Token Issuers

Token issuers are configurable components that take token data as input and produce an artifact string, according to a token type and purpose. Token Issuers are used by Token Procedures to issue various types of tokens, such as access tokens and ID tokens.

All tokens in the Curity Identity Server are issued using Token Procedures . Among other things, these are responsible for collecting the data to be associated to tokens and rely on Token Issuers to actually issue those tokens. This provides great flexibility in what tokens can be issued and which data should be added to them.

Processing of token request
Processing of token request

The Curity Identity Server includes default token issuers for the different purposes and custom issuers may also be defined.

Token Types#

The Curity Identity Server supports three main types of tokens, each with different characteristics regarding the token string returned to the client and the associated data.

JSON Web Token

The token string is a JSON Web Token (JWT) which includes all the token data.

JWTs are signed and the signature verification keys are made available on the server metadata .

Opaque

The token string is an opaque reference to the actual token data, similar to an UUID. The associated token data is persisted and accessible via introspection.

Wrapped Opaque

The token string is a JWT whose contents do not expose the token data directly, except for a few metadata fields (e.g. expiration time). The associated token data is persisted and accessible via introspection.

The data included in the JWT returned as the token string (the wrapper) can be configured separately from the main token data via claim mappers . Specifically, the data that goes into the wrapper JWT is defined by the wrapper-token claim sink, which is used whenever a wrapped opaque token is issued, regardless of its purpose.

Wrapped opaque tokens are useful in scenarios where the token consumer (e.g. client, resource server, infrastructure components) may need to process part of the token data before actually using/introspecting it. The wrapper JWT may contain non-sensitive claims to help the consumer in that case. An example of such scenarios is described in the HEART Profile for OAuth 2.0, where compliant resource servers may accept tokens from different authorization servers and need to inspect the token’s issuer in order to decide which introspection service to use.

Default Token Issuers#

In the Token Issuers section it’s possible to configure the issuers that are used by default in the system when a custom issuer is not specified. By default, Curity issues opaque tokens whenever the token format is not pre-defined (e.g. ID tokens are always JWT). The data associated with opaque tokens is persisted, so a data source that supports token storage must be configured using the default-data-source setting.

There are some configuration options that allow tweaking the behavior of the default token issuers, namely:

  • jwt-issuer-settings - Settings for the default JWT token issuer, such as which signing key to use.
  • access-token-as-jwt - Issue access tokens as JWT instead of opaque tokens.
  • use-wrapped-opaque-tokens - Issue tokens as wrapped opaque tokens instead of opaque tokens (when applicable).

The following is an example of the configuration for default token issuers using the options mentioned above.

<default-token-issuer>
    <jwt-issuer-settings>
        <signing-key-id>default-signing-key</signing-key-id>
        <verification-keystore-id>default-signature-verification-key</verification-keystore-id>
        <algorithm>RS256</algorithm>
    </jwt-issuer-settings>
    <access-token-as-jwt/>
    <default-data-source>DefaultHSQLDB</default-data-source>
</default-token-issuer>

For details on how to use the default issuers see Token Procedures .

Custom Token Issuers#

Custom token issuers are named issuers that are accessible by their name from Token Procedures . By defining a custom issuer, it is possible to issue some tokens with specific settings, while keeping the default settings in place for other tokens.

When configuring a custom issuer, its id, token type and token purpose must be defined. Other settings vary with the selected token type. For example, opaque tokens require a token data source.

The following is an example of the configuration for two custom issuers, one for wrapped opaque access tokens and another for opaque nonce tokens.

<custom-token-issuer>
    <id>access-token-issuer</id>
    <issuer-type>wrapped-opaque</issuer-type>
    <purpose-type>access_token</purpose-type>
    <data-sources>
        <tokens-data-source-id>DefaultHSQLDB</tokens-data-source-id>
    </data-sources>
    <jwt>
        <signing-key-id>default-signing-key</signing-key-id>
        <verification-keystore-id>default-signature-verification-key</verification-keystore-id>
    </jwt>
</custom-token-issuer>
<custom-token-issuer>
    <id>nonce-issuer</id>
    <issuer-type>opaque</issuer-type>
    <purpose-type>nonce</purpose-type>
    <data-sources>
        <tokens-data-source-id>DefaultHSQLDB</tokens-data-source-id>
    </data-sources>
</custom-token-issuer>

The supported combinations of issuer type and purpose are identified below:

Issuer typeAccess tokenRefresh tokenID tokenNonceGenericUserinfo
JWTYesNoYesNoYesYes
OpaqueYesYesNoYesNoNo
Wrapped opaqueYesYesNoYesNoNo

Encrypted ID Tokens#

The Curity Identity Server supports issuing encrypted ID tokens. As required by OpenID Connect, if an ID token is encrypted, it must be signed then encrypted, with the result being a nested JWT as defined by the JSON Web Token (JWT) specification. This means that an encrypted ID token encompasses two parts:

  1. An inner JWT, signed using JSON Web Signature (JWS). This token is issued by any of the ID token issuers described in the previous sections.
  2. An outer JSON Web Encryption (JWE) structure whose payload is the compact serialization of the previous JWT. This JWE is encrypted for a specific recipient, i.e. the client that started the authorization flow.

It is possible to configure the Curity Security Token Server so that encrypted ID tokens are enabled and, optionally, required. This can be done at different levels:

  • Profile - see id-token-encryption on the OpenID Connect configuration settings .
    • Enable encrypted ID tokens as a whole and define the allowed Key Management and Content Encryption algorithms for JWE.
  • Configured clients - see id-token-encryption on the configured client settings .
    • Enable encrypted ID tokens for specific clients by defining the encryption key and the Key Management and Content Encryption algorithms to use.
  • Non-templatized dynamic clients - see require-id-token-encryption on the non-templatized dynamic clients configuration settings .
    • Require that dynamic clients are registered with ID token encryption settings.
    • Note that these clients can use encrypted ID tokens even if not required by the configuration, as long as encrypted ID tokens are enabled in the profile.

Dynamic clients can define which Key Management and Content Encryption algorithms are used via the id_token_encrypted_response_alg and id_token_encrypted_response_enc client metadata values, respectively, as long as these are allowed by the profile. The encryption key is obtained from the JSON Web Key Set (JWKS) supplied on registration.

When possible, the issued JWE will include the Key ID (kid) and the X.509 Certificate SHA-256 Thumbprint (x5t#S256) header parameters. This may be particularly helpful for dynamic clients that have multiple encryption keys in their JWKS. If multiple keys are applicable when issuing an encrypted ID token, the ones that include the Key ID (kid) header parameter are preferred and then the first key in the JWKS order is used.

The supported Key Management and Content Encryption algorithms are exposed in the metadata endpoint when encrypted ID tokens are enabled.

Learn More#

Was this helpful?