All tokens in the Curity Security Token Server are issued using token procedures. These are executed after validation has been performed and are responsible for both issuing the tokens, and assembling the data that should be used as response to the client.
This gives the administrator enormous flexibility in what tokens can be issued and which data should be added to these.
Fig. 140 Processing of token request
The Curity Security Token Server supports three types of tokens, each with different characteristics regarding the token string returned to the client and the associated data:
JSON Web Token (JWT) - The token string is a JWT which includes all the token data.
Opaque - The token string is an opaque reference to the actual token data, similar to an UUID. The associated token data is obtained 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 obtained via introspection.
The process of issuing tokens uses the concept of Token Issuers - used by token procedures - which take the token data as input and return an artifact string.
Each issuer handles one of the aforementioned token types for a given purpose (e.g. access token, ID token).
The Curity Security Token Server includes default token issuers for the different purposes and custom issuers may also be defined.
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.
For details on how to use the default issuers see Token procedures.
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.
The supported combinations of issuer type and purpose are identified below:
The data associated with wrapped opaque tokens is twofold: data that goes into the JWT returned as the token string (the wrapper) and the main token data, which is obtained via introspection.
Each part can be configured separately 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.