JSON Web Tokens (JWT)

JSON Web Tokens (JWT) are used to securely transmit authentication information formatted as a JSON object.

As JWT are digitally signed by the issuer, they can be used for authentication purposes by validating the signature, without having to expose a password to Db2®. A claim within the JWT identifies the user's identity Db2.

Typically, it is an Identity Provider (IDP) product that will generate the JWT when a user logs in through an application, although it is possible for an individual application to create a JWT itself. Db2 can validate JWT but does not provide a method for generating them.

A diagram of the JWT workflow

The issuer of the JWT must be identified in the token under the 'iss' claim. An exact match for the issuer must be found in the token configuration file (db2token.cfg) in the JWT_IDP_ISSUER parameter in order to locate keys for validating the JWT signature. A local keystore file of type PKCS#12 (*.p12) is used to hold the keys and its location must be configured in the token configuration file.

The signature algorithm is declared as part of the JWT header. Db2 supports the following signature algorithms:
  • HMAC using SHA2 (HS256, HS384, HS512)
  • RSASSA-PKCS1-v1 using SHA2 (RS256, RS384, RS512)
  • ECDSA P-256 with SHA256 (ES256)
  • ECDSA P-384 with SHA384 (ES384)
  • ECDSA P-512 with SHA512 (ES512)
  • Available starting from Db2 version 11.5.5:
    • RSASSA-PSS using SHA-256 and MGF1 with SHA-256 (PS256)
    • RSASSA-PSS using SHA-384 and MGF1 with SHA-384 (PS384)
    • RSASSA-PSS using SHA-512 and MGF1 with SHA-512 (PS512)

Db2 does not support encrypted JWT. TLS/SSL is strongly recommended to protect the JWT while sent over the network.

For Db2 to validate tokens signed with the indicated algorithm, you must configure the appropriate key. A secret key that was used to sign the JWT must be configured if HS256, HS384 or HS512 is used. A certificate with appropriate public key must be configured for each of RSA signature algorithms. The label for these keys are specified in the db2token.cfg file.

To determine the identity of the token holder, Db2 examines the contents of the token itself. The token configuration file, under the JWT_IDP_AUTHID_CLAIM parameter determines which claim within the token holds the users identity. This claim will be taken as the authorization ID of the user within Db2. While not required to be named so, the claim is often called "sub" (for subject) or "username". Individual IDPs often include the ability to customize the JWT they produce, and it may even be possible to generate a claim such as "db2authid".

No processing is performed on the value identified by the authid claim. For example if a claim identifies an email address, it is not broken apart into username and domain portions, but kept as a whole.

The JWT must include an expiry time in the 'exp' claim, as Db2 does not support revoking methods. Careful thought must be given to appropriate values for the expiry time. If the JWT were exposed to a malicious user, a value that is too large increases the window during which it may be used. A value that is too small may interfere with Db2 operations. Once a connection is established, the token can expire without consequence. However, there are certain scenarios in which the token may be re-used, and if it had expired prevent the operation from succeeding. Specifically:
  • Automatic Client Reroute: re-establishing a new connection would reuse the existing token and fail if it had expired.
  • Federation connections to remote data source: When configured for single-sign on (SSO), outbound connections to remote data sources will use the JWT that was used to connect to the Federation server. If the token has expired, this connection will fail.

Often, when a JWT is generated, it is accompanied by a refresh token. Db2 does not support using a refresh token to obtain a new, non-expired JWT.

Db2 does not obtain group information or other authorization details from the JWT. The standard group plug-in is used to obtain groups for the user.

For the JWT to be validated by Db2, it must have the following properties:

  • If a 'typ' claim is in the token header, it must have the value JWT. The claim is optional and does not need to be present.
  • An 'alg' claim of a supported algorithm, and appropriately configured key in the db2token.cfg file
  • An 'iss' claim that matches an issuer in the db2token.cfg file.
  • A JWT_IDP_AUTHID_CLAIM claim identifying the authorization ID of the user.
  • An 'exp' claim with a value that has not expired

The JWT may contain any other claims, but they are ignored by Db2.

The following is a sample JWT header and claims.

Example HEADER:
   "alg": "RS256",
   "typ": "JWT"
Example PAYLOAD:
   "username": "admin",
   "sub": "admin",
   "iss": "KNOXSSO",
   "aud": "DSX",
   "role": "Admin",
   "permissions": [
   "uid": "1000330999",
   "authenticator": "default",
   "display_name": "admin",
   "iat": 1579286619,
   "exp": 1579329819
In this case
  • The issuer is KNOXSSO.
  • The JWT signing algorithm uses RS256 - (RSA signature with SHA256).
  • The expiration time for JWT is set at 12 hours.
  • The "username" claim identifies the Db2 authorization ID.