Enabling single sign on for extending services via PassTicket configuration

One option to enable single sign-on (SSO) to your extending REST API services is to configure Zowe API ML PassTickets. Passtickets are encoded and encrypted and are only valid for a few minutes after you generate them. PassTickets enable z/OS components and products to authenticate a user ID without storing or caching z/OS passwords or sending the passwords through the network. 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.

Required Role: security administrator

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 support of JWT or a client certificate 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. The API Gateway provides the user ID and password in the Authorization header which serves as basic authentication in HTTP requests using the Basic authentication scheme.

Configuring Zowe to use PassTickets

Configuring Zowe to use PassTickets involves two processes:

1. Enabling the use of PassTickets in your External Security Manager (ESM)
2. 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)

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.

To allow an API service extender to onboard a second (or subsequent) service using httpBasicPassTicket without repeating unnecessary ESM-level setup, reference the following comparison table to determine your path:

Step	First service	Second+ service
Activate PTKTDATA class	Required	Already done
Define APPLID	Required	Required (new APPLID)
Set session key (SSIGNON)	Required	Required (new key)
Permit ZWESVUSR for IRRPTAUTH	Required	Required (new APPLID)

First service onboarding with PassTickets

Follow this path if you are setting up PassTickets in your ESM for the first time.

Pre-requisites:

• Known APPLID
• ESM admin authority
• PTKTDATA class not yet activated

First service onboarding with PassTickets requires a full ESM setup. Requirements for this first service onboarding include:

• Activation of the PTKTDATA class
• Defining your APPLID
• Setting the session key
• Permitting the ZWESVUSR user ID

The following example presents the full first service configuration for IBM RACF.

Example:

SETROPTS CLASSACT(PTKTDATA) RACLIST(PTKTDATA)
SETROPTS CLASSACT(APPL)
SETROPTS GENERIC(PTKTDATA)
RDEFINE APPL MYAPPL1 UACC(READ)
RDEFINE PTKTDATA MYAPPL1 UACC(NONE) APPLDATA('NO REPLAY PROTECTION') SSIGNON(KEYMASKED(<key>))
RDEFINE PTKTDATA IRRPTAUTH.MYAPPL1.* UACC(NONE)
PERMIT IRRPTAUTH.MYAPPL1.* CLASS(PTKTDATA) ACCESS(UPDATE) ID(ZWESVUSR)
SETROPTS RACLIST(PTKTDATA) REFRESH

Follow all steps in the ESM-specific sections presented later in this article. For more information, see Configuring your specific External Security Manager (ESM).

Second and subsequent service onboarding with PassTickets

Follow this path to onboard a second, or subsequent service.

Pre-requisites:

• PassTickets already enabled (PTKTDATA active, session keys exist)
• ZWESVUSR already permitted for at least one existing APPLID
• New APPLID known

When onboarding subsequent services, the activation of the PTKTDATA class and configuring global session key parameters have already been performed. These are one-time operations and are already complete in your environment after initial service onboarding.

Ensure that you satisfy the following requirements:

• Define the new APPLID
• Set the new APPLID unique session key
• Run the PERMIT step for the new APPLID

note

You do not need to repeat the full ESM setup. In the ESM-specific instructions presented later in this article, you may skip the class activation steps.

The following example presents the second or subsequent service configuration for IBM RACF.

Example:

RDEFINE APPL MYAPPL2 UACC(READ)
RDEFINE PTKTDATA MYAPPL2 UACC(NONE) APPLDATA('NO REPLAY PROTECTION') SSIGNON(KEYMASKED(<key>))
RDEFINE PTKTDATA IRRPTAUTH.MYAPPL2.* UACC(NONE)
PERMIT IRRPTAUTH.MYAPPL2.* CLASS(PTKTDATA) ACCESS(UPDATE) ID(ZWESVUSR)
SETROPTS RACLIST(PTKTDATA) REFRESH

note

SETROPTS CLASSACT(PTKTDATA) is skipped for second and subsequent service configuration as this operation was already performed during first-service onboarding.

Configuring your specific External Security Manager (ESM)

To complete the PassTicket setup for first service onboarding, choose the configuration instructions that correspond to your system's ESM (ACF2, Top Secret, or IBM RACF).

tip

