Token configuration file

In order to support token authentication, several configuration values are required to describe what types of tokens are supported, and how they are to be validated.

Before you begin

Note: This feature is available starting from Db2® version 11.5.4.
A file, db2token.cfg must be created in the instance directory, which defaults to the following:
  • Linux and UNIX (for serial or DPF) $INSTHOME/sqllib/cfg
  • Linux and UNIX for pureScale (for serial or DPF): $INSTHOME/sqllib_shared/cfg
  • Windows: C:\ProgramData\IBM\DB2\db2copy1\DB2\cfg

The configuration file must be owned by the instance owner with read/write permissions.

Procedure

On the Db2 server, create the token configuration file in a text editor.

Keywords

Consider a JWT to be validated as follows:
{
   "alg": "RS256",
   "typ": "JWT"
}
.
{
   "username": "admin",
   "sub": "admin",
   "iss": "KNOXSSO",
   "iat": 1579286619,
   "exp": 1579329819
 }
 .
 signature
and this example token configuration file:
VERSION=1
TOKEN_TYPES_SUPPORTED=JWT
JWT_KEYDB=/home/db2inst1/jwtkeys.p12

JWT_IDP_ISSUER=KNOXSSO
JWT_IDP_AUTHID_CLAIM=username
JWT_IDP_RSA_CERTIFICATE_LABEL=mylabel
JWT_IDP_ISSUER=A_SECOND_ISSUER
JWT_IDP_AUTHID_CLAIM=userid
JWT_IDP_RSA_CERTIFICATE_LABEL=aDifferentLabel
Common parameters:
VERSION
The version of the configuration file. (Mandatory)
TOKEN_TYPES_SUPPORTED
The types of tokens supported as a comma-separated list. Currently, JWT is the only supported token type. (Mandatory)
JWT Parameters:
JWT_KEYDB
The path to local keystore file. (Mandatory)

Private keys, and public keys as certificates, are stored in a local keystore file with a corresponding stash file (\*.sth extension). This keystore is used to store keys for all IDP and key labels must be unique across IDPs.

JWT IDP Group parameters:

The following parameters are grouped together and apply to a single IDP. The group starts with JWT_IDP_ISSUER and succeeding keywords apply to that IDP until the next JWT_IDP_ISSUER is parsed.

JWT_IDP_ISSUER
The name of the issuer of the token. Corresponds to iss claim in the JWT and must match exactly. Must appear first in a group of parameters particular to one IDP. (Mandatory)
JWT_IDP_AUTHID_CLAIM
The claim within the JWT that specifies the key holding the authorization ID of the user connecting to Db2. Must appear after JWT_IDP_ISSUER parameter. The value will depend on the contents specified by IDP. It may be a value such as "username", "userid", "uid" or "sub". This is not the value of the authid, but the key which identifies the authid in the token (see example above).
  • Nested JSON is not supported for the claim

Rules for authid value in the token, which is looked up on the basis of this config parameter:

  • The authorization ID in the token will be converted to uppercase.
  • Additional parsing of the claim, such as separating a username portion of an email address, is not supported, the claim is taken as-is.
JWT_IDP_SECRETKEY_LABEL
The label for the secret (symmetric) key used to verify the signature of the token using the HMAC-SHA algorithm. Must appear after JWT_IDP_ISSUER parameter. (Optional)
JWT_IDP_RSA_CERTIFICATE_LABEL
The label for the certificate containing the public key used to verify the signature of the token using the RSA algorithm. Must appear after JWT_IDP_ISSUER parameter. (Optional)
JWT_IDP_ECDSA_CERTIFICATE_LABEL
The label for the certificate containing the ECDSA public key, used to verify the signature of the token using the ECDSA algorithm. Must appear after JWT_IDP_ISSUER parameter. (Optional)
JWT_IDP_PSS_CERTIFICATE_LABEL
The label for the certificate containing the RSA public key used to verify the signature of the token using the PSS-RSA algorithm. Must appear after JWT_IDP_ISSUER parameter. (Optional)

Notes

  • Unless otherwise indicated, do not use quotes around values
  • With the exception of TOKEN_TYPES_SUPPORTED, the value for all other parameters is case-sensitive. For example, the value for JWT_IDP_ISSUER must match exactly the iss value in the JWT.
  • At least one IDP group must be specified.

  • Starting from Db2 version 11.5.5, multiple labels are supported for JSON Web Tokens. Up to 10 issuers can be specified. Each issuer can have a maximum of 5 labels for each label type. Each of the labels are extracted and verified against token signature for verification.

  • The maximum number of IDP groups is 6 for Db2 version 11.5.4, and 10 starting from version 11.5.5.
  • For each IDP group, at least one of JWT_IDP_SECRETKEY_LABEL, JWT_IDP_RSA_CERTIFICATE_LABEL, JWT_IDP_ECDSA_CERTIFICATE_LABEL, JWT_IDP_PSS_CERTIFICATE_LABEL must be specified.
  • Up to 5 labels can be specified for each label type per IDP group. Labels should be specified on separate lines. For example:
    JWT_IDP_SECRETKEY_LABEL=secretkeyLabel1
JWT_IDP_SECRETKEY_LABEL=secretkeyLabel2
JWT_IDP_SECRETKEY_LABEL=secretkeyLabel3
JWT_IDP_SECRETKEY_LABEL=secretkeyLabel4
JWT_IDP_SECRETKEY_LABEL=secretkeyLabel5

    When multiple labels are used, each of the labels is extracted and an attempt is made to verify the token signature with the label until verification is successful or all labels have been attempted.

  • Take caution when deciding to use the HMAC-SHA signature algorithm for signing tokens, because the key used to sign the token is the same as the one used to validate the signature. Therefore, anyone that can check signatures can also generate them. This should only be used in scenarios where there is strong trust between the issuer/signer (the IDP) and the verifier (Db2 instance owner).