Add expiration customization instructions to config with JWT (#3409)

* add expiration customization instructions

Signed-off-by: Andrew Jandacek <[email protected]>

* remove note

Signed-off-by: Andrew Jandacek <[email protected]>

* remove procedure

Signed-off-by: Andrew Jandacek <[email protected]>

---------

Signed-off-by: Andrew Jandacek <[email protected]>

docs/user-guide/api-mediation/configuration-jwt.md

@@ -5,27 +5,27 @@
 
 As a system programmer, you can customize how JWT authentication is performed, the service that provides the JWT authentication token, whether it's possible to refresh JWT token and other characteristics of JWT for consumption. 
 
-## SAF as an Authentication provider
+* [Using SAF as an authentication provider](#using-saf-as-an-authentication-provider)
+* [Enabling a JWT token refresh endpoint](#enabling-a-jwt-token-refresh-endpoint)
+* [Authorization](#authorization)
+* [Additional customizable properties when using JWT tokens](#additional-customizable-properties-when-using-jwt-tokens)
+
+## Using SAF as an authentication provider
 
 By default, the API Gateway uses z/OSMF as an authentication provider. It is possible to switch to SAF as the authentication
 provider instead of z/OSMF. The intended usage of SAF as an authentication provider is for systems without z/OSMF.
 If SAF is used and the z/OSMF is available on the system, the created tokens are not accepted by z/OSMF. Use
 the following procedure to switch to SAF. 
 
 1. Open the `zowe.yaml` configuration file.
-2. Find or add the property `components.gateway.apiml.security.auth.provider` and set the value to `saf`.
+2. Find or add the following property, and set the value to `saf`:
+```
+components.gateway.apiml.security.auth.provider
+```
 3. Restart Zowe.
 
 Authentication requests now utilize SAF as the authentication provider. API ML can run without z/OSMF present on the system. 
 
-Also see the following properties:
-
-* **[apiml.security.auth.tokenProperties.expirationInSeconds](./api-mediation/api-mediation-internal-configuration/#runtime-configuration)**  
-    This property is relevant only when the JWT is generated by the API Mediation Layer and specifies to the time before expiration.
-
-* **[components.gateway.apiml.security.auth.zosmf.ServiceId](./api-mediation/api-gateway-configuration/#runtime-configuration)**  
-        This parameter specifies the z/OSMF service id used as authentication provider. The service id is defined in the static definition of z/OSMF. The default value is `zosmf`.
-
 ## Enabling a JWT token refresh endpoint
 
 Enable the `/gateway/api/v1/auth/refresh` endpoint to exchange a valid JWT token for a new token with a new expiration date. Call the endpoint with a valid JWT token and trusted client certificate. When using the z/OSMF authentication provider, enable API Mediation Layer for PassTicket generation and configure the z/OSMF APPLID. 
@@ -35,16 +35,40 @@ For more information, see [Configure Passtickets](configuration-extender-passtic
 1. Open the file `zowe.yaml`.
 2. Configure the following properties:
 
-    * **components.gateway.apiml.security.allowtokenrefresh: true**  
-    Add this property to enable the refresh endpoint.
+  * **components.gateway.apiml.security.allowtokenrefresh: true**  
+  Add this property to enable the refresh endpoint.
 
-    * **components.gateway.apiml.security.zosmf.applid**  
-    If you use z/OSMF as an authentication provider, provide a valid `APPLID`. The API ML generates a passticket for the specified `APPLID` and subsequently uses this passticket to authenticate to z/OSMF. The default value in the installation of z/OSMF is `IZUDFLT`.
+  * **components.gateway.apiml.security.zosmf.applid**  
+  If you use z/OSMF as an authentication provider, provide a valid `APPLID`. The API ML generates a PassTicket for the specified `APPLID` and subsequently uses this PassTicket to authenticate to z/OSMF. The default value in the installation of z/OSMF is `IZUDFLT`.
 
 3. Restart Zowe.
 
 ## Authorization
 
-Authorization is a method used to determine access rights of an entity.
+Authorization is used to set the access rights of an entity.
+
+In the API ML, authorization is performed by any of the following z/OS security managers:
+* [ACF2](https://www.broadcom.com/products/mainframe/identity-access/acf2)
+* [IBM RACF](https://www.ibm.com/support/knowledgecenter/zosbasics/com.ibm.zos.zsecurity/zsecc_042.htm)
+*  [Top Secret](https://www.broadcom.com/products/mainframe/identity-access/top-secret). 
+
+An authentication token is used as proof of valid authentication. The authorization checks, however, are always performed by the z/OS security manager.
+
+## Additional customizable properties when using JWT tokens
+
+You can also customize the following properties when authenticating with a JWT token:
+
+* **components.gateway.apiml.security.auth.zosmf.ServiceId**  
+    This parameter specifies the z/OSMF service id used as authentication provider. The service id is defined in the static definition of z/OSMF. The default value is `zosmf`.
+
+* **components.gateway.apiml.security.auth.tokenProperties.expirationInSeconds**  
+    This property is relevant only when the JWT is generated by the API Mediation Layer and specifies to the time before expiration.
+
+    API ML generation of the JWT occurs in the following cases:
+
+    * z/OSMF is only available as an older version which does not support JWT tokens  
+    * The SAF provider is used
+
+    To use a custom configuration for z/OSMF which changes the expiration of the LTPA token, it is necessary to also set the expiration in this parameter.
+
 
-In the API ML, authorization is performed by the z/OS security manager ([ACF2](https://www.broadcom.com/products/mainframe/identity-access/acf2), [IBM RACF](https://www.ibm.com/support/knowledgecenter/zosbasics/com.ibm.zos.zsecurity/zsecc_042.htm), [Top Secret](https://www.broadcom.com/products/mainframe/identity-access/top-secret)). An authentication token is used as proof of valid authentication. The authorization checks, however, are always performed by the z/OS security manager.