To validate if a PassTicket is already defined, list the APPL and PTKTDATA with a command corresponding to your ESM. Output indicates if a PassTicket is already defined. No results after issuing an ESM command indicates that a PassTicket is not defined. If a PassTicket is defined, the access of the ZWESVUSR can be determined.

Validating an existing PassTicket for ACF2

Click here for procedure details about validating an existing PassTicket for ACF2.

In your ESM command line interface or other security environment, perform the following steps:

1. Issue a SHOW CLASMAP command in TSO ACF to verify if the APPL resource is defined in the GSO. Note the 3 character type code associated with APPL. If APPL does not appear in the SHOW CLASMAP listing, run the following commands:

   SET CONTROL(GSO)
   INSERT CLASMAP.appl RESOURCE(APPL) RSRCTYPE(APL)
   F ACF2,REFRESH(CLASMAP)

2. Replace 'APL' with the type code listed in the SHOW CLASMAP output:

   SET RESOURCE(APL)
   LIST LIKE(<applid>-)

3. Verify if PTKTDATA is defined, by executing the following commands:

   SET PROFILE(PTKTDATA) DIVISION(SSIGNON)
   LIST LIKE(<applid>-)
   SET RESOURCE(PTK)
   LIST LIKE(IRRPTAUTH-)

• -
  A wildcard symbol that lists all resources

• <applid>-
  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 command details about validating an existing PassTicket for Top Secret.

1. In your ESM command line interface or other security environment, execute the following commands:

   TSS WHOHAS APPL(<applid>)
   TSS WHOHAS PTKTDATA(IRRPTAUTH.<applid>.)

2. If APPL and PTKTDATA are not yet defined, follow the steps to create them as described in the Enabling PassTickets with Top Secret section.

• .
  A wildcard symbol that lists all resources

• IRRPTAUTH.<applid>.
  Returns everything about the specified applid for IRRPTAUTH

Validating an existing PassTicket for IBM RACF

Click here for command details about validating an existing PassTicket for IBM RACF.

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 PTKTDATA 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

Enabling PassTickets with ACF2

Click here for command details about configuring Zowe to use PassTickets using ACF2.

1. Issue the SHOW CLASMAP command in TSO ACF to identity the 3 character type code associated with APPL. Replace 'APL' with the type code listed in the SHOW CLASMAP output:

   SET RESOURCE(APL)
   RECKEY <applid> ADD(UID(<user>) ALLOW)
   F ACF2,REBUILD(APL)

2. 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)
   INSERT <applid> SSKEY(<key-description>) MULT-USE
   F ACF2,REBUILD(PTK),CLASS(P)

• 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.

3. Complete the PassTicket setup by entering the following commands:

       F ACF2,REBUILD(PTK),CLASS(P)

   The PassTicket record is now active in the system.

4. 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(<userid>) SERVICE(UPDATE,READ) ALLOW)

• userid
  Specifies the Zowe server user ID

You configured Zowe to use PassTickets for single sign on using ACF2.

Enabling PassTickets with Top Secret

Click here for command 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 (IRRPTAUTH) have not already been defined as described in the previous tip.

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.

   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 (IRRPTAUTH). Execute the following commands:

   TSS ADDTO(<department>) PTKTDATA(IRRPTAUTH) 

• department
  Specifies the department for PTKTDATA(IRRPTAUTH). The default department is TSODEPT1.

3. Define PassTicket for application ID applid without replay protection:

   TSS ADDTO(NDT) PSTKAPPL(<applid>) SESSKEY(<key-description>) SIGNMULTI

• 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:

   TSS PERMIT(<stc-userid>) PTKTDATA(IRRPTAUTH.<applid>) ACCESS(UPDATE)

• stc-userid
  Specifies the Accessor ID (ACID) that you created when you created LDAP Server started task User IDs.

Default: CALDAP

You configured Zowe to use PassTickets using Top Secret.

Enabling PassTickets with IBM RACF

Click here for command details about configuring Zowe to use PassTickets using IBM 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:

       SETROPTS CLASSACT(PTKTDATA) RACLIST(PTKTDATA)

2. Specify the application ID requiring access through PassTicket for the Zowe server with the following commands:

   RDEFINE APPL <applid> UACC(READ)
   SETROPTS CLASSACT(APPL)
   SETROPTS GENERIC(PTKTDATA)

