Skip to content
Connect2id
Connect2id server

Self-contained access tokens in Connect2id

This post explains the format of self-contained access tokens issued by the Connect2id server. It complements an earlier post about pros and cons of self-contained tokens in terms of processing and performance and how they compare with identifier tokens that act as lookup keys.

The Connect2id server can be configured to issue self-contained access tokens that represent a signed JSON Web Token (JWT) with the following fields:

  • sub [string] The subject (user) of the authorisation, e.g. alice@wonderland.net. This is a standard JWT claim.
  • iss [string] The issuer of the authorisation, corresponds to the OpenID Connect provider’s identifier, e.g. https://my-company.com/oidc. This is a standard JWT claim.
  • iat [integer] The token issue time. This is a standard JWT claim.
  • exp [integer] The token expiration time. This is a standard JWT claim.
  • aud [string array] The token audience list, typically the intended protected resources represented by their URIs. This is a standard JWT claim.
  • jti [string] Secure unique identifier for the token, to enable token de-duplication. This is a standard JWT claim.
  • cid [string] Non-standard claim, represents the identifier of the client that received the token.
  • scp [string array] Non-standard claim, represents the authorised scope values, e.g. ["openid", "email", "app:read", "app:write"].
  • clm [string array] Non-standard claim, represents the consented UserInfo claims to be released at the UserInfo endpoint, e.g. ["name", "email"].
  • cll [string array] Non-standard claim, represents the preferred locales of the consented UserInfo claims, e.g. ["es-ES", "en-GB"].
  • sid [string] Non-standard claim, represents the (browser) session identifier for the subject (user) with the OpenID Connect provider. Can be used to check if the user is still logged in, or to retrieve additional details from his/her IdP session.
  • dat [object] Non-standard claim, can be used to store additional data in an arbitrary JSON object, e.g. the user’s geolocation.

The Connect2id server configuration allows the administrator to choose which of the above fields get included in the self-contained access tokens. For example, the tokens can be configured to include only the issuer, the subject, the timestamps and the authorised scope:

{
 "sub" : "alice",
 "scp" : [ "openid", "email", "app:write" ],
 "iss" : "http://idp.example.com",
 "iat" : 1360050795,
 "exp" : 1360053600,
}

The above claims set is then signed (JWS) using the RSA-SSA algorithm to produce the final JSON Web Token (JWT) similar to this (with extra line breaks):

eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjEzNzA2MDU0NDgsInN1YiI
6ImFsaWNlQHdvbmRlcmxhbmQubmV0Iiwic2NvcGUiOiJvcGVuaWQ
gcHJvZmlsZSBlbWFpbCB3ZWJhcHA6cG9zdCB3ZWJhcHA6YnJvd3N
lIiwiYXVkIjpbImh0dHA6XC9cL3dlYmFwcC5jb21cL3Jlc3RcL3Y
xIiwiaHR0cDpcL1wvd2ViYXBwLmNvbVwvcmVzdFwvdjIiXSwiaXN
zIjoiaHR0cHM6XC9cL2MyaWQuY29tXC9vcCIsImlhdCI6MTM3MDY
wMzY0OH0.dcLjGbBiijHSF0YGLHY0GGdXqQOlAbiBli4es7dgoOc
9jqKKUkqG2d9lztku82dLDq-xWvU2RDuhDtd-luSyLEQrrMGdAnW
zQwWTPw_RVKDzK8NdRuUbx7pwj8cayhFBsgJujmdxN_qOyvjEdIE
mfdEnprESkwNZo87OO_RMxeY

The protected resources that receive the access token can verify it by using the server’s public RSA key, typically published at the OpenID Connect provider’s JWK set endpoint.

The Connect2id server has support for the following standard RSA signing algorithms for securing the self-contained access tokens:

  • RS256
  • RS384
  • RS512
  • PS256
  • PS384
  • PS512

Clients can make use of the open source Nimbus JOSE+JWT library to verify the JWTs. Open source libraries for other languages than Java are also available on the web.