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.

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.

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.

{
   "alg": "RS256",
   "typ": "JWT"
}

{
   "username": "admin",
   "sub": "admin",
   "iss": "KNOXSSO",
   "aud": "DSX",
   "role": "Admin",
   "permissions": [
     "administrator",
     "can_provision"
   ],
   "uid": "1000330999",
   "authenticator": "default",
   "display_name": "admin",
   "iat": 1579286619,
   "exp": 1579329819
 }