• applid
  Specifies the application ID used for PassTicket validation to authenticate connections to the server. (One to 8 characters)

  note

  This name is usually provided by the site security administrator.

3. Define the profile for the application with the following command:

   RDEFINE PTKTDATA  <applid> UACC(NONE) APPLDATA('NO REPLAY PROTECTION') SSIGNON(KEYMASKED(<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. Replace key-description with the application name defined previously.

Important

PassTickets for the API service must have the replay protection switched off. This links a secured sign-on application key with the application.

5. Define the profile IRRPTAUTH in PTKTDATA class for the <applid>

   RDEFINE PTKTDATA IRRPTAUTH.<applid>.* UACC(NONE)

6. Allow the application ID (applid) to use PassTickets:

   PERMIT IRRPTAUTH.<applid>.* CLASS(PTKTDATA) ACCESS(UPDATE) ID(<userid>)

• userid
  Specifies the value of the LDAP Server started task.

7. Refresh the IBM RACF PTKTDATA definition with the new profile:

   SETROPTS RACLIST(PTKTDATA) REFRESH

You configured Zowe to use PassTickets using IBM RACF.

Configuring security to allow Zowe API Gateway to generate PassTickets for an API service

As a security administrator, you can issue security commands to allow the Zowe started task user ID to generate PassTickets for the API service.

Specify the following variables when generating PassTickets for the API service to enable the Zowe started task user ID:

• applid
  The APPLID value used by the API service for PassTicket support (for example, OMVSAPPL)

• 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.

Use the configuration format that corresponds to your ESM as presented in the following examples.

Generating PassTickets using ACF2

Click here for command 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
    SET RESOURCE(PTK)
    RECKEY IRRPTAUTH ADD(<applid>.- UID(<zowe-user-id>) SERVICE(UPDATE,READ) ALLOW)
    F ACF2,REBUILD(PTK),CLASS(P)
    END

Generating PassTickets using Top Secret

Click here for command 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:

    TSS PERMIT(<zowe-user-id>) PTKTDATA(IRRPTAUTH.<applid>.) ACCESS(READ,UPDATE)
    TSS REFRESH

Generating PassTickets using IBM RACF

Click here for command details about generating PassTickets using IBM RACF.

Grant the Zowe started task user ID permission to generate PassTickets for users of the API service.

Example:

    RDEFINE PTKTDATA IRRPTAUTH.<applid>.* UACC(NONE)
    PERMIT IRRPTAUTH.<applid>.* CL(PTKTDATA) ID(<zowe-user-id>) ACCESS(UPDATE)
    SETROPTS RACLIST(PTKTDATA) REFRESH

Verifying your PassTicket Application

In your ESM command line interface or other security environment, execute the commands that correspond to your ESM:

Verifying PassTickets using ACF2

Click here for command details for ACF2.

ACF2:

Replace 'APL' with the type code listed in the SHOW CLASMAP output:

SET RESOURCE(APL)
LIST LIKE(<applid>-)
SET RESOURCE(PTK)
LIST LIKE(IRRPTAUTH-)

• applid
  Specifies the application ID used for PassTicket validation to authenticate connections to the server

Successful execution of this validation command shows your application and the specific access of the application.

Verifying PassTickets using Top Secret

Click here for command details for Top Secret.

TSS:

TSS WHOHAS APPL(<applid>)
TSS WHOHAS PTKTDATA(IRRPTAUTH.<applid>)

Verifying PassTickets using IBM RACF

Click here for command details for IBM RACF

IBM RACF:

 RLIST APPL <applid> ALL
 RLIST PTKTDATA IRRPTAUTH.<applid>.* ALL

Output example:

 CLASS      NAME
 -----      ----
 PTKTDATA   IRRPTAUTH.ZWEADMIN.* (G)

 USER      ACCESS
 ----      ------
 ZWESVUSR  UPDATE

(Optional) Adding custom HTTP Auth headers to store user ID and PassTicket

If a downstream (southbound) service needs to consume the PassTicket as well as 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. The southbound service must use the httpBasicPassTicket scheme in order to leverage this functionality. Once the HTTP headers names are defined, each request to the southbound service contains the PassTicket and the user ID in the custom headers.

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 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.