Merge branch 'docs-staging' into anax-v2.12-whatsnewsection-docs

Signed-off-by: anaxceron <[email protected]>

.github/dco.yml

@@ -0,0 +1,3 @@
+allowRemediationCommits:
+  individual: true
+  thirdParty: true

dco_signoffs/Lobhas-Paradkar-docs-site.txt

@@ -0,0 +1,3 @@
+I, Lobhas Paradkar, hereby sign-off-by all of my past commits to this repo subject to the Developer Certificate of Origin (DCO), Version 1.1. 
+In the past I have used email: [email protected]
+41febb79fe07ae4670a746301b7215740e65a3c7 updated release notes 2.12 (#3203)

dco_signoffs/Pablo-Carle-docs-site.txt

@@ -0,0 +1,2 @@
+I, Pablo Carle, hereby sign-off-by all of my past commits to this repo subject to the Developer Certificate of Origin (DCO), Version 1.1. In the past I have used emails: [email protected], [email protected]
+3f0d3888423905a60aa72bc0e4ee8be31ce7834e Add comments for review around configuration section (#3246)

dco_signoffs/Sergei-Kurnevich-docs-site.txt

@@ -0,0 +1,3 @@
+I, Sergei Kurnevich, hereby sign-off-by all of my past commits to this repo subject to the Developer Certificate of Origin (DCO), Version 1.1. In the past I have used emails: [email protected]
+
+3b9ecfb727b8b0081cea8a3a395d278c1c26de42 ZIS load module typo fix (#3258)

dco_signoffs/Wen-Ting-Su-docs-site.txt

@@ -0,0 +1,6 @@
+I, Wen Ting Su, hereby sign-off-by all of my past commits to this repo subject to the Developer Certificate of Origin (DCO), Version 1.1. In the past I have used emails: [email protected]
+c2d5e239df7013223e5f52f1b8ac41a345891967 Update certificate-configuration-scenarios.md (#3189)
+98a73862bbf28cea7ba227a4482030437729c228 Update zowe-security-authentication.md (#3149)
+624fddc413f15bd35acfda827ff6dc16fb75ece9 Adjust the advanced config section (#3216)
+b07fd2c678379338bf03a691eef2c1588176c679 Add an overall flowchart to the beginning of the containerization installation chapter (#3237)
+277e136947f50d0703cd7e033fb07de17db35769 typo fix (#3256)

docs/extend/extend-apiml/api-mediation-oidc-authentication.md

@@ -23,7 +23,7 @@ The OIDC protocol is used by API ML client applications to verify the identity o
 After successful user login, the OIDC provider grants the client application a JWT Access Token along with an (JWT) Identity Token.
 The client application can pass this Access Token with subsequent requests to mainframe services routed through the API ML Gateway.
 The API ML Gateway then validates the OIDC Access Token. If the token is valid, the user identity from that token is mapped to the mainframe identity of the user.
-The API ML Gateway can then create mainframe user credentials (JWT or a Passticket) according to the service's authentication schema configuration.
+The API ML Gateway can then create mainframe user credentials (JWT or a PassTicket) according to the service's authentication schema configuration.
 The request is routed to the target API services with correct mainframe user credentials.
 
 ## Authentication Flow
@@ -32,17 +32,17 @@ The following diagram illustrates the interactions between the participants of t
 
 ![APIML OIDC Workflow](../../images/api-mediation/apiml-oidc-auth-seq.png)
 
-- When a user wants to access mainframe resources or services using the client application without a valid authentication or an access token, the client redirects the user agent to the login end-point of the distributed OIDC provider.
+- When a user wants to access mainframe resources or services using the client application without valid authentication or an access token, the client redirects the user agent to the login end-point of the distributed OIDC provider.
 - The user is asked to provide valid credentials (authentication factors).
 - After successful validation of all authentication factors, the OIDC provider grants the client an Access Token.
 - The client can then request from API ML Gateway the needed mainframe resources presenting the access token in the request.
 - The Gateway validates the access token by comparing the key id of the token against the key ids obtained from the authorization server's JWK keys endpoint.
-- The URL to specific authorization server's JWK keys end point should be set using the property `jwks_uri`. If the access token is validated, the outcome is cached for a short time (20 sec by default).
+- The URL to the specific authorization server's JWK keys endpoint should be set using the property `jwks_uri`. If the access token is validated, the outcome is cached for a short time (20 sec by default).
 - The JWK Keys obtained from the authorization server's endpoint are cached for a while to prevent repeated calls to the endpoint. The interval can be set using the property `jwks.refreshInternalHours` (The default value is one hour).
-- In subsequent calls with the same token, the Gateway reuses the cached validation outcome. As such, round trips to the OIDC authorization server for JWK keys and JWT Token validation are not required between short intervals when the client needs to access multiple resources in a row to complete a unit of work. The caching interval is configurable with a default value of 20 seconds, which is typically a sufficient time to allow most client operations requiring multiple API requests to complete, while also providing adequate protection against unauthorized access.
-- The caching interval is configurable with a default value of 20 seconds, which is typically a sufficient time to allow most client operations requiring multiple API requests to complete, while also providing adequate protection against unauthorized access.
+- In subsequent calls with the same token, the Gateway reuses the cached validation outcome. As such, round trips to the OIDC authorization server for JWK keys and JWT Token validation are not required between short intervals when the client needs to access multiple resources in a row to complete a unit of work. 
+- The caching interval is configurable with a default value of 20 seconds, which is typically a sufficient amount of time to allow most client operations requiring multiple API requests to complete, while also providing adequate protection against unauthorized access.
 - The API ML Gateway fetches the distributed user identity from the distributed access token and maps this user identity to the user mainframe identity using SAF.
-- The API ML Gateway calls the requested mainframe service/s with mainframe user credentials (Zowe, SAF JWT, or pass-ticket) which are expected by the target mainframe service.
+- The API ML Gateway calls the requested mainframe service/s with mainframe user credentials (Zowe, SAF JWT, or PassTicket) which are expected by the target mainframe service.
 
 ## Prerequisites
 
@@ -58,9 +58,11 @@ Ensure that the following prerequisites are met:
 - Client Application configuration in the OIDC provider.
 
   Depending on the OIDC provider and client application capabilities, configuration of the OIDC provider varies.
-For example Web Applications with a secure server side component can use `code grant authorization flow` and can be granted a Refresh Token, whereas a Single Page Application running entirely in the User Agent (browser) is more limited regarding its security capabilities.  
+For example, web applications with a secure server side component can use `code grant authorization flow` and can be granted a Refresh Token, whereas a Single Page Application running entirely in the User Agent (browser) is more limited regarding its security capabilities.  
 
-  **Tip:** Consult your OIDC provider documentation for options and requirements available for your type of client application.
+  :::tip
+  Consult your OIDC provider documentation for options and requirements available for your type of client application.
+  :::
 
 - Users have been assigned to the Client Application.
 
@@ -73,9 +75,9 @@ A distributed identity consists of two parts:
 - A distributed identity name
 - A trusted registry which governs that identity
 
-API ML provides a Zowe CLI plugin to help administrators to generate a JCL for creating the mapping filter specific for the ESM installed on the target mainframe system.
+API ML provides a Zowe CLI plugin to help administrators generate a JCL for creating the mapping filter specific for the ESM installed on the target mainframe system.
 
-  See the [Identity Federation cli plugin](#)  <!--Add link --> documentation for details about how to use the plugin tool to set up the mapping in the ESM of your z/OS system.
+  See the [Identity Federation cli plugin](../../user-guide/cli-idfplugin.md) documentation for details about how to use the plugin tool to set up the mapping in the ESM of your z/OS system.
 
 Alternatively, administrators can use the installed ESM functionality to create, delete, list, and query a distributed identity filter/s:
 
@@ -92,12 +94,6 @@ Use the following procedure to enable the feature to use an OIDC Access Token as
 - **`components.gateway.apiml.security.oidc.enabled`**  
    Specifies the global feature toggle. Set the value to `true` to enable OIDC authentication functionality.
 
-- **`components.gateway.apiml.security.oidc.clientId`**  
-   Specifies the value of the client identification (`client_id`) assigned by the OIDC provider to the API ML Gateway.
-
-- **`components.gateway.apiml.security.oidc.clientSecret`**
-   Specifies the client secret assigned by the OIDC provider to the API ML Gateway. This parameter is used in combination with the `client_id` to obtain JWKs from jwks.uri of the OIDC provider.
-
 - **`components.gateway.apiml.security.oidc.registry`**  
    Specifies the SAF registry used to group the identities recognized as having a OIDC identity mapping. The registry name is the string used during the creation of the mapping between the dustributed and mainframe user identities. For more information, see the [ESM configuration](#esm-configuration).
 
@@ -124,26 +120,13 @@ Use the following procedure to enable the feature to use an OIDC Access Token as
 
 ## Troubleshooting
 
-### API ML fails to validate the OIDC access token due to missing clientID and/or clientSecret
-
-**Symptom**  
-The Gateway log contains the following WARNING message:  
-`Missing clientId or clientSecret configuration. Cannot proceed with token validation.`
-
-**Explanation**  
-The `clientId` and/or `clientSecret` are not configured properly to correspond to the values set for the client application in the OIDC Identity Provider.
-
-**Solution**  
-Configure the `clientId` and/or `clientSecret` properly to contain the values set for the client application in the OIDC Identity Provider.
-
 ### API ML fails to validate the OIDC access token with the Distributed Identity Provider
 
 **Symptom**  
 The Gateway log contains the following ERROR message:  
-`Failed to validate the OIDC access token. Unexpected response: XXX.`  
-where:
+`Failed to validate the OIDC access token. Unexpected response: XXX.` 
 
-- _XXX_
+- **_XXX_**  
 is the HTTP status code returned by the Identity Provider.
 
 **Explanation**  
@@ -164,4 +147,27 @@ The OIDC provider returns an HTTP 40x error code.
 The client application is not properly configured in the API ML Gateway.
 
 **Solution**  
-Check that the `client_id` and `client_secret` configured in the API ML Gateway correspond to the `client_id` and `client_secret` of the client application as configured in the OIDC provider.
+Check that the URL `jwks_uri` contains the key for  OIDC token validation.
+
+
+:::tip
+API ML Gateway exposes a validate token operation which is suitable during the OIDC setup. The call to the endpoint `/gateway/api/v1/auth/oidc-token/validate` verifies if the OIDC token is trusted by API ML. Note that the Gateway service does not perform the mapping request to the ESM when the `/gateway/api/v1/auth/oidc-token/validate` endpoint is called.
+
+Use the following curl command to make a REST request with the OIDC token to the validate token endpoint:
+```shell
+curl --location 'https://"$HOSTNAME:$PORT"/gateway/api/v1/auth/oidc-token/validate --data '{"token": "$OIDC_TOKEN","serviceId": "$SERVICE_ID"}'
+```
+An HTTP `200` code is returned if the validation passes. Failure to validate returns an HTTP `40x` error.
+:::
+
+:::note**Azure Entra ID OIDC notes:**
+API ML uses the `sub` claim of the ID Token to identify the user, and to map to the mainframe account. Note that the structure of the `sub` claim varies between the Azure token and the OKTA ID token:
+* The Azure token `sub` is an alphanumeric value.  
+For more information, see the topic _Use claims to reliably identify a user_ in the Microsoft Learn documentation.
+* The OKTA ID token has an email in the `sub` claim.
+
+For more information about Entra ID token format see _ID token claims reference_ in the Microsoft documentation.
+:::
+
+
+

docs/extend/extend-apiml/authentication-for-apiml-services.md

@@ -84,7 +84,7 @@ The `auth/ticket` endpoint generates a PassTicket for the user associated with a
 
   **Notes:** 
 
-   - The endpoint is disabled by default. For more information, see [Enable JWT token endpoint](../../user-guide/api-mediation/api-gateway-configuration.md#enable-jwt-token-refresh-endpoint).
+   - The endpoint is disabled by default. For more information, see [Enable JWT token endpoint](../../user-guide/api-mediation/configuration-jwt#enabling-a-jwt-token-refresh-endpoint).
    - The endpoint is protected by a client certificate.
 
   The refresh request requires the token in one of the following formats:
@@ -133,9 +133,9 @@ Authentication is performed in the following ways:
 * Ensure that you have an external Certificate Authority and signed client certificates, or generate these certificates in SAF. The client certificate has to have correct `Extended Key Usage` metadata to allow being used for TLS client authentication. (`OID: 1.3.6.1.5.5.7.3.2`)
 * Import the client certificates to SAF, or add them to a user profile. (Examples: `RACDCERT ADD` or `RACDCERT GENCERT`). For more information, see your security system documentation.
 * Import the external CA to the truststore or keyring of the API Mediation Layer.
-* [Configure Gateway for client certificate authentication](../../user-guide/api-mediation/api-gateway-configuration.md#gateway-client-certificate-authentication).
+* [Configure Gateway for client certificate authentication](../../user-guide/api-mediation/configuration-client-certificates).
 * To upgrade from Zowe 1.18 or lower, see the [Additional security rights that need to be granted](../../user-guide/configure-zos-system.md#configure-main-Zowe-server-use-identity-mapping).
-* PassTicket generation must be enabled for the Zowe runtime user. The user has to be able to generate PassTicket for itself and for the APPLID of z/OSMF. For more information, see [Configure Passticket](api-mediation-passtickets.md).
+* PassTicket generation must be enabled for the Zowe runtime user. The user has to be able to generate PassTicket for itself and for the APPLID of z/OSMF. For more information, see [Configure Passticket](../../user-guide/api-mediation/configuration-extender-passtickets).
 * The Zowe runtime user has to be enabled to perform identity mapping in SAF. For more information, see [Additional security rights that need to be granted](../../user-guide/configure-zos-system.md#configure-main-Zowe-server-use-identity-mapping).
 * ZSS has to be configured to participate in Zowe SSO. For more information, see [Configure components zss](../../appendix/zowe-yaml-configuration.md/#configure-component-zss).
 
@@ -178,15 +178,15 @@ The value of this parameter specifies a service authentication scheme. Any valid
       * When a Zowe JWT is provided, this scheme value specifies that the service accepts the Zowe JWT. No additional processing is done by the API Gateway.
       * When a client certificate is provided, the certificate is transformed into a Zowe JWT, and the southbound service performs the authentication.
       * If the southbound service needs to consume the JWT token from a custom HTTP request header to participate in the Zowe SSO, it is possible to provide a header in the Gateway configuration.
-      The HTTP header is then added to each request towards the southbound service and contains the Zowe JWT to be consumed by the service. See [Advanced Gateway features configuration](../../user-guide/api-mediation/api-gateway-configuration.md) for more information about the custom HTTP request header.
+      The HTTP header is then added to each request towards the southbound service and contains the Zowe JWT to be consumed by the service. See [Customizing the header](../../user-guide/api-mediation/configuration-extender-jwt#adding-a-custom-http-auth-header-to-store-zowe-jwt-token) for more information about the custom HTTP request header.
     * **httpBasicPassTicket**  
     This value specifies that a service accepts PassTickets in the Authorization header of the HTTP requests using the basic authentication scheme.
       It is necessary to provide a service APPLID in the `authentication.applid` parameter to prevent passticket generation errors.
 
         * When a JWT is provided, the service validates the Zowe JWT to use for passticket generation.
         * When a client certificate is provided, the service validates the certificate by mapping it to a mainframe user to use for passticket generation.
         * If the southbound service needs to consume the user ID and the passticket from custom HTTP request headers (i.e. to participate in the Zowe SSO), it is possible to provide the headers in the Gateway configuration.
-      The HTTP headers are then added to each request towards the southbound service. The headers contain the user ID and the passticket to be consumed by the service. See [Advanced Gateway features configuration](../../user-guide/api-mediation/api-gateway-configuration.md) for more information about the custom HTTP request headers.
+      The HTTP headers are then added to each request towards the southbound service. The headers contain the user ID and the passticket to be consumed by the service. See [Customize Auth header](../../user-guide/api-mediation/configuration-extender-passtickets#adding-custom-http-auth-headers-to-store-user-id-and-passticket) for more information about the custom HTTP request headers.
 
       For more information, see [Authentication with PassTickets](#authentication-with-passtickets).