Merge pull request #3737 from zowe/janan07-sso-via-PAT-config-peer-re…

…view
zowe · Jul 5, 2024 · 6ff1d15 · 6ff1d15
2 parents 8d4a7a9 + bda0d40
commit 6ff1d15
Showing 1 changed file with 121 additions and 61 deletions.
diff --git a/docs/user-guide/api-mediation/configuration-extender-passtickets.md b/docs/user-guide/api-mediation/configuration-extender-passtickets.md
@@ -1,24 +1,26 @@
 # Enabling single sign on for extending services via PassTicket configuration
 
-Single sign on can be enabled by configuring Zowe to use PassTickets for API services to authenticate with API Mediation Layer. Follow the procedures described in this article to configure Zowe to use PassTickets, and to enable Zowe to use PassTickets to authenticate towards specific extending services.
+One option for enabling single sign on is by configuring Zowe to use PassTickets, whereby API services can authenticate with API Mediation Layer. Follow the procedures described in this article to configure Zowe to use PassTickets, and to enable Zowe to use PassTickets to authenticate towards specific extending services.
 
-:::info Role: security administrator
+:::info Required Role: security administrator
 :::
 
-- [Overview of how PassTickets are used](#overview-of-how-passtickets-are-used)
+- [Overview of PassTickets](#overview-of-how-passtickets-are-used)
 - [Configuring Zowe to use PassTickets](#configuring-zowe-to-use-passtickets)
     - [Enabling PassTicket support](#enabling-passticket-support)
-        - [PassTicket enablement with ACF2](#passticket-enablement-with-acf2)
-        - [PassTicket enablement with Top Secret](#passticket-enablement-with-top-secret)
-        - [PassTicket enablement with RACF](#passticket-enablement-with-racf)
+        - [Enabling PassTickets with ACF2](#enabling-passtickets-with-acf2)
+        - [Enable PassTickets with Top Secret](#enabling-passtickets-with-top-secret)
+        - [Enabling PassTickets with RACF](#enabling-passtickets-with-racf)
     - [Configuring security to allow the Zowe API Gateway to generate PassTickets for an API service](#configuring-security-to-allow-zowe-api-gateway-to-generate-passtickets-for-an-api-service)
         - [Generating PassTickets using ACF2](#generating-passtickets-using-acf2)
         - [Generating PassTickets using Top Secret](#generating-passtickets-using-top-secret)
         - [Generating PassTickets using RACF](#generating-passtickets-using-racf)
+        - [Validating if the PassTicket Application is created](#validating-if-the-passticket-application-is-created)
 - [Adding custom HTTP Auth headers to store user ID and PassTicket](#adding-custom-http-auth-headers-to-store-user-id-and-passticket)
-## Overview of how PassTickets are used
 
-API clients can use various supported methods such as a Zowe JWT token or client certificate to access an API service even if the API service itself does not support the JWT token or client certificate.
+## Overview of PassTickets 
+
+API clients can use various supported methods to access an API service such as a Zowe JWT token or a client certificate even if the API service itself does not support the JWT token or a client certificate. An intermediary for this support can be through the use of PassTickets.
 
 When an API client provides a valid authentication method to API ML, the API Gateway generates a valid PassTicket for any API service that supports PassTickets. A PassTicket is a one-time only password that is generated for a specific user ID. 
 The API Gateway uses the PassTicket to access that API service.
@@ -28,69 +30,105 @@ The API Gateway provides the user ID and password in the Authorization header of
 ## Configuring Zowe to use PassTickets
 
 Configuring Zowe to use PassTickets involves two processes:
-* Enabling the use of PassTickets in the operating system
+* Enabling the use of PassTickets in your External Security Manager (ESM)
 * Configuring security to allow the Zowe API Gateway to generate PassTickets for an API service
 
-### Enabling the use of PassTickets in the operating system
+### Enabling the use of PassTickets in your External Security Manager (ESM)
 
-This section applies to users who do not have PassTickets enabled in the system or those who need to define a PassTicket for a new APPLID. If you already have an APPLID that you will use to define your API service, skip to the section [Configuring security to allow the Zowe API Gateway to generate PassTickets for an API service](#configuring-security-to-allow-zowe-api-gateway-to-generate-passtickets-for-an-api-service).
+This section applies to users who do not already have PassTickets enabled in the system, or users who need to define a PassTicket for a new APPLID. If you already have an APPLID that you intend to use to define your API service, skip to the section [Configuring security to allow the Zowe API Gateway to generate PassTickets for an API service](#configuring-security-to-allow-zowe-api-gateway-to-generate-passtickets-for-an-api-service).
 
 :::tip
 To validate if a PassTicket is already defined, use the commands that correspond to your ESM. If the PassTicket is defined, the access of the zoweuser can be determined.
 
-<details>
-<summary>**For ACF2**</summary>
+* **Validating an existing PassTicket for ACF2**
 
-```
-SET RESOURCE(SAF)
-LIST LIKE(-)
+    <details>
 
-SET RESOURCE(SAF)
-LIST LIKE(<applid>-)
+    <summary>Click here for details about validating an existing PassTicket for ACF2.</summary>
 
-SET PROFILE(PTKTDATA) DIVISION(SSIGNON)
-LIST LIKE(<applid>-)
+    In your ESM command line interface or other security environment, execute the following commands:
 
-SET RESOURCE(PTK)
-LIST LIKE(IRRPTAUTH-)
-```
+    ```
+    SET RESOURCE(SAF)
+    LIST LIKE(-)
 
-</details>
+    SET RESOURCE(SAF)
+    LIST LIKE(<applid>-)
 
-<details>
-<summary>**For Top Secret**</summary>
+    SET PROFILE(PTKTDATA) DIVISION(SSIGNON)
+    LIST LIKE(<applid>-)
 
-```
-TSS WHOHAS APPL(<applid>)
-TSS WHOHAS PTKTDATA(<applid>)
-TSS WHOHAS PTKTDATA(IRRPTAUTH.<applid>.)
-```
+    SET RESOURCE(PTK)
+    LIST LIKE(IRRPTAUTH-)
+    ```
+    * **`-`**  
+    A wildcard symbol that lists all resources
 
-</details>
+    * **`<applid>-`**  
+    Lists everything related to specified applid in a resource (in this case, SAF), or specified in a profile (in this case, PTKTDATA)
 
-<details>
-<summary>**For RACF**</summary>
+    </details>
 
-```
-RLIST APPL * ALL -validate all APPL
-RLIST APPL <applid> ALL  - validate particular APPL
-RLIST PTKTDATA <applid> SSIGNON ALL
-RLIST PTKTDATA IRRPTAUTH.<applid>.* ALL 
-```
-Ensure that you validate PKTDATA access for appl.
+* **Validating an existing PassTicket for Top Secret**
 
-</details>
+    <details>
+
+    <summary>Click here for details about validating an existing PassTicket for Top Secret.</summary>
+
+    In your ESM command line interface or other security environment, execute the following commands:
+    ```
+    TSS WHOHAS APPL(<applid>)
+    TSS WHOHAS PTKTDATA(<applid>)
+    TSS WHOHAS PTKTDATA(IRRPTAUTH.<applid>.)
+    ```
+
+    * **`.`**  
+    A wildcard symbol that lists all resources
+
+    * **`IRRPTAUTH.<applid>.`**  
+    Returns everything about the specified applid for IRRPTAUTH
+
+    </details>
+
+* **Validating an existing PassTicket for RACF**
+
+    <details>
+
+    <summary>Click here for details about validating an existing PassTicket for RACF.</summary>
+
+    In your ESM command line interface or other security environment, execute the following commands:
+
+    ```
+    RLIST APPL * ALL 
+    RLIST APPL <applid> ALL  
+    RLIST PTKTDATA <applid> SSIGNON ALL
+    RLIST PTKTDATA IRRPTAUTH.<applid>.* ALL 
+    ```
+    Ensure that you validate PKTDATA access for APPL.
+
+    * **`*`**  
+    A wildcard symbol that resturns all resources
+
+    * **`RLIST PTKTDATA <applid> SSIGNON ALL`**  
+    Validates all applid for PTKDATA class
+
+    * **`RLIST PTKTDATA IRRPTAUTH.<applid>.* ALL`**  
+    Validates all applid permissions for PTKDATA class
+
+    </details>
 
 :::
 
-The following steps outline the procedure for enabling PassTicket Support for your ESM:
+Follow these steps to enable PassTicket Support specific to your ESM. Consult with your security administrator to perform the following procedures. 
+
+#### Enabling PassTickets with ACF2
 
-#### PassTicket enablement with ACF2
 <details>
-<summary> Click here for steps to configure Zowe to use PassTickets using ACF2. Note that this procedure should be performed by your security administrator. </summary>
 
+<summary> Click here for details about configuring Zowe to use PassTickets using ACF2. </summary>
 
-1.	Define the application session key by entering the following commands, if the session key is not already defined. 
+
+1.	In your ESM command line interface or other security environment, Ddefine the application session key by entering the following commands, if the session key is not already defined. 
 
 ```
 SET PROFILE(PTKTDATA) DIV(SSIGNON)
@@ -116,15 +154,21 @@ The PassTicket record is now active in the system.
 3. Enable the started task user ID to generate PassTickets for the application by entering commands similar to the following:
 ```
 SET RESOURCE(PTK) 
-RECKEY IRRPTAUTH ADD(applid.userid UID(<uid-of-userid>) SERVICE(UPDATE,READ) ALLOW)
+RECKEY IRRPTAUTH ADD(applid.userid UID(<userid>) SERVICE(UPDATE,READ) ALLOW)
 ```
+* `<userid>`  
+Specifies the Zowe server user ID
+
+
+You configured Zowe to use PassTickets using ACF2. 
 
 </details>
 
-#### PassTicket enablement with Top Secret
+#### Enabling PassTickets with Top Secret
 
 <details>
-<summary> Click here for steps to configure Zowe to use PassTickets using Top Secret. Note that this procedure should be performed by your security administrator. </summary>
+
+<summary> Click here for details about configuring Zowe to use PassTickets using Top Secret.</summary>
 
 Before you begin this procedure, verify that the `PTKTDATA` class and ownership for the PassTicket resource (`IRRPTAUT`) have not already been defined.
 
@@ -133,6 +177,7 @@ Before you begin this procedure, verify that the `PTKTDATA` class and ownership
 :::note
 The PTKTDATA resource is not a predefined class.
 :::
+
 ```
 TSS ADDTO(RDT) RESCLASS(PTKTDATA) RESCODE(n) ACLST(ALL,READ,UPDATE) MAXLEN(37) 
 ```
@@ -152,7 +197,10 @@ TSS ADDTO(department) PTKTDATA(IRRPTAUT)
 TSS ADDTO(NDT) PSTKAPPL(<applid>) SESSKEY(<key-description>) SIGNMULTI
 ```
 
-* **key-description**  
+* **applid**  
+Specifies the application ID used for PassTicket validation to authenticate connections to the server.
+
+* **key-description**    
  Specifies the secured sign-on hexadecimal application key of 16 hexadecimal digits (8-byte or 64-bit key). Each application key must be the same on all systems in the configuration and the values must be kept secret and secured.
 
 4. Permit access to the PassTicket resource defined in the previous step for the LDAP Server by executing the following command:
@@ -163,17 +211,20 @@ TSS PERMIT(<stc-userid>) PTKTDATA(IRRPTAUTH.applid) ACCESS(UPDATE)
 * **stc-userid**  
 Specifies the ACID that you created when you created LDAP Server started task User IDs. The parameter is "CALDAP" by default.	
 	
+You configured Zowe to use PassTickets using Top Secret.
 
 </details>
 
-#### PassTicket enablement with RACF
+#### Enabling PassTickets with RACF
 
 
 <details>
-<summary> Click here for steps to configure Zowe to use PassTickets using RACF. Note that this procedure should be performed by your security administrator. </summary>
 
-1. Activate the `PTKTDATA` class, which encompasses all profiles containing PassTicket information.  
-Execute the following command:
+<summary> Click here for details about configuring Zowe to use PassTickets using RACF.</summary>
+
+1. Activate the `PTKTDATA` class, which encompasses all profiles containing PassTicket information.
+
+In your ESM command line interface or other security environment, execute the following command:
 
 ```
 SETROPTS CLASSACT(PTKTDATA) RACLIST(PTKTDATA)
@@ -186,7 +237,8 @@ SETROPTS CLASSACT(APPL)
 SETROPTS GENERIC(PTKTDATA)
 ```
 
-Replace _applid_ with a one to 8 character name designated for the application. 
+* ***applid**  
+A one to 8 character name designated for the application. 
 
 :::note 
 This name is usually provided by the site security administrator.
@@ -219,6 +271,8 @@ Specifies the value of the LDAP Server started task.
 SETROPTS RACLIST(PTKTDATA) REFRESH
 ```
 
+You configured Zowe to use PassTickets using RACF.
+
 </details>
 
 ### Configuring security to allow Zowe API Gateway to generate PassTickets for an API service
@@ -227,10 +281,10 @@ As a security administrator, you can issue security commands to allow the Zowe s
 
 Specify the following variables when generating PassTickets for the API service to enable the Zowe started task user ID:
 
-- **`<applid>`**  
+* **applid**  
 The APPLID value used by the API service for PassTicket support (e.g. `OMVSAPPL`)
 
-- **`<zowe-user-id>`**  
+* **zowe-user-id**   
 The Zowe started task user ID used during the Zowe installation
 
 In the following examples of ESM configuration, replace these variables with actual values.
@@ -288,13 +342,19 @@ SETROPTS RACLIST(PTKTDATA) REFRESH
 ```
 </details>
 
-### Validate if the PassTicket Application is created
+### Validating if the PassTicket Application is created
+
+In your ESM command line interface or other security environment, execute the following commands:
 
 ```
 RLIST APPL <applid> ALL
 RLIST PTKTDATA IRRPTAUTH.<applid>.* ALL
 ```
-Your application and the specific access of the application will be displayed.
+
+* **applid**  
+The APPLID value used by the API service for PassTicket support
+
+Successful execution of this validation command shows your application and the specific access of the application.
 
 
 ## Adding custom HTTP Auth headers to store user ID and PassTicket (Optional)
@@ -305,8 +365,8 @@ The southbound service must use the `httpBasicPassTicket` scheme in order to lev
 Use the following procedure to add the custom HTTP headers.
 
 1. Open the file `zowe.yaml`.
-2. Find or add the property `components.gateway.apiml.security.auth.passticket.customAuthHeader` and set the value which represents the header's name.
-3. Find or add the property `components.gateway.apiml.security.auth.passticket.customUserHeader` and set the value which represents the header's name.
+2. Find or add the property `components.gateway.apiml.security.auth.passticket.customAuthHeader` and set the value which represents the name of the header.
+3. Find or add the property `components.gateway.apiml.security.auth.passticket.customUserHeader` and set the value which represents the name of the header.
 4. Restart Zowe.
 
 Requests through the Gateway towards the southbound service now contain the custom HTTP headers with the PassTicket and the user ID.