From e89f5e1ad19c72577582aade7b15b48211bc05ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= Date: Wed, 31 Jul 2024 14:12:42 +0200 Subject: [PATCH 1/7] automatic lint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pablo Hernán Carle --- .../configuration-extender-passtickets.md | 111 ++++++++++-------- 1 file changed, 61 insertions(+), 50 deletions(-) diff --git a/docs/user-guide/api-mediation/configuration-extender-passtickets.md b/docs/user-guide/api-mediation/configuration-extender-passtickets.md index dadc3ee9a5..a6eae83d46 100644 --- a/docs/user-guide/api-mediation/configuration-extender-passtickets.md +++ b/docs/user-guide/api-mediation/configuration-extender-passtickets.md @@ -7,31 +7,31 @@ One option for enabling single sign on is by configuring Zowe to use PassTickets - [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) - - [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) + - [Enabling PassTicket support](#enabling-passticket-support) + - [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 PassTickets +## 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. +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. The API Gateway provides the user ID and password in the Authorization header of the HTTP requests using the -[Basic authentication scheme](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#Basic_authentication_scheme). +[Basic authentication scheme](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#Basic_authentication_scheme). ## Configuring Zowe to use PassTickets Configuring Zowe to use PassTickets involves two processes: -* 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 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 your External Security Manager (ESM) @@ -40,7 +40,7 @@ This section applies to users who do not already have PassTickets enabled in the :::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. -* **Validating an existing PassTicket for ACF2** +- **Validating an existing PassTicket for ACF2**
@@ -61,36 +61,38 @@ To validate if a PassTicket is already defined, use the commands that correspond SET RESOURCE(PTK) LIST LIKE(IRRPTAUTH-) ``` - * **`-`** + + - **`-`** A wildcard symbol that lists all resources - * **`-`** + - **`-`** Lists everything related to specified applid in a resource (in this case, SAF), or specified in a profile (in this case, PTKTDATA)
-* **Validating an existing PassTicket for Top Secret** +- **Validating an existing PassTicket for Top Secret**
Click here for details about validating an existing PassTicket for Top Secret. In your ESM command line interface or other security environment, execute the following commands: + ``` TSS WHOHAS APPL() TSS WHOHAS PTKTDATA() TSS WHOHAS PTKTDATA(IRRPTAUTH..) ``` - * **`.`** + - **`.`** A wildcard symbol that lists all resources - * **`IRRPTAUTH..`** + - **`IRRPTAUTH..`** Returns everything about the specified applid for IRRPTAUTH
-* **Validating an existing PassTicket for RACF** +- **Validating an existing PassTicket for RACF**
@@ -104,22 +106,23 @@ To validate if a PassTicket is already defined, use the commands that correspond RLIST PTKTDATA SSIGNON ALL RLIST PTKTDATA IRRPTAUTH..* ALL ``` + Ensure that you validate PKTDATA access for APPL. - * **`*`** + - **`*`** A wildcard symbol that resturns all resources - * **`RLIST PTKTDATA SSIGNON ALL`** + - **`RLIST PTKTDATA SSIGNON ALL`** Validates all applid for PTKDATA class - * **`RLIST PTKTDATA IRRPTAUTH..* ALL`** + - **`RLIST PTKTDATA IRRPTAUTH..* ALL`** Validates all applid permissions for PTKDATA class
::: -Follow these steps to enable PassTicket Support specific to your ESM. Consult with your security administrator to perform the following procedures. +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 @@ -127,8 +130,7 @@ Follow these steps to enable PassTicket Support specific to your ESM. Consult wi Click here for details about configuring Zowe to use PassTickets using ACF2. - -1. In your ESM command line interface or other security environment, 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, define the application session key by entering the following commands, if the session key is not already defined. ``` SET PROFILE(PTKTDATA) DIV(SSIGNON) @@ -136,31 +138,34 @@ INSERT SSKEY() MULT-USE F ACF2,REBUILD(PTK),CLASS(P) ``` -* **applid** +- **applid** Specifies the application ID used for PassTicket validation to authenticate connections to the server. -* **MULT-USE** +- **MULT-USE** This setting lets you reuse the same PassTicket multiple times. -* **key-description** +- **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. 2. Complete the PassTicket setup by entering the following commands: + ``` F ACF2,REBUILD(PTK),CLASS(P) ``` + 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() SERVICE(UPDATE,READ) ALLOW) ``` + * `` Specifies the Zowe server user ID - -You configured Zowe to use PassTickets using ACF2. +You configured Zowe to use PassTickets using ACF2. @@ -172,7 +177,7 @@ You configured Zowe to use PassTickets using ACF2. Before you begin this procedure, verify that the `PTKTDATA` class and ownership for the PassTicket resource (`IRRPTAUT`) have not already been defined. -1. Update the resource descriptor table (RDT) to define the `PTKTDATA` class by entering the following commands: +1. Update the resource descriptor table (RDT) to define the `PTKTDATA` class by entering the following commands: :::note The PTKTDATA resource is not a predefined class. @@ -181,43 +186,46 @@ The PTKTDATA resource is not a predefined class. ``` TSS ADDTO(RDT) RESCLASS(PTKTDATA) RESCODE(n) ACLST(ALL,READ,UPDATE) MAXLEN(37) ``` + The PTKTDATA resource is added to the RDT. :::note Include `RESCODE(n)` in the range of 101 to 13F to make `PTKTDATA` a prefixed resource class. ::: -2. Assign ownership for the PassTicket resource (`IRRPTAUT`). Execute the following commands: +2. Assign ownership for the PassTicket resource (`IRRPTAUT`). Execute the following commands: + ``` TSS ADDTO(department) PTKTDATA(IRRPTAUT) ``` + 3. Define PassTicket for application ID _applid_ without replay protection. ``` TSS ADDTO(NDT) PSTKAPPL() SESSKEY() SIGNMULTI ``` -* **applid** +- **applid** Specifies the application ID used for PassTicket validation to authenticate connections to the server. -* **key-description** +- **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: + ``` TSS PERMIT() 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. - +- **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. #### Enabling PassTickets with RACF -
Click here for details about configuring Zowe to use PassTickets using RACF. @@ -231,23 +239,26 @@ SETROPTS CLASSACT(PTKTDATA) RACLIST(PTKTDATA) ``` 2. Specify the application ID requiring access through PassTicket for the ZOWE server with the following commands: + ``` RDEFINE APPL UACC(READ) SETROPTS CLASSACT(APPL) SETROPTS GENERIC(PTKTDATA) ``` -* ***applid** -A one to 8 character name designated for the application. +- ***applid** +A one to 8 character name designated for the application. -:::note +:::note This name is usually provided by the site security administrator. ::: 3. Define the profile for the application with the following command: + ``` RDEFINE PTKTDATA UACC(NONE) APPLDATA('NO REPLAY PROTECTION') SSIGNON(KEYMASKED() APPLDATA('NO REPLAY PROTECTION') ``` + * **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. @@ -263,10 +274,11 @@ PassTickets for the API service must have the replay protection switched off. Th PERMIT IRRPTAUTH.applid.* CLASS(PTKTDATA) ACCESS(UPDATE) ID(userid) ``` -* **userid** +- **userid** Specifies the value of the LDAP Server started task. 5. Refresh the RACF PTKTDATA definition with the new profile: + ``` SETROPTS RACLIST(PTKTDATA) REFRESH ``` @@ -281,10 +293,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. @@ -326,7 +338,6 @@ TSS PERMIT() PTKTDATA(IRRPTAUTH..) ACCESS(READ,UPDATE) TSS REFRESH ``` -
#### Generating PassTickets using RACF @@ -343,6 +354,7 @@ Grant the Zowe started task user ID permission to generate PassTickets for users PERMIT IRRPTAUTH..* CL(PTKTDATA) ID() ACCESS(UPDATE) SETROPTS RACLIST(PTKTDATA) REFRESH ``` + ### Validating if the PassTicket Application is created @@ -354,12 +366,11 @@ RLIST APPL ALL RLIST PTKTDATA IRRPTAUTH..* ALL ``` -* **applid** +- **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) If a downstream (southbound) service needs to consume the PassTicket and the user ID from custom headers to participate in the Zowe SSO, you can define the custom HTTP headers names as part of the Gateway configuration. @@ -372,4 +383,4 @@ Use the following procedure to add the custom HTTP headers. 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. \ No newline at end of file +Requests through the Gateway towards the southbound service now contain the custom HTTP headers with the PassTicket and the user ID. From 3d1c8f84f9ae7fec3fa51a4df39eb8e09ac7a84b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= Date: Wed, 31 Jul 2024 14:30:50 +0200 Subject: [PATCH 2/7] fix other lint issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pablo Hernán Carle --- .../configuration-extender-passtickets.md | 63 ++++++++++--------- 1 file changed, 32 insertions(+), 31 deletions(-) diff --git a/docs/user-guide/api-mediation/configuration-extender-passtickets.md b/docs/user-guide/api-mediation/configuration-extender-passtickets.md index a6eae83d46..4e1b17dad7 100644 --- a/docs/user-guide/api-mediation/configuration-extender-passtickets.md +++ b/docs/user-guide/api-mediation/configuration-extender-passtickets.md @@ -5,18 +5,18 @@ One option for enabling single sign on is by configuring Zowe to use PassTickets :::info Required Role: security administrator ::: -- [Overview of PassTickets](#overview-of-how-passtickets-are-used) +- [Overview of PassTickets](#overview-of-passtickets) - [Configuring Zowe to use PassTickets](#configuring-zowe-to-use-passtickets) - - [Enabling PassTicket support](#enabling-passticket-support) - - [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) +- [Enabling the use of PassTickets in your External Security Manager (ESM)](#enabling-the-use-of-passtickets-in-your-external-security-manager-esm) + - [Enabling PassTickets with ACF2](#enabling-passtickets-with-acf2) + - [Enabling PassTickets with Top Secret](#enabling-passtickets-with-top-secret) + - [Enabling PassTickets with RACF](#enabling-passtickets-with-racf) +- [Configuring security to allow 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 (Optional)](#adding-custom-http-auth-headers-to-store-user-id-and-passticket-optional) ## Overview of PassTickets @@ -30,6 +30,7 @@ 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 your External Security Manager (ESM) - Configuring security to allow the Zowe API Gateway to generate PassTickets for an API service @@ -100,7 +101,7 @@ To validate if a PassTicket is already defined, use the commands that correspond In your ESM command line interface or other security environment, execute the following commands: - ``` + ```rac RLIST APPL * ALL RLIST APPL ALL RLIST PTKTDATA SSIGNON ALL @@ -132,7 +133,7 @@ Follow these steps to enable PassTicket Support specific to your ESM. Consult wi 1. In your ESM command line interface or other security environment, define the application session key by entering the following commands, if the session key is not already defined. -``` +```acf2 SET PROFILE(PTKTDATA) DIV(SSIGNON) INSERT SSKEY() MULT-USE F ACF2,REBUILD(PTK),CLASS(P) @@ -149,7 +150,7 @@ This setting lets you reuse the same PassTicket multiple times. 2. Complete the PassTicket setup by entering the following commands: -``` +```acf2 F ACF2,REBUILD(PTK),CLASS(P) ``` @@ -162,7 +163,7 @@ SET RESOURCE(PTK) RECKEY IRRPTAUTH ADD(applid.userid UID() SERVICE(UPDATE,READ) ALLOW) ``` -* `` +- `` Specifies the Zowe server user ID You configured Zowe to use PassTickets using ACF2. @@ -183,7 +184,7 @@ Before you begin this procedure, verify that the `PTKTDATA` class and ownership The PTKTDATA resource is not a predefined class. ::: -``` +```tss TSS ADDTO(RDT) RESCLASS(PTKTDATA) RESCODE(n) ACLST(ALL,READ,UPDATE) MAXLEN(37) ``` @@ -195,13 +196,13 @@ Include `RESCODE(n)` in the range of 101 to 13F to make `PTKTDATA` a prefixed re 2. Assign ownership for the PassTicket resource (`IRRPTAUT`). Execute the following commands: -``` +```tss TSS ADDTO(department) PTKTDATA(IRRPTAUT) ``` -3. Define PassTicket for application ID _applid_ without replay protection. +3. Define PassTicket for application ID _applid_ -``` +```tss TSS ADDTO(NDT) PSTKAPPL() SESSKEY() SIGNMULTI ``` @@ -213,13 +214,13 @@ Specifies the application ID used for PassTicket validation to authenticate conn 4. Permit access to the PassTicket resource defined in the previous step for the LDAP Server by executing the following command: -``` +```tss TSS PERMIT() 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. - +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. @@ -234,13 +235,13 @@ You configured Zowe to use PassTickets using Top Secret. In your ESM command line interface or other security environment, execute the following command: -``` +```racf SETROPTS CLASSACT(PTKTDATA) RACLIST(PTKTDATA) ``` 2. Specify the application ID requiring access through PassTicket for the ZOWE server with the following commands: -``` +```racf RDEFINE APPL UACC(READ) SETROPTS CLASSACT(APPL) SETROPTS GENERIC(PTKTDATA) @@ -255,11 +256,11 @@ This name is usually provided by the site security administrator. 3. Define the profile for the application with the following command: -``` +```racf RDEFINE PTKTDATA UACC(NONE) APPLDATA('NO REPLAY PROTECTION') SSIGNON(KEYMASKED() APPLDATA('NO REPLAY PROTECTION') ``` -* **key-description** +- **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. Replace `key-description` with the application name defined previously. @@ -270,7 +271,7 @@ PassTickets for the API service must have the replay protection switched off. Th 4. Allow the application ID (_applid_) to use PassTickets: -``` +```racf PERMIT IRRPTAUTH.applid.* CLASS(PTKTDATA) ACCESS(UPDATE) ID(userid) ``` @@ -279,7 +280,7 @@ Specifies the value of the LDAP Server started task. 5. Refresh the RACF PTKTDATA definition with the new profile: -``` +```racf SETROPTS RACLIST(PTKTDATA) REFRESH ``` @@ -313,7 +314,7 @@ Grant the Zowe started task user ID permission to generate PassTickets for users **Example:** -```markup +```acf ACF SET RESOURCE(PTK) RECKEY IRRPTAUTH ADD(.- UID() SERVICE(UPDATE,READ) ALLOW) @@ -350,7 +351,7 @@ Grant the Zowe started task user ID permission to generate PassTickets for users **Example:** -```markup +```racf PERMIT IRRPTAUTH..* CL(PTKTDATA) ID() ACCESS(UPDATE) SETROPTS RACLIST(PTKTDATA) REFRESH ``` @@ -361,7 +362,7 @@ SETROPTS RACLIST(PTKTDATA) REFRESH In your ESM command line interface or other security environment, execute the following commands: -``` +```racf RLIST APPL ALL RLIST PTKTDATA IRRPTAUTH..* ALL ``` From 8c913cb5f496cb89a63e4aa20856b565da675275 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= Date: Wed, 31 Jul 2024 14:59:04 +0200 Subject: [PATCH 3/7] remove replay protection MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pablo Hernán Carle --- .../api-mediation/configuration-extender-passtickets.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/user-guide/api-mediation/configuration-extender-passtickets.md b/docs/user-guide/api-mediation/configuration-extender-passtickets.md index 4e1b17dad7..3e97e5eedb 100644 --- a/docs/user-guide/api-mediation/configuration-extender-passtickets.md +++ b/docs/user-guide/api-mediation/configuration-extender-passtickets.md @@ -257,7 +257,7 @@ This name is usually provided by the site security administrator. 3. Define the profile for the application with the following command: ```racf -RDEFINE PTKTDATA UACC(NONE) APPLDATA('NO REPLAY PROTECTION') SSIGNON(KEYMASKED() APPLDATA('NO REPLAY PROTECTION') +RDEFINE PTKTDATA UACC(NONE) SSIGNON(KEYMASKED()) ``` - **key-description** @@ -265,10 +265,6 @@ RDEFINE PTKTDATA UACC(NONE) APPLDATA('NO REPLAY PROTECTION') SSIGNON(K Replace `key-description` with the application name defined previously. -:::caution Important -PassTickets for the API service must have the replay protection switched off. This links a secured sign-on application key with the application. -::: - 4. Allow the application ID (_applid_) to use PassTickets: ```racf From e8a0dec2fe26260b2d0e83933d00f85ce9769d43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= Date: Wed, 31 Jul 2024 16:25:54 +0200 Subject: [PATCH 4/7] address review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pablo Hernán Carle --- .../api-mediation/configuration-extender-passtickets.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/user-guide/api-mediation/configuration-extender-passtickets.md b/docs/user-guide/api-mediation/configuration-extender-passtickets.md index 3e97e5eedb..6d124f40a2 100644 --- a/docs/user-guide/api-mediation/configuration-extender-passtickets.md +++ b/docs/user-guide/api-mediation/configuration-extender-passtickets.md @@ -135,16 +135,13 @@ Follow these steps to enable PassTicket Support specific to your ESM. Consult wi ```acf2 SET PROFILE(PTKTDATA) DIV(SSIGNON) -INSERT SSKEY() MULT-USE +INSERT SSKEY() F ACF2,REBUILD(PTK),CLASS(P) ``` - **applid** Specifies the application ID used for PassTicket validation to authenticate connections to the server. -- **MULT-USE** -This setting lets you reuse the same PassTicket multiple times. - - **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. @@ -203,7 +200,7 @@ TSS ADDTO(department) PTKTDATA(IRRPTAUT) 3. Define PassTicket for application ID _applid_ ```tss -TSS ADDTO(NDT) PSTKAPPL() SESSKEY() SIGNMULTI +TSS ADDTO(NDT) PSTKAPPL() SESSKEY() ``` - **applid** From 32b993e9969eb9b3ba66c2d9076884db4da2baa5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= Date: Fri, 2 Aug 2024 10:57:15 +0200 Subject: [PATCH 5/7] add note about re-enabling replay protection for old MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pablo Hernán Carle --- .../api-mediation/configuration-extender-passtickets.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/user-guide/api-mediation/configuration-extender-passtickets.md b/docs/user-guide/api-mediation/configuration-extender-passtickets.md index 6d124f40a2..b935395151 100644 --- a/docs/user-guide/api-mediation/configuration-extender-passtickets.md +++ b/docs/user-guide/api-mediation/configuration-extender-passtickets.md @@ -36,6 +36,9 @@ Configuring Zowe to use PassTickets involves two processes: ### Enabling the use of PassTickets in your External Security Manager (ESM) +:::note +Since Zowe 2.17 release it is no longer needed to disable the replay protection. If you are upgrading Zowe from a prior release, these protections can be activated again. + 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 From 7c7646eddfe37fd250a6df29d790485055025369 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= Date: Fri, 2 Aug 2024 14:38:04 +0200 Subject: [PATCH 6/7] try fix indent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pablo Hernán Carle --- .../configuration-extender-passtickets.md | 245 +++++++++--------- 1 file changed, 127 insertions(+), 118 deletions(-) diff --git a/docs/user-guide/api-mediation/configuration-extender-passtickets.md b/docs/user-guide/api-mediation/configuration-extender-passtickets.md index b935395151..493ab83728 100644 --- a/docs/user-guide/api-mediation/configuration-extender-passtickets.md +++ b/docs/user-guide/api-mediation/configuration-extender-passtickets.md @@ -47,80 +47,83 @@ To validate if a PassTicket is already defined, use the commands that correspond - **Validating an existing PassTicket for ACF2**
- - Click here for details about validating an existing PassTicket for ACF2. + + Click here for details about validating an existing PassTicket for ACF2. + In your ESM command line interface or other security environment, execute the following commands: - ``` - SET RESOURCE(SAF) - LIST LIKE(-) + ```acf2 + SET RESOURCE(SAF) + LIST LIKE(-) - SET RESOURCE(SAF) - LIST LIKE(-) + SET RESOURCE(SAF) + LIST LIKE(-) - SET PROFILE(PTKTDATA) DIVISION(SSIGNON) - LIST LIKE(-) + SET PROFILE(PTKTDATA) DIVISION(SSIGNON) + LIST LIKE(-) - SET RESOURCE(PTK) - LIST LIKE(IRRPTAUTH-) + SET RESOURCE(PTK) + LIST LIKE(IRRPTAUTH-) ``` - - **`-`** - A wildcard symbol that lists all resources + - **`-`** + A wildcard symbol that lists all resources - - **`-`** - Lists everything related to specified applid in a resource (in this case, SAF), or specified in a profile (in this case, PTKTDATA) + - **`-`** + Lists everything related to specified applid in a resource (in this case, SAF), or specified in a profile (in this case, PTKTDATA)
- **Validating an existing PassTicket for Top Secret**
- - Click here for details about validating an existing PassTicket for Top Secret. + + Click here for details about validating an existing PassTicket for Top Secret. + In your ESM command line interface or other security environment, execute the following commands: - ``` - TSS WHOHAS APPL() - TSS WHOHAS PTKTDATA() - TSS WHOHAS PTKTDATA(IRRPTAUTH..) + ```tss + TSS WHOHAS APPL() + TSS WHOHAS PTKTDATA() + TSS WHOHAS PTKTDATA(IRRPTAUTH..) ``` - - **`.`** - A wildcard symbol that lists all resources + - **`.`** + A wildcard symbol that lists all resources - - **`IRRPTAUTH..`** - Returns everything about the specified applid for IRRPTAUTH + - **`IRRPTAUTH..`** + Returns everything about the specified applid for IRRPTAUTH
- **Validating an existing PassTicket for RACF**
- - Click here for details about validating an existing PassTicket for RACF. + + Click here for details about validating an existing PassTicket for RACF. + In your ESM command line interface or other security environment, execute the following commands: - ```rac - RLIST APPL * ALL - RLIST APPL ALL - RLIST PTKTDATA SSIGNON ALL - RLIST PTKTDATA IRRPTAUTH..* ALL + ```racf + RLIST APPL * ALL + RLIST APPL ALL + RLIST PTKTDATA SSIGNON ALL + RLIST PTKTDATA IRRPTAUTH..* ALL ``` Ensure that you validate PKTDATA access for APPL. - - **`*`** - A wildcard symbol that resturns all resources + - **`*`** + A wildcard symbol that resturns all resources - - **`RLIST PTKTDATA SSIGNON ALL`** - Validates all applid for PTKDATA class + - **`RLIST PTKTDATA SSIGNON ALL`** + Validates all applid for PTKDATA class - - **`RLIST PTKTDATA IRRPTAUTH..* ALL`** - Validates all applid permissions for PTKDATA class + - **`RLIST PTKTDATA IRRPTAUTH..* ALL`** + Validates all applid permissions for PTKDATA class
@@ -131,40 +134,41 @@ Follow these steps to enable PassTicket Support specific to your ESM. Consult wi #### Enabling PassTickets with ACF2
- - Click here for details about configuring Zowe to use PassTickets using ACF2. + + Click here for details about configuring Zowe to use PassTickets using ACF2. + 1. In your ESM command line interface or other security environment, define the application session key by entering the following commands, if the session key is not already defined. -```acf2 -SET PROFILE(PTKTDATA) DIV(SSIGNON) -INSERT SSKEY() -F ACF2,REBUILD(PTK),CLASS(P) -``` + ```acf2 + SET PROFILE(PTKTDATA) DIV(SSIGNON) + INSERT SSKEY() + F ACF2,REBUILD(PTK),CLASS(P) + ``` -- **applid** -Specifies the application ID used for PassTicket validation to authenticate connections to the server. + - **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. + - **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. 2. Complete the PassTicket setup by entering the following commands: -```acf2 -F ACF2,REBUILD(PTK),CLASS(P) -``` + ```acf2 + F ACF2,REBUILD(PTK),CLASS(P) + ``` -The PassTicket record is now active in the system. + 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() SERVICE(UPDATE,READ) ALLOW) -``` + ```acf2 + SET RESOURCE(PTK) + RECKEY IRRPTAUTH ADD(applid.userid UID() SERVICE(UPDATE,READ) ALLOW) + ``` -- `` -Specifies the Zowe server user ID + - `` + Specifies the Zowe server user ID You configured Zowe to use PassTickets using ACF2. @@ -173,38 +177,39 @@ You configured Zowe to use PassTickets using ACF2. #### Enabling PassTickets with Top Secret
- - Click here for details about configuring Zowe to use PassTickets using Top Secret. + + Click here for details about configuring Zowe to use PassTickets using Top Secret. + Before you begin this procedure, verify that the `PTKTDATA` class and ownership for the PassTicket resource (`IRRPTAUT`) have not already been defined. 1. Update the resource descriptor table (RDT) to define the `PTKTDATA` class by entering the following commands: -:::note -The PTKTDATA resource is not a predefined class. -::: + :::note + The PTKTDATA resource is not a predefined class. + ::: -```tss -TSS ADDTO(RDT) RESCLASS(PTKTDATA) RESCODE(n) ACLST(ALL,READ,UPDATE) MAXLEN(37) -``` + ```tss + TSS ADDTO(RDT) RESCLASS(PTKTDATA) RESCODE(n) ACLST(ALL,READ,UPDATE) MAXLEN(37) + ``` -The PTKTDATA resource is added to the RDT. + The PTKTDATA resource is added to the RDT. -:::note -Include `RESCODE(n)` in the range of 101 to 13F to make `PTKTDATA` a prefixed resource class. -::: + :::note + Include `RESCODE(n)` in the range of 101 to 13F to make `PTKTDATA` a prefixed resource class. + ::: 2. Assign ownership for the PassTicket resource (`IRRPTAUT`). Execute the following commands: -```tss -TSS ADDTO(department) PTKTDATA(IRRPTAUT) -``` + ```tss + TSS ADDTO(department) PTKTDATA(IRRPTAUT) + ``` 3. Define PassTicket for application ID _applid_ -```tss -TSS ADDTO(NDT) PSTKAPPL() SESSKEY() -``` + ```tss + TSS ADDTO(NDT) PSTKAPPL() SESSKEY() + ``` - **applid** Specifies the application ID used for PassTicket validation to authenticate connections to the server. @@ -214,9 +219,9 @@ Specifies the application ID used for PassTicket validation to authenticate conn 4. Permit access to the PassTicket resource defined in the previous step for the LDAP Server by executing the following command: -```tss -TSS PERMIT() PTKTDATA(IRRPTAUTH.applid) ACCESS(UPDATE) -``` + ```tss + TSS PERMIT() 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. @@ -228,24 +233,25 @@ You configured Zowe to use PassTickets using Top Secret. #### Enabling PassTickets with RACF
- - Click here for details about configuring Zowe to use PassTickets using RACF. + + Click here for details about configuring Zowe to use PassTickets using RACF. + 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: + In your ESM command line interface or other security environment, execute the following command: -```racf -SETROPTS CLASSACT(PTKTDATA) RACLIST(PTKTDATA) -``` + ```racf + SETROPTS CLASSACT(PTKTDATA) RACLIST(PTKTDATA) + ``` 2. Specify the application ID requiring access through PassTicket for the ZOWE server with the following commands: -```racf -RDEFINE APPL UACC(READ) -SETROPTS CLASSACT(APPL) -SETROPTS GENERIC(PTKTDATA) -``` + ```racf + RDEFINE APPL UACC(READ) + SETROPTS CLASSACT(APPL) + SETROPTS GENERIC(PTKTDATA) + ``` - ***applid** A one to 8 character name designated for the application. @@ -256,9 +262,9 @@ This name is usually provided by the site security administrator. 3. Define the profile for the application with the following command: -```racf -RDEFINE PTKTDATA UACC(NONE) SSIGNON(KEYMASKED()) -``` + ```racf + RDEFINE PTKTDATA UACC(NONE) SSIGNON(KEYMASKED()) + ``` - **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. @@ -267,18 +273,18 @@ Replace `key-description` with the application name defined previously. 4. Allow the application ID (_applid_) to use PassTickets: -```racf -PERMIT IRRPTAUTH.applid.* CLASS(PTKTDATA) ACCESS(UPDATE) ID(userid) -``` + ```racf + PERMIT IRRPTAUTH.applid.* CLASS(PTKTDATA) ACCESS(UPDATE) ID(userid) + ``` - **userid** Specifies the value of the LDAP Server started task. 5. Refresh the RACF PTKTDATA definition with the new profile: -```racf -SETROPTS RACLIST(PTKTDATA) REFRESH -``` + ```racf + SETROPTS RACLIST(PTKTDATA) REFRESH + ``` You configured Zowe to use PassTickets using RACF. @@ -303,19 +309,20 @@ Use the configuration format that corresponds to your ESM as presented in the fo #### Generating PassTickets using ACF2
- - Click here for details about generating PassTickets using ACF2. + + Click here for details about generating PassTickets using ACF2. + Grant the Zowe started task user ID permission to generate PassTickets for users of the API service. **Example:** ```acf -ACF -SET RESOURCE(PTK) -RECKEY IRRPTAUTH ADD(.- UID() SERVICE(UPDATE,READ) ALLOW) -F ACF2,REBUILD(PTK),CLASS(P) -END + ACF + SET RESOURCE(PTK) + RECKEY IRRPTAUTH ADD(.- UID() SERVICE(UPDATE,READ) ALLOW) + F ACF2,REBUILD(PTK),CLASS(P) + END ```
@@ -323,16 +330,17 @@ END #### Generating PassTickets using Top Secret
- -Click here for details about generating PassTickets using Top Secret. + + Click here for details about generating PassTickets using Top Secret. + Grant the Zowe started task user ID permission to generate PassTickets for users of the API service. **Example:** -```markup -TSS PERMIT() PTKTDATA(IRRPTAUTH..) ACCESS(READ,UPDATE) -TSS REFRESH +```tss + TSS PERMIT() PTKTDATA(IRRPTAUTH..) ACCESS(READ,UPDATE) + TSS REFRESH ```
@@ -340,16 +348,17 @@ TSS REFRESH #### Generating PassTickets using RACF
- - Click here for details about generating PassTickets using RACF. + + Click here for details about generating PassTickets using RACF. + Grant the Zowe started task user ID permission to generate PassTickets for users of the API service. **Example:** ```racf -PERMIT IRRPTAUTH..* CL(PTKTDATA) ID() ACCESS(UPDATE) -SETROPTS RACLIST(PTKTDATA) REFRESH + PERMIT IRRPTAUTH..* CL(PTKTDATA) ID() ACCESS(UPDATE) + SETROPTS RACLIST(PTKTDATA) REFRESH ```
@@ -359,8 +368,8 @@ SETROPTS RACLIST(PTKTDATA) REFRESH In your ESM command line interface or other security environment, execute the following commands: ```racf -RLIST APPL ALL -RLIST PTKTDATA IRRPTAUTH..* ALL + RLIST APPL ALL + RLIST PTKTDATA IRRPTAUTH..* ALL ``` - **applid** From d61adc4173ac3521eaef92364afb18903f332963 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= Date: Fri, 2 Aug 2024 16:14:15 +0200 Subject: [PATCH 7/7] remove toc in article, fix note MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pablo Hernán Carle --- .../configuration-extender-passtickets.md | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/docs/user-guide/api-mediation/configuration-extender-passtickets.md b/docs/user-guide/api-mediation/configuration-extender-passtickets.md index 493ab83728..c7a878d4e9 100644 --- a/docs/user-guide/api-mediation/configuration-extender-passtickets.md +++ b/docs/user-guide/api-mediation/configuration-extender-passtickets.md @@ -5,19 +5,6 @@ One option for enabling single sign on is by configuring Zowe to use PassTickets :::info Required Role: security administrator ::: -- [Overview of PassTickets](#overview-of-passtickets) -- [Configuring Zowe to use PassTickets](#configuring-zowe-to-use-passtickets) -- [Enabling the use of PassTickets in your External Security Manager (ESM)](#enabling-the-use-of-passtickets-in-your-external-security-manager-esm) - - [Enabling PassTickets with ACF2](#enabling-passtickets-with-acf2) - - [Enabling PassTickets with Top Secret](#enabling-passtickets-with-top-secret) - - [Enabling PassTickets with RACF](#enabling-passtickets-with-racf) -- [Configuring security to allow 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 (Optional)](#adding-custom-http-auth-headers-to-store-user-id-and-passticket-optional) - ## 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. @@ -38,6 +25,7 @@ Configuring Zowe to use PassTickets involves two processes: :::note Since Zowe 2.17 release it is no longer needed to disable the replay protection. If you are upgrading Zowe from a prior release, these protections can be activated again. +::: 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).