Token configurations

The default configurations for Knox token integration are as follows.

Default configurations

Table 1. Default token configurations
Property Sample values Default
Token State Service Implementation Knox's internal implementation of its own token state service.
Allowed Token Management Implementations A list of implementation names that Knox considers allowed on its own token generation page. JDBCTokenStateService,AliasBasedTokenStateService
Configured Token TTL The value of knox.token.ttl in the homepage topology. 1 hour
Token Type This is an optional configuration parameter to indicate the type of the JWT token that Knox generates. JWT
Enable Lifespan Input Whether the lifespan input fields are enabled on Knox's token generation page. false
User Limit The number of tokens a user is allowed to manage. Setting this to -1 indicates unlimited token management. 10
User Limit Exceeded Action The action Knox will take if user limit is exceeded while trying to create a new Knox Token. If REMOVE_OLDEST is selected then the oldest token of the user, who the token is being generated for, will be removed. Otherwise, if RETURN_ERROR is selected, Knox will return an error response with 403 error code. RETURN_ERROR
Renewer Whitelist This is an optional configuration parameter to authorize the comma-separated list of users to invoke the associated token renewal and/or revocation APIs. empty string
JWKS URL This optional configuration parameter enables end-users to declare their JWKS URL. The JSON Web Key Set (JWKS) is a set of keys containing the public keys used to verify any JSON Web Token (JWT) issued by the authorization server and signed using the RS256 signing algorithm. empty string
Allowed JWS Types This is an optional configuration parameter to allow a comma-separated list of token types Knox will allow while validating JSON Web Signature (JWS) using JWKS URLs. Defaults to JWT. The typical customized value is at+jwt, JWT. JWT
Expected Principal Claim If that configuration parameter is defined, Knox will use this to get the value of this claim from the submitted JWT upon verification instead of using the default principal. empty string
Default configurations seen from Cloudera Manager:
Default configurations seen from the Knox homepage UI:

Database connection properties

Optional database connection properties that you can declare individually:
  • gateway.database.type: Set to postgresql or mysql.
  • Host where your DB server is running.
  • gateway.database.port: Port that your DB server is listening on.
  • Name of the database you are connecting to.

Token TTL details

Out of the box, Knox will display the custom lifetime spinners on the Token Generation page. However, they can be hidden by disabling the Knox Token Integration - Enable Lifespan Input checkbox on the CM UI. Given that input property, and the configured maximum lifetime property, the generated token can have the following TTL value:

  • If there is no configured token TTL and lifespan inputs are disabled, the default TTL is used (30 seconds).
  • If there is configured TTL and lifespan inputs are disabled, the configured TTL is used.
  • If there is configured TTL and lifespan inputs are enabled and lifespan inputs result in a value that is less than or equal to the configured TTL, the lifespan query param is used.
  • If there is configured TTL and lifespan inputs are enabled and lifespan inputs result in a value that is greater than the configured TTL, the configured TTL is used.

Generate-jwk options

CM automatically creates a token hash key for you. But if you want to do this manually, such as when scripting, configure the knox.token.hash.key alias with:
generate-jwk --saveAlias knox.token.hash.key
This generates a JSON Web Key using the supplied algorithm name.
Table 2. Options
Option Description Sample values
jwkAlg (Optional) The desired JSON Web Signature algorithm name. Determines if the gateway-level alias is configured with a 256, 384, or 512-bit length JWK.

HS256 (Default)



saveAlias (Optional, Recommended) Given alias name used to save the generated JWK, instead of printing this sensitive information on the screen. knox.token.hash.key
topology (Optional) Name of the topology (i.e., the cluster) to be used when saving the JWK as an alias. If none specified, the alias is going to be saved for the Gateway.

cdp-proxy (Default)

cdp-proxy api