Merge pull request #7159 from OpenLiberty/staging

Staging to vNext doc edits

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]

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

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,14 +25,35 @@ 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]
 ----
 @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:
 
 ----
 <applicationMonitor dropinsEnabled="false" />
 ----
 
-=== 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:
 
 ----
 <application-bnd>