Merge branch 'docs-staging' into archiving-v2.12.x-release

Signed-off-by: Wen Ting Su (Sam) <[email protected]>

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/zowe-api-mediation-layer-security-overview.md

@@ -36,7 +36,7 @@ API ML uses the following authentication methods:
 
 - **OIDC authentication**
 
-  API ML is now able to authenticate mainframe users with an external/distributed Identity Provider (IDP) implemented by an OIDC/OAuth2 provider, such as OKTA, KeyCloak and others.
+  API ML is now able to authenticate mainframe users with an external/distributed Identity Provider (IDP) implemented by an OIDC/OAuth2 provider, such as OKTA, KeyCloak, Microsoft Entra ID (a.k.a. Azure Active Directory) and others.
   Client applications can ask their users to log in at the authentication page of the OIDC provider, and then access APIs with the JWT Access Token that is provided by the external IDP. The following process outlines that basic flow:
   - The client application intiates the OIDC authentication flow with the distributed OIDC provider.  
   - The user provides credentials as required at the provider's authentication page/end-point.

docs/troubleshoot/servers/must-gather.md

@@ -44,6 +44,8 @@ Do you think your issue is a bug? If so, try to list the steps to reproduce it,
 When running Zowe servers on z/OS, the joblog has the most information.
 Depending on what support group you are contacting, you may want to sanitize the logs as they can contain basic system information like hostnames, usernames, and network configuration.
 
+Ensure that your logs were captured with long enough record length to be read by support. Zowe commonly writes lines as long as 500 characters, especially when tracing.
+
 ### Enabling debugging and tracing
 
 There are several debug modes in the Zowe servers, and support groups may ask for you to turn some on.

docs/troubleshoot/troubleshoot-zos-certificate.md

@@ -2,7 +2,7 @@
 
 The following topic provides the information that can help you troubleshoot problems when you encounter errors or warnings in configuring certificates.
 
-## PKCS 12 server keystore generation fails in Java 8 SR7FP15, SR7 FP16, and SR7 FP20
+## PKCS12 server keystore generation fails in Java 8 SR7FP15, SR7 FP16, and SR7 FP20
 
 **Symptoms**