How to configure a locally generated JWT

To call an API with a locally generated JWT, you must configure the jwtBuilder and zosconnect_authTokenLocal elements in the server.xml configuration file and define SAF SURROGAT profiles.

1. Typically, the z/OS subsystem that calls the z/OS Connect Server is authenticated using basic authentication or client authentication.
   • For more information on enabling basic authentication, see API requester basic authentication to IBM z/OS Connect.
   • For more information on enabling client authentication, see API requester client certificate authentication to IBM z/OS Connect.

   Note: Locally generated JWTs can be used without an authenticated link user ID, in this case the SAF SURROGAT profile checks are performed against the SAF unauthenticated user ID.
2. Define the appropriate SURROGAT profile definition in RACF. Consult your security administrator to confirm the appropriate definitions to use for your environment.
   1. Define a profile named assertedid.BAQTOKEN in the SURROGAT class, where assertedid represents the z/OS application asserted user ID. For example, if the asserted identity is FRED, enter the RACF command:

      RDEFINE SURROGAT FRED.BAQTOKEN UACC(NONE)

   2. Grant the authenticated link user ID READ access to the SURROGAT profile created in the previous step.
      For example, if the link user ID is LINKID1 and is allowed to generate JWTs containing a "sub" claim value of FRED, enter the RACF command:

      PERMIT FRED.BAQTOKEN CLASS(SURROGAT) ID(LINKID1) ACCESS(READ)

   3. Repeat these commands for other z/OS application asserted user IDs and authenticated link user IDs that are used for locally generated JWTs.
   4. After you have entered all the RACF SURROGAT class profile commands, refresh the SURROGAT class. Enter the RACF command:

      SETROPTS RACLIST(SURROGAT) REFRESH

   Alternatively: If the authenticated link user ID is allowed to generate JWTs containing the "sub" claim value for any z/OS application asserted user IDs, you can choose to use a generic profile definition. For example:

   RDEFINE SURROGAT *.BAQTOKEN UACC(NONE)

   PERMIT *.BAQTOKEN CLASS(SURROGAT) ID(LINKID1) ACCESS(READ)

   Note: It is recommended that the SAF unauthenticated user ID is authorized to use only the minimum number of SAF resources. An authenticated link user ID is typically used. However, if you choose not to have a link user ID and allow API requester requests to run under the SAF unauthenticated user ID, then you will need to permit that user ID READ access to the appropriate SURROGAT profile definitions. The default SAF unauthenticated user ID is WSGUEST. As the SAF unauthenticated user ID is defined with the RESTRICTED attribute, it must be explicitly permitted access to a nongeneric profile name. For more information, see SAF unauthenticated user ID and Defining restricted user IDs in the z/OS documentation.
3. Configure a jwtBuilder element to specify the registered claims and additional attributes that are used to generate a JWT.
   For example,

   
   <jwtBuilder
       id="myLocalJWTBuilder"
       scope="scope1"
       audiences="myApp1"
       signatureAlgorithm="RS256"
       expiresInSeconds="30m"
       jti="true"
       nbfOffset="50s"
       keyStoreRef="myKeyStore"
       keyAlias="keyLabel" />

   By default the "iss" (Issuer) claim is set to https://{hostname}:{httpsPort}/jwt/{jwtBuilderId} where hostname and httpsPort are the hostname and HTTPS port of the z/OS Connect Server and jwtBuilderId is the id attribute value of the jwtBuilder element. To specify an alternative value for the "iss" (Issuer) claim, configure the issuer attribute of the jwtBuilder element. For more information about how to configure the jwtBuilder element, see JWT Builder (jwtBuilder) in the WebSphere Application Server for z/OS Liberty documentation.

   Note:

   • The claims attribute on the jwtBuilder allows only existing user attributes that are defined for the subject of this JWT in the user registry to be included as claims in the JWT. To specify public and private claim name value pairs, use the claims subelement on the zosconnect_authTokenLocal element as shown in Step 4.
   • The value for the registered claim "iat" (Issued At) is automatically set when the JWT is generated locally by the z/OS Connect Server.
4. Configure a zosconnect_authTokenLocal element to specify the parameters that are used to generate the JWT that is used to authenticate with the RESTful API endpoint. The parameters include a reference to the jwtBuilder element, public and private claims, and the HTTP header name that is used to contain the JWT on the request to the RESTful API endpoint.
   For example,

   
   <zosconnect_authTokenLocal id="myLocalJWTConfig"  
       tokenGeneratorRef="myLocalJWTBuilder"
       header="myJWTHeader">
       <claims>{"branch":"Eastern",
                "dept":"insurance"}</claims>
   </zosconnect_authTokenLocal>

   Where:

   • The tokenGeneratorRef attribute references the jwtBuilder element with the ID value myLocalJWTBuilder that is defined in Step 3.
   • The header attribute specifies the name of the HTTP header that contains the JWT on the API request to the RESTful API endpoint. If you do not specify the header attribute, the HTTP Authorization header is used by default.
   • The claims subelement specifies the public and private claims as a JSON string.

   For more information about the zosconnect_authTokenLocal element, see zosconnect_authTokenLocal in the configuration elements section.

   Note:

   • The claims subelement is intended to specify only public and private claims. If registered claims, such as "aud" (Audience), are specified on the claims subelement, then these values overwrite the corresponding values that are configured on the jwtBuilder element that is referenced by the tokenGeneratorRef attribute of the zosconnect_authTokenLocal element. If the "sub" claim is specified on the claims subelement, its value is overwritten by the z/OS Connect Server to be the z/OS application asserted user ID. Registered claims are defined in the IANA JSON Web Token Claims Registry.
   • If the JSON string value of the claims subelement contains XML markup characters, such as <, > and &, then include the JSON string inside a CDATA section. For more information, see zosconnect_authTokenLocal_claims.
5. Configure the zosconnect_endpointConnection element to identify the locally generated JWT authentication data.
   For example,

   
   <zosconnect_endpointConnection id="conn"
       host="https://api.server.com" 
       port="9443"
       authenticationConfigRef="myLocalJWTConfig" />

   Where:

   • The authenticationConfigRef attribute references the zosconnect_authTokenLocal element with the ID value myLocalJWTConfig that was defined in Step 4.