Start of change

Enabling JSON Web Token support

You can configure the z/OSMF server to build and use JSON Web Token (JWT) tokens.

z/OSMF supports the use of JWT tokens, as follows:
  • The z/OSMF server returns a JWT token after the user authenticates with the z/OSMF server
  • The z/OSMF-provided JWT token can be decrypted by a remote web application with or without requiring a connection to the z/OSMF server.
  • The z/OSMF-provided JWT token can be used to access z/OSMF REST services, similar to the use of LTPA tokens.

By default, the JWT function is disabled on the z/OSMF server. For information about enabling the JWT function, see the sections that follow.

How to enable JWT function on z/OSMF server

To enable the JWT function on z/OSMF server, do the following:
  1. Copy the file server_override.xml from <product_dir>/defaults/servers/zosmfServer/ to < user_dir >/configuration
    Where:
    • <product_dir> is the z/OSMF product directory. By default, this is /usr/lpp/zosmf
    • < user_dir > is the z/OSMF data directory. By default, this is /global/zosmf
  2. Set the permissions to 755 for the file server_override.xml in < user_dir >/configuration. For example: 
    chmod 755 < user_dir >/configuration/server_override.xml
  3. Restart the z/OSMF server.

As a result, the JWT support is enabled with default values. Usually, the default values are sufficient for most installations.

How to obtain the JWT token from the z/OSMF server

On successful SAF authentication with the z/OSMF server, an application can receive both the JWT token and the LTPA token.

In the following example, assume that the POST request is issued with a valid user ID and password. If so, the JWT token is stored in the browser cookies: 
POST /zosmf/services/authenticate

For more information about authenticating with z/OSMF, see IBM z/OS Management Facility Programming Guide.

How to configure the JWT settings for the z/OSMF server

You can customize different aspects of the JWT token processing, as described in the following sections:

JWT Single Sign On

In the server_override.xml file, locate the following statement. Here, you specify the settings for configuring JWT Single Sign On. Start of change
<jwtSso cookieName="jwtToken" jwtBuilderRef="zOSMFBuilder" includeLtpaCookie="true" useLtpaIfJwtAbsent="true" />
End of change
The parameters of this statement are described in Table 1.
Table 1. Statement for configuring JWT single sign-on
Parameter Type Default value Description
cookieName String jwtToken Name of the cookie that is used to store the JWT token.
jwtBuilderRef A reference to top-level jwtBuilder element (string). zOSMFBuilder A reference to the JWT Builder configuration element in server.xml that describes how to build the JWT token.
includeLtpaCookie Boolean true After successful authentication with a JWT token, include an LTPA cookie in addition to the JWT cookie.

z/OSMF requires this setting to be TRUE.
useLtpaIfJwtAbsent Boolean true If the JWT cookie is missing, attempt to process an LTPA cookie if it is present.

z/OSMF requires this setting to be TRUE.

For more information, see https://www.ibm.com/support/knowledgecenter/SS7K4U_liberty/com.ibm.websphere.liberty.autogen.nd.doc/ae/rwlp_config_jwtSso.html

JWT builder

In the server_override.xml file, locate the following statement. Here, you can specify the elements and attributes that are used to build the JWT token. Start of change
<jwtBuilder id="zOSMFBuilder" issuer="zOSMF" keyAlias="DefaultzOSMFCert.IZUDFLT" expiresInSeconds="${izu.ltpa.expiration}"/>
End of change
The parameters of this statement are described in Table 2.
Table 2. Statement for configuring the JWT builder
Parameter Type Default value Description
id String zOSMFBuilder This ID is used to identify the JWT builder.
issuer String zOSMF The issuer information.
keyAlias String DefaultzOSMFCert.IZUDFLT A key alias name that is used to locate the private key for signing the token with an asymmetric algorithm. This value is the certificate label value.
expiresInSeconds A time period with second precision ${izu.ltpa.expiration} Indicates the token expiration time in seconds. z/OSMF requires JWT token expiration time be equal to LTPA token expiration time, so use one variable to set it. This value can be set by the statement SESSION_EXPIRE in parmlib.

For more information, see https://www.ibm.com/support/knowledgecenter/SS7K4U_liberty/com.ibm.websphere.liberty.autogen.nd.doc/ae/rwlp_config_jwtBuilder.html

MicroProfile JWT token

In the server_override.xml file, locate the following statement, which is used to configure the MicroProfile JWT token: Start of change
<mpJwt id="myMpJwt" issuer="zOSMF" jwksUri="https://${izu.jwks.hostname}:${izu.https.port}/jwt/ibm/api/zOSMFBuilder/jwk" />
End of change
The parameters of this statement are described in Table 3.
Table 3. The statement to configure JWT builder
Parameter Type Default value Description
id String myMpJwt The unique ID.
issuer String zOSMF The issuer information. It should match the issuer value in Builder.
jwksUri String https://${izu.jwks.hostname}:${izu.https.port}/jwt/ibm/api/zOSMFBuilder/jwk Specifies a JSON Web Key service URL.

For more information, see https://www.ibm.com/support/knowledgecenter/SS7K4U_liberty/com.ibm.websphere.liberty.autogen.nd.doc/ae/rwlp_config_mpJwt.html

End of change