diff --git a/modules/ROOT/pages/authentication-filters.adoc b/modules/ROOT/pages/authentication-filters.adoc index 2a1459bffb..797a8f220e 100644 --- a/modules/ROOT/pages/authentication-filters.adoc +++ b/modules/ROOT/pages/authentication-filters.adoc @@ -39,4 +39,6 @@ For more information, see xref:reference:config/authFilter.adoc[the authFilter e == See also * xref:reference:feature/spnego-1.0.adoc#_apply_spnego_authentication_to_a_subset_of_http_requests[Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO): Apply SPNEGO authentication to a subset of HTTP requests] -* xref:reference:feature/mpJwt-1.1.adoc#_specify_login_with_microprofile_jwt_for_a_subset_of_applications_urls_browsers_or_ip_addresses[MicroProfile JSON Web Token: Specify login with Micrprofile JSON Web Token for only a subset of applications, URLs, browsers, or IP addresses] +* xref:reference:feature/mpJwt-1.1.adoc#_configure_authentication_filter_to_login_with_microprofile_jwt[MicroProfile JSON Web Token: Specify login with Micrprofile JSON Web Token for only a subset of applications, URLs, browsers, or IP addresses] + +* xref:reference:feature/samlWeb/examples.adoc#authfilter[Configure SAML authentication for a subset of requests] diff --git a/modules/ROOT/pages/authentication.adoc b/modules/ROOT/pages/authentication.adoc index 30d1a36d0b..1faa3bc7a3 100644 --- a/modules/ROOT/pages/authentication.adoc +++ b/modules/ROOT/pages/authentication.adoc @@ -8,18 +8,18 @@ // :page-description: :seo-title: Authentication -:seo-description: Authentication is the processes by which an application that is running on Open Liberty confirms a user's identity. +:seo-description: Authentication is the process by which an application that is running on Open Liberty confirms a user's identity. :page-layout: general-reference :page-type: general = Authentication For an application to be secure, it must be able to determine who its users are. Authentication is the process of confirming a user’s identity. -Open Liberty authenticates users by collecting credentials from them, such as a username and password, and checking these credentials against a configured user registry. Authentication is completed in different ways, depending on the details of an application and the resources that are available to it. For microservice-based applications, authentication must be lightweight and configurable, since any user request might need to authenticate to multiple services. In many cases, a user's credentials are placed in a token that can be passed from the server to different services to authenticate requests for protected resources. +Open Liberty authenticates users by collecting credentials from them, such as a username and password, and checking these credentials against a user registry. Authentication is completed in different ways, depending on the details of an application and the resources that are available to it. For microservice-based applications, authentication must be lightweight and configurable, since any user request might need to authenticate to multiple services. In many cases, a user's credentials are placed in a token that can be passed from the server to different services to authenticate requests for protected resources. For example, a user of a streaming music service might want to listen to a song, learn about the artist, and get recommendations for similar artists. Each of these tasks requires access to a different service, but authenticating to each service separately expends time and resources. Open Liberty supports a number of different mechanisms for single sign-on (SSO) authentication so that a user or service authenticates only one time to access the various resources in an application. For example, the feature:socialLogin[display=Social Media Login] feature enables users of an application that is running on Open Liberty to authenticate with social media credentials. After authentication, an application can either construct a JSON Web Token (JWT) or obtain one from the social media service or associated SSO identity provider. Open Liberty provides the feature:jwt[display=JSON Web Token] feature to construct JWTs for an application on the server. This JWT can then authenticate the user to other services that the application communicates with. -The following diagram shows the authentication process when a user requests access to protected resources from an application that is running on an Open Liberty server: +The following diagram shows the authentication process when a user requests access to protected resources from an application that is running on Open Liberty: .Authentication and authorization image::authn-ol-diagram-2.png[diagram that shows the flow of an authentication request,align="center"] @@ -69,14 +69,15 @@ Open Liberty supports various solutions for SSO authentication, including the fo === The authentication cache -Because the creation of a subject might affect performance, Open Liberty provides an authentication cache to store a subject after a user authentication is successful. This cache is available by default when the feature:appSecurity[display=Application Security (Jakarta Security)] feature is enabled in your `server.xml` file. You can customize the details of the authentication cache by specifying the config:authCache[] element. +Because the creation of a subject might affect performance, Open Liberty provides an authentication cache to store a subject after a successful user authentication. This cache is available by default when the feature:appSecurity[display=Application Security (Jakarta Security)] feature is enabled in your `server.xml` file. You can customize the details of the authentication cache by specifying the config:authCache[] element. You can also configure a distributed authentication cache that is shared among a group of Open Liberty servers that use the same set of users and groups by using JCache. For more information, see xref:authentication-cache.adoc[Configure the authentication cache]. === The logged-out cookie cache -If a single sign-on (SSO) cookie for a logged-out user is persisted and presented to the server again, it is validated based on the expiration time and the LTPA encryption keys. However, you can configure the server to track logged-out SSO cookies so that if they are presented again, the user must authenticate again. You can track logged-out SSO cookies on a single server or across multiple servers that share SSO data and configuration. For more information, see xref:track-loggedout-sso.adoc[Track logged-out SSO cookies]. + +If an SSO cookie for a logged-out user is persisted and presented to the server again, it is validated based on the expiration time and the LTPA encryption keys. However, you can configure the server to track logged-out SSO cookies so that if they are presented again, the user must authenticate again. You can track logged-out SSO cookies on a single server or across multiple servers that share SSO data and configuration. For more information, see xref:track-loggedout-sso.adoc[Track logged-out SSO cookies]. == See also - The feature:appSecurity[display=Application Security (Jakarta Security)] feature diff --git a/modules/ROOT/pages/authorization.adoc b/modules/ROOT/pages/authorization.adoc index 0df5752ad9..fc74002dd6 100644 --- a/modules/ROOT/pages/authorization.adoc +++ b/modules/ROOT/pages/authorization.adoc @@ -16,7 +16,7 @@ For an application to be secure, it must manage access to protected resources. Authorization determines which resources a user can access. In applications where only certain users are entitled to access certain resources, users and groups are assigned roles that correspond to the resources that they can access. Authorization determines a user's role and the permissions that role includes. -For example, in a payroll application, users in the `Employee` role can view a page that lists their hourly wages and hours worked. +For example, in a payroll application, users in the `Employee` role can view a page that lists their hourly wages and the hours they worked. However, only users in the `Manager` role can edit employee wages. During xref:authentication.adoc[authentication], Open Liberty identifies users and determines what access groups they belong to. When a user attempts to access a protected resource on the server, this information determines whether the user is authorized to access the resource. @@ -25,6 +25,12 @@ In addition to configuring authorization to application resources, you can confi == Define roles in your application +To secure access to application resources, you can specify roles for different resources in your application source code. How you specify these roles generally depends on whether you are securing front-end or back-end resources. + +=== Securing back-end resources with the `@RolesAllowed` annotation + +The `@RolesAllowed` annotation typically specifies role-based access to back-end application resources, such as calls to a database. + You can specify which roles can access an application resource by setting the `@RolesAllowed` annotation on a class or method in the source code, as shown in the following example: [source,java] @@ -32,7 +38,22 @@ You can specify which roles can access an application resource by setting the `@ @RolesAllowed({ "admin", "user" }) ---- -You can map the roles that are declared in the application to existing groups from a user registry or SSO identity provider. To map the roles, you can specify the `security-role` element within the `application-bnd` element in the `server.xml` file, as shown in the following example: +[#servlet] +=== Securing front end resources with servlet security roles + +To control authorization for front-end resources, such as HTTP calls, you can specify roles by configuring the `@ServletSecurity` annotation on a class in the servlet code. You can specify the permissible roles with the `rolesAllowed` attribute on the `@HttpConstraint` or `@HttpMethodConstraint` parameters. The `@HttpMethodConstraint` parameter specifies constraints for specific HTTP methods. The `@HttpConstraint` parameter specifies the default constraints for all HTTP methods that are not otherwise specified by the `@HttpMethodConstraint` parameter. + +In the following example, the `@HttpConstraint` parameter specifies that all HTTP methods are constrained either to the `user` role or the `admin` role. The `@HttpMethodConstraint` parameter specifies that the `POST` method is constrained only to users who are in the `admin` role: + +[source,java] +---- +@ServletSecurity (value = @HttpConstraint(rolesAllowed = { "user", "admin" }), + httpMethodConstraints = {@HttpMethodConstraint(value = "POST", rolesAllowed = {"admin"})}) +---- + +=== Mapping roles to SSO groups + +You can map the roles that are declared in the application to existing groups from a user registry or SSO identity provider. To map the roles, you can specify the `security-role` element within the config:application-bnd[] element in the `server.xml` file, as shown in the following example: [source,xml] ---- @@ -48,48 +69,35 @@ You can map the roles that are declared in the application to existing groups fr ---- The `name` attribute of the `security-role` element corresponds to a role that is specified in the application to control access to resources. The `name` attributes of the `group` elements correspond to the groups that are specified by a user registry or SSO identity provider. -If the role names match the group names exactly, the server maps the group to the role with a matching name by default. +If the role names match the group names exactly, Open Liberty maps the group to the role with a matching name by default. If you use this default mapping, you do not need to specify an `application-bnd` element in the `server.xml` file. In some cases, an application needs to know only the user’s authentication status. In such cases, you can specify the `**` value as the role name in the `@RolesAllowed` annotation. This value denotes that any authenticated user can access a resource. -You can also authorize all users by setting the `@PermitAll` annotation on a class or method in the application code The `@PermitAll` annotation specifies that anyone can access a resource, even users who are not authenticated. +You can also authorize all users by setting the `@PermitAll` annotation on a class or method in the application code. The `@PermitAll` annotation specifies that anyone can access a resource, even users who are not authenticated. For more information, see the link:/guides/microprofile-jwt.html#securing-the-system-service[Securing the inventory service section of the guide to Securing microservices with JSON Web Tokens]. +=== Role-mapping limitations with the dropins directory + Open Liberty provides a `dropins` directory, which is automatically monitored by the server. If you put an application into this directory, the application is automatically deployed on the server. Similarly, if the application is deleted from the directory, the application is automatically removed from the server. The `dropins` directory can be used for applications that do not require security role mapping or other extra configuration in the `server.xml` file. However, if you specify the `application-bnd` element in your server.xml file to configure security role mapping, your application must not be in the `dropins` directory. If you leave your application in the `dropins` directory, then you must disable application monitoring by adding the following code in your `server.xml` file: ---- ---- -=== Configure servlet security roles - -The `@RolesAllowed` annotation typically specifies role-based access to back-end application resources, such as calls to a database. -To control authorization for front-end resources, such as HTTP calls, you can specify roles by configuring the `@ServletSecurity` annotation on a class in the servlet code. You can specify the permissible roles with the `rolesAllowed` attribute on the `@HttpConstraint` or `@HttpMethodConstraint` parameters. The `@HttpMethodConstraint` parameter specifies constraints for specific HTTP methods. The `@HttpConstraint` parameter specifies the default constraints for all HTTP methods that are not otherwise specified by the `@HttpMethodConstraint` parameter. - -In the following example, the `@HttpConstraint` parameter specifies that all HTTP methods are constrained either to the `user` role or the `admin` role. The `@HttpMethodConstraint` parameter specifies that the `POST` method is constrained only to users who are in the `admin` role: - -[source,java] ----- -@ServletSecurity (value = @HttpConstraint(rolesAllowed = { "user", "admin" }), - httpMethodConstraints = {@HttpMethodConstraint(value = "POST", rolesAllowed = {"admin"})}) ----- - - For more information, see link:/guides/security-intro.html#adding-authentication-and-authorization[the Adding authentication and authorization section of the Securing a web application guide]. - -=== Authorize requests between web services +== Authorize requests between web services Authorization occurs not only between users and applications, but also between microservices within an application. When one service requests data from another, the requesting service often must demonstrate that it is authorized to access the data. xref:single-sign-on.adoc#_json_web_token_jwt[Token-based authorization], such as with a JSON Web Token (JWT), provides a lightweight way for security controls and security tokens to propagate user identities and roles across different services. Open Liberty supports token-based authorization through the feature:jwt[display=MicroProfile JWT feature]. -=== Configure authorization with a deployment descriptor file +== Configure authorization with a deployment descriptor file Although annotations are the most common way to define roles in microservices, you can also define roles by specifying `security-constraint` elements in a `web.xml` deployment descriptor file. This configuration might be necessary in situations where you want to keep the security configuration separate from the development environment and apply it at deployment time. @@ -98,7 +106,7 @@ Some applications rely on a combination of declarative annotations and a deploym Therefore, you can specify roles in a deployment descriptor file if you want to override security settings or defaults from elsewhere in the application code. For more information, see link:/guides/security-intro.html#adding-authentication-and-authorization[the Adding authentication and authorization section of the Securing a web application guide]. -=== Configure calls to run under a specific caller identity +== Configure calls to run under a specific caller identity When a user is authenticated to a servlet, the servlet can make subsequent calls to downstream resources, such as other servlets or EJB components. These subsequent calls are normally made under the same security identity that was used to log in to the servlet. This identity is known as the caller identity. Alternatively, you can delegate any subsequent calls to a different caller identity. @@ -110,7 +118,7 @@ For example, consider a servlet that requires either the `admin` or `user` role @RunAs("admin") @RolesAllowed({ "admin", "user" }) ---- -For more information, see the xref:reference:javadoc/liberty-javaee8-javadoc.adoc#package=javax/annotation/security/package-frame.html&class=javax/annotation/security/RunAs.html[@RunAs annotation]. +For more information, see the xref:reference:javadoc/liberty-jakartaee10-javadoc.html?package=allclasses-frame.html&class=jakarta/annotation/security/RunAs.html[@RunAs annotation]. Alternatively, in the following `web.xml` deployment descriptor file example, the `run-as` element specifies that the servlet makes calls under the `admin` role that is defined in the server configuration: @@ -128,7 +136,7 @@ Alternatively, in the following `web.xml` deployment descriptor file example, th To delegate calls that are made from a security role to a particular caller identity, specify the `run-as` element in the security role configuration in your `server.xml` file. For example, the servlet from the previous example needs to call to downstream resources that require a particular caller identity with the username `Wanda`. You can set the `run-as` element on the `admin` security role to specify that calls that are made in that role must use this caller identity. -In the following `server.xml` file example, the `run-as` element specifies that calls under the `admin` security role are run under the caller identity with the `Wanda` username : +In the following `server.xml` file example, the `run-as` element specifies that calls under the `admin` security role are run under the caller identity with the `Wanda` username: ---- diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index c797c60a8e..f52b2829ec 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -12,25 +12,23 @@ :page-type: general = API documentation with OpenAPI -MicroProfile OpenAPI is a MicroProfile community programming model for the OpenAPI specification. -MicroProfile OpenAPI helps you to generate structured documentation from your JAX-RS applications. +MicroProfile OpenAPI helps you to generate structured documentation from your Jakarta RESTful Services or JAX-RS applications. This documentation helps other microservices and developers to understand and communicate with your application. -Structured documentation helps other microservices and developers to understand and communicate with your application. Other developers need relevant information to build an application that communicates with the REST API of your application. MicroProfile OpenAPI facilitates this communication by generating human and machine-readable documentation on a simple interface that doesn’t require access to the source code. -You can implement MicroProfile OpenAPI for Open Liberty by enabling the feature:mpOpenAPI[display=MicroProfile OpenAPI] feature. + +You can implement MicroProfile OpenAPI for Open Liberty by enabling the feature:mpOpenAPI[display=MicroProfile OpenAPI] feature. When this feature is enabled, you can view the OpenAPI document in a browser by using the `/openapi` endpoint. For example, if your browser is on the same machine where your server is running, you can view the raw OpenAPI document at the `\http://localhost:9080/openapi` URL or view the OpenAPI document in a user interface at the `\http://localhost:9080/openapi/ui` URL. + +To explore how to document and filter RESTful APIs from code or static files by using Open Liberty and MicroProfile OpenAPI, see the link:/guides/microprofile-openapi.html[Documenting RESTful APIs] guide. The two main approaches to generate an OpenAPI document are the code-first approach and the design-first approach. -In the code-first approach, a developer can generate documentation of the REST API from the source code. +In the code-first approach, you can generate documentation of the REST API from the source code. The reference document that is produced lists all the API endpoints with descriptions of how to use them. Alternatively, in the design-first approach, you can include a pre-generated OpenAPI document that was written separately from the code. The JAX-RS framework handles basic API generation for JAX-RS annotations and generates a skeleton OpenAPI treemap. You can use this treemap as a starting point and augment it with annotations and code to produce a complete OpenAPI document. Additionally, you can use this manually created documentation to generate stubs, or testable versions of code modules, such as client libraries for the API. -Some deprecated annotations were removed between Microprofile OpenAPI versions 1.1 and 2.0, which might result in breaking changes between those versions. -For more information, see the https://download.eclipse.org/microprofile/microprofile-open-api-2.0/microprofile-openapi-spec-2.0.html#release_notes_20[Release Notes for Microprofile OpenAPI 2.0]. - == The code-first approach In the code-first approach, you can initially generate basic API documentation of the REST API from annotations that are specified in the source code. @@ -112,7 +110,7 @@ The following OpenAPI document is generated in YAML format from the OpenAPI anno The information that is provided through the OpenAPI annotations augments the basic API documentation that is generated by the JAX-RS framework. -For more information, see the xref:reference:javadoc/microprofile-4.1-javadoc.adoc#package=org/eclipse/microprofile/openapi/annotations/package-frame.html&class=org/eclipse/microprofile/openapi/annotations/package-summary.html[MicroProfile OpenAPI Javadoc] for the available annotations. +For more information, see the link:reference/javadoc/microprofile-6.1-javadoc.html?package=org/eclipse/microprofile/openapi/package-frame.html&class=org/eclipse/microprofile/openapi/package-summary.html[MicroProfile OpenAPI Javadoc] for the available annotations. == The design-first approach @@ -128,17 +126,6 @@ You can augment manually created API documents by adding annotations to the code For more information, see https://openliberty.io/guides/microprofile-openapi.html#using-pregenerated-openapi-documents[Using pregenerated OpenAPI documents]. -== Filter components in and out of API documentation - -If you want to update or remove certain elements and fields of the OpenAPI document you can use a filter, which is called one time after all other documentation mechanisms are finished. -Filters give the users the flexibility to modify the document. -With filters, you can implement an interface in your application. -When a component of the documentation is processed, it calls your implementation and you can either add or remove content. -For more information, see https://openliberty.io/guides/microprofile-openapi.html#filtering-the-openapi-tree-elements[Filtering the OpenAPI tree elements]. - -== View API documentation - -The OpenAPI document can be viewed in a browser by using the `/openapi` endpoint. For example, if your browser is on the same machine where your server is running, you can view the OpenAPI document at the http://localhost:9080/openapi or the http://localhost:9080/openapi/ui URL. [#multi-module] == Multiple application and multi-module application support with MicroProfile OpenAPI @@ -209,8 +196,8 @@ When OpenAPI documentation from multiple modules is merged into a single documen - If the `externalDocs` section is not the same across all documents, it is removed from the final document. + == See also -- link:/guides/microprofile-openapi.html[Guide: Documenting RESTful APIs] +- - Guide: link:/guides/microprofile-config-intro.html[Separating configuration from code in microservices] -- link:https://download.eclipse.org/microprofile/microprofile-open-api-2.0/microprofile-openapi-spec-2.0.html#release_notes_20[Release Notes for MicroProfile OpenAPI 2.0] diff --git a/modules/reference/nav.adoc b/modules/reference/nav.adoc index ac83432ae0..28adbc8c4b 100644 --- a/modules/reference/nav.adoc +++ b/modules/reference/nav.adoc @@ -60,6 +60,7 @@ include::reference:partial$feature-nav.adoc[] ** xref:javadoc/liberty-javaee7-javadoc.adoc[Java EE 7] * xref:microprofile-api.adoc[MicroProfile API] + ** xref:javadoc/microprofile-6.1-javadoc.adoc[MicroProfile 6.1] ** xref:javadoc/microprofile-6.0-javadoc.adoc[MicroProfile 6.0] ** xref:javadoc/microprofile-5.0-javadoc.adoc[MicroProfile 5.0] ** xref:javadoc/microprofile-4.1-javadoc.adoc[MicroProfile 4.1] @@ -82,4 +83,4 @@ include::reference:partial$feature-nav.adoc[] include::reference:partial$feature-nav-api-openliberty.adoc[] -include::reference:partial$feature-nav-spi-openliberty.adoc[] \ No newline at end of file +include::reference:partial$feature-nav-spi-openliberty.adoc[] diff --git a/modules/reference/pages/feature/mpJwt/examples.adoc b/modules/reference/pages/feature/mpJwt/examples.adoc index e9ca8b3e3c..eabba87863 100644 --- a/modules/reference/pages/feature/mpJwt/examples.adoc +++ b/modules/reference/pages/feature/mpJwt/examples.adoc @@ -1,12 +1,8 @@ == Examples -=== Configure MicroProfile JWT +=== Configure authentication with MicroProfile JWT -The following example shows authentication with a JSON Web Token (JWT). -The `mpJwt` element defines the configuration to process the inbound JSON Web Tokens. -The `jwksUri` attribute points the `mpjwt` element towards the public key `https://localhost:19443/jwt/ibm/api/myBuilder/jwk`, to validate the JWT. -The `keyStore` element defines the keystore and truststore where the public key is stored. -The `keyStore` element validates the JSON Web Token when the JSON Web Key Set (JWKS) is not used: +The following example shows how to configure authentication with a JSON Web Token (JWT) in your `server.xml` file. [source,xml] ---- @@ -15,19 +11,22 @@ The `keyStore` element validates the JSON Web Token when the JSON Web Key Set (J ---- +* The `mpJwt` element defines the configuration to process the inbound JWTs. +* The `jwksUri` attribute points the `mpjwt` element to the `\https://localhost:19443/jwt/ibm/api/myBuilder/jwk` JWK endpoint URL. The Liberty runtime obtains the public keys to verify the JWT from this endpoint. +* The `keyStore` element defines the keystore where the public key is stored. This element validates the JWT when the JSON Web Key Set (JWKS) is not used. -In MicroProfile JSON Web Token 1.1 and later, this configuration is optional and you can also use MicroProfile Config properties to configure MicroProfile JWT. For more information, see link:/guides/microprofile-jwt.html[Guide: Securing microservices with JSON Web Tokens]. +In MicroProfile JSON Web Token 1.1 and later, this configuration is optional and you can xref:ROOT:microprofile-config-properties.adoc#jwt[use MicroProfile Config properties to configure MicroProfile JWT] instead. For more information, see link:/guides/microprofile-jwt.html[Guide: Securing microservices with JSON Web Tokens]. -=== Configure authentication filter to login with MicroProfile JWT +=== Configure an authentication filter to log in with MicroProfile JWT -You can use an authentication filter to protect a subset of applications, URLs, or IP addresses. -The security configuration works when the conditions in the filter are met. +You can use an xref:ROOT:authentication-filters.adoc[authentication filter] to protect a subset of applications, URLs, or IP addresses with MicroProfile JWT. +The security configuration uses MicroProfile JWT when the conditions in the filter are met. In the following example, any requests to the `myApp` application are authenticated with the `mpJwt` feature. -The `authFilterRef` attribute that is named `myAuthFilter` filters the login requests to the `myApp` application: +The `authFilterRef` attribute that is named `myAuthFilter` filters the login requests to the `myApp` application: [source,xml] ---- - + ---- -The `id` attribute in the `keyStore` element specifies the `“defaultTrustStore”` value to configure a truststore within the keystore. A truststore contains the certificates that are used to validate the requests that are sent to applications with JSON Web Tokens. The `ssl` element is used to specify how the application validates the SSL connection to a server. Within the `ssl` element, the `id` attribute specifies the `"defaultSSLConfig"` value that sets the SSL configuration as the default SSL configuration for the server that the application connects to. The `trustStoreRef` attribute specifies the `“defaultTrustStore”` value that configures the `ssl` element to reference the truststore so that the application recognizes the truststore when it attempts to connect to the server. The `jwksUri` attribute specifies the `"https://localhost:19443/jwt/ibm/api/myBuilder/jwk”` JWK endpoint URL value that the server uses to obtain the public keys from to verify the JWT. +* The `id` attribute in the `keyStore` element specifies the `“defaultTrustStore”` value to configure a truststore within the keystore. A truststore contains the certificates that are used to validate the requests that are sent to applications with JWTs. +* The `ssl` element specifies how the application validates the SSL connection to a server. Within the `ssl` element, the `id` attribute specifies the `"defaultSSLConfig"` value that sets the SSL configuration as the default SSL configuration for the server that the application connects to. +* The `trustStoreRef` attribute specifies the `defaultTrustStore` value to reference the `ssl` element configuration so that the application recognizes the truststore when it attempts to connect to the server. +* The `jwksUri` attribute specifies the `\https://localhost:19443/jwt/ibm/api/myBuilder/jwk` JWK endpoint URL where the server obtains the public keys to verify the JWT. -=== Configure the restriction of MicroProfile JWT authentication +=== Configure MicroProfile JWT authentication for only certain applications By default, if the MicroProfile JWT feature is configured, all authorized requests from applications must include a valid JSON Web Token in the HTTP header of the API. To modify the default behavior to require JSON Web Tokens in only some applications, you can set the `ignoreApplicationAuthMethod` attribute to `“false”` in the `mpJwt` element, as shown in the following example: @@ -58,36 +60,39 @@ By default, if the MicroProfile JWT feature is configured, all authorized reques ---- -After you modify the authorization behavior, you can use either of two options to configure applications to use MicroProfile JWT as a login method. In the API, you can add a `@LoginConfig` annotation that contains the `authMethod` attribute to specify MicroProfile JWT as the authentication method as shown in the following example: +After you modify the authorization behavior, you can use either of two options to configure applications to use MicroProfile JWT as a login method. In the API, you can add a `@LoginConfig` annotation that contains the `authMethod` attribute to specify MicroProfile JWT as the authentication method, as shown in the following example: [source,java] ---- @LoginConfig(authMethod = "MP-JWT", realmName = "MP-JWT") ---- -You can also add `MP-JWT` to the `auth-method` element of the `web.xml` file to specify MicroProfile JWT as the authentication method in the `login-config` element, as shown in the following example: +Alternatively, ypu can configure MicroProfile JWT authorization in the web.xml file. Specify `MP-JWT` as the value for the `auth-method` sub-element in the `login-config` element, as shown in the following example: [source,xml] ---- - MP-JWT MP-JWT + + MP-JWT + MP-JWT + ---- === Define role mapping for MicroProfile JWT -By default, JSON Web Tokens use the `upn` claim from the JWT as the principal name and unique security name of the user. JSON Web Tokens also use the `groups` claim from the JWT as the group name for security role mapping. To change the default mapping, you can use the `userNameAttribute` attribute to choose a claim for the user principal. You can also use the `groupNameAttribute` attribute to choose a claim for the group name, as shown in the following example: +By default, JSON Web Tokens use the `upn` claim from the JWT as the principal name and unique security name of the user. JWTs also use the `groups` claim from the JWT as the group name for security role mapping. To change the default mapping, you can use the `userNameAttribute` attribute to choose a claim for the user principal. You can also use the `groupNameAttribute` attribute to choose a claim for the group name, as shown in the following example: [source,xml] ---- - + ---- === Validate MicroProfile JWT claims with the user registry -By default, JSON Web Tokens authenticate user claims without validation from the user registry. To modify this behavior, you can set the `mapToUserRegistry` attribute to `true` in the the `mpJwt` element, as shown in the following example: +By default, JSON Web Tokens authenticate user claims without validation from the user registry. To modify this behavior, you can set the `mapToUserRegistry` attribute to `true` in the `mpJwt` element, as shown in the following example: [source,xml] ---- ---- -When you set the `mapToUserRegistry` attribute to `true`, JSON Web Tokens are forced to validate user claims with the user registry. The user claims are validated based on the user attributes that are contained in the user registry. \ No newline at end of file +When you set the `mapToUserRegistry` attribute to `true`, JWTs are forced to validate user claims based on the user attributes that are contained in the user registry. diff --git a/modules/reference/pages/feature/mpOpenAPI-1.1/description.adoc b/modules/reference/pages/feature/mpOpenAPI-1.1/description.adoc new file mode 100644 index 0000000000..99a2c24649 --- /dev/null +++ b/modules/reference/pages/feature/mpOpenAPI-1.1/description.adoc @@ -0,0 +1,2 @@ +Some deprecated annotations were removed between Microprofile OpenAPI versions 1.1 and 2.0, which might result in breaking changes between those versions. +For more information, see the https://download.eclipse.org/microprofile/microprofile-open-api-2.0/microprofile-openapi-spec-2.0.html#release_notes_20[Release Notes for Microprofile OpenAPI 2.0]. diff --git a/modules/reference/pages/feature/mpOpenAPI-2.0/description.adoc b/modules/reference/pages/feature/mpOpenAPI-2.0/description.adoc new file mode 100644 index 0000000000..99a2c24649 --- /dev/null +++ b/modules/reference/pages/feature/mpOpenAPI-2.0/description.adoc @@ -0,0 +1,2 @@ +Some deprecated annotations were removed between Microprofile OpenAPI versions 1.1 and 2.0, which might result in breaking changes between those versions. +For more information, see the https://download.eclipse.org/microprofile/microprofile-open-api-2.0/microprofile-openapi-spec-2.0.html#release_notes_20[Release Notes for Microprofile OpenAPI 2.0]. diff --git a/modules/reference/pages/feature/samlWeb/examples.adoc b/modules/reference/pages/feature/samlWeb/examples.adoc index 1b0f59cb71..2088625d24 100644 --- a/modules/reference/pages/feature/samlWeb/examples.adoc +++ b/modules/reference/pages/feature/samlWeb/examples.adoc @@ -24,9 +24,9 @@ This endpoint on the service provider (SP) point of contact server receives asse - The service provider metadata URL endpoint: `\https://:/ibm/saml20/defaultSP/samlmetadata` + -This endpoint provides configuration information for the service provider. -You can download the metadata for the service provider from a browser with the service provider metadata URL. -You can also provide the service provider metadata URL to the SAML IdP to establish a federation between the SP and IdP. +This endpoint provides configuration information for the SP. +You can download the metadata for the SP from a browser with the SP metadata URL. +You can also provide the SP metadata URL to the SAML IdP to establish a federation between the SP and IdP. The IdP metadata file must be named `idpMetadata.xml` and copied to the `resources/security` directory on the server. @@ -84,7 +84,7 @@ If the request meets the criteria that are specified in the authentication filte In this example, request URLs that contain the `/SimpleServlet` pattern are authenticated by using SAML SSO authentication. If the SAML Web Single Sign-On feature is enabled but no authentication filter is configured, all unauthenticated requests are processed by SAML authentication. -You can also configure multiple SP and IdP federation partners by creating multiple `samlWebSso20` elements and associating each of them with a unique config:authFilter[] element. In this case, all `authFilters` must exclude each other. When multiple `samlWebSso20` elements are configured, each element can implement single-sign-on with its specified federated IdP and according to its own authentication policy and rules. The following example shows a two mutually exclusive SAML configurations, each of which uses a different authentication filter to control the kinds of requests that it processes. +You can also configure multiple SP and IdP federation partners by creating multiple `samlWebSso20` elements and associating each of them with a unique config:authFilter[] element. In this case, all `authFilters` must exclude each other. When multiple `samlWebSso20` elements are configured, each element can implement single sign-on with its specified federated IdP and according to its own authentication policy and rules. The following example shows two mutually exclusive SAML configurations, each of which uses a different authentication filter to control the kinds of requests that it processes. [source, xml] ---- @@ -139,8 +139,8 @@ The following example configuration demonstrates how to configure inbound propag === Configure identity provider-initiated unsolicited single sign-on Open Liberty SAML SP supports IdP-initiated unsolicited SSO with and without the requirement of IdP metadata on-premises. If you do not have IdP metadata, or if you intend to use unsolicited SSO to federate with multiple identity providers with one Liberty SP, you must add the following configurations. -- Configure the `PKIXTrustEngine` subelement and import all the IdP signer certificates to the default truststore of the Liberty server, or to the trustAnchor of the PKIXTrustEngine. -- Configure the `trustedIssuers` attribute to list the issuer name of the IdP as it appears in the SAML assertion. The issuer name is used as the EntityID in the metadata. +- Configure the `PKIXTrustEngine` subelement and import all the IdP signer certificates to the default truststore of the Liberty server, or to the `trustAnchor` location of the `pkixTrustEngine` configuration. +- Configure the `trustedIssuers` attribute to list the issuer name of the IdP as it appears in the SAML assertion. The issuer name is used as the `EntityID` value in the metadata. The following example demonstrates the `server.xml` file configuration to specify IdP-initiated SSO, where the IdP signer certificates are in a file that is specified in the `serverStore` keystore configuration. @@ -172,8 +172,8 @@ To configure this scenario, set the `loginPageURL` attribute to a URL that can i [#ltpa] === Configure an SP authentication session and session cookie -After SAML assertion is verified and processed, the Liberty SAML SP maintains an authenticated session between the browser and the SP without using an LTPA cookie. The authenticated session timeout is set to `SessionNotOnOrAfter` value from the `saml:AuthnStatement` element, if one is presented, or to the `sessionNotOnOrAfter` attribute as configured in the server.xml file. The default value is 120 minutes. -The session cookie name is automatically generated, and you can customize the cookie name by using the attribute `spCookieName`, as shown in the following example. +After the SAML assertion is verified and processed, the Liberty SAML SP maintains an authenticated session between the browser and the SP without using an LTPA cookie. The authenticated session timeout is set to the `SessionNotOnOrAfter` value from the `saml:AuthnStatement` element, if one is presented, or to the `sessionNotOnOrAfter` attribute, as configured in the `server.xml` file. The default value is 120 minutes. +The session cookie name is automatically generated, and you can customize the cookie name by using the `spCookieName` attribute, as shown in the following example. [source,xml] ---- @@ -197,9 +197,9 @@ The Open Liberty SAML Single Logout Service URL takes the following format: `\ht For IdP-initiated single logout, no additional configuration step is required. The Open Liberty SP listens on the Single Logout Service URL and automatically responds to any single logout request. -However, Open Liberty also supports service provider-initiated single logout. When you set the `spLogout` attribute to `true` both the `ibm_security_logout` URL and the `HttpServletRequest.logout()` method are upgraded to implement SAML single logout. +However, Open Liberty also supports service provider-initiated single logout. When you set the `spLogout` attribute to `true`, both the `ibm_security_logout` URL and the `HttpServletRequest.logout()` method are upgraded to implement SAML single logout. [source,xml] ---- ----- \ No newline at end of file +---- diff --git a/modules/reference/pages/feature/socialLogin/examples.adoc b/modules/reference/pages/feature/socialLogin/examples.adoc index 919a119323..15cf055f62 100644 --- a/modules/reference/pages/feature/socialLogin/examples.adoc +++ b/modules/reference/pages/feature/socialLogin/examples.adoc @@ -164,20 +164,32 @@ The following example shows how to use a private key JWT for client authenticati [#openshiftservice] === Use OpenShift service accounts to authenticate and authorize protected resource requests -The Social Media Login feature can be configured to use OpenShift service accounts to authenticate and authorize protected resource requests. -With this configuration, server administrators can secure endpoints, for example, monitoring and metrics endpoints, that might produce sensitive information. +You can configure the Social Media Login feature to use OpenShift service accounts to authenticate and authorize protected resource requests. +With this configuration, you can secure endpoints that might produce sensitive information, such as monitoring and metrics endpoints. + The service accounts can authenticate themselves by providing a service account token that was created within the OpenShift cluster in the request. -The following example shows how to configure the Social Media Login feature to use OpenShift service accounts as a single sign-on provider. +The following `server.xml` file example shows how to configure the Social Media Login feature to use OpenShift service accounts as a single sign-on provider. + [source,xml] ---- - - ---- +When the Liberty runtime is packaged and deployed within an OpenShift cluster, The minimum configuration requires only an config:okdServiceLogin[] element. + The `okdServiceLogin` element authenticates all protected resource requests received by Open Liberty. -The OpenShift project that the service account is in, is used as the group for the service account for authorization decisions. + +Incoming requests to protected resources must include a service account token. The token must be specified as a bearer token in the `Authorization` header of the request. The Liberty runtime uses the service account token to query information about the associated service account from the OpenShift cluster. The OpenShift project that is associated with the service account is used as the group for the service account for authorization decisions. Similarly, the name of the service account is used as the username. + +If the Liberty runtime is not deployed within an OpenShift cluster, configure the `userValidationApi` attribute to the value for the appropriate User API endpoint in the OpenShift cluster: + +[source,xml] +---- + +---- + +You can configure multiple `okdServiceLogin` elements as long as each element specifies a unique `id` attribute. In those cases, configure xref:ROOT:authentication-filters.adoc[authentication filters] to ensure the appropriate endpoints are protected by a unique `okdServiceLogin` instance. [#activedirectory] === Use Active Directory as an authentication provider diff --git a/modules/reference/pages/javadoc/microprofile-6.1-javadoc.adoc b/modules/reference/pages/javadoc/microprofile-6.1-javadoc.adoc new file mode 100644 index 0000000000..6040ae3777 --- /dev/null +++ b/modules/reference/pages/javadoc/microprofile-6.1-javadoc.adoc @@ -0,0 +1,15 @@ +// Copyright (c) 2023 IBM Corporation and others. +// Licensed under Creative Commons Attribution-NoDerivatives +// 4.0 International (CC BY-ND 4.0) +// https://creativecommons.org/licenses/by-nd/4.0/ +// +// Contributors: +// IBM Corporation +// +:page-layout: javadoc += MicroProfile 6.1 + +++++ + +++++