ID Token
- Kai Bjørnstad (Deactivated)
The ID Token is defined by the OIDC specification.
In short, the token is represented using JSON Web Token (JWT) and includes a set of standard claims. The JWT is signet by the OpenID Provider using the key-set for the relevant Security Domain.
The standard claims are specified here, but additional claims may be added, depending on the context and Security Domain.
The claims available in the ID Token is also dependent on the scopes requested/specified by the client.
Token lifespan
The lifetime of an ID token is set as max session time for a given Security Domain. The lifespan of an ID Token is typically significantly longer that that of an Access Token.
Basic claims
The following claims are used within the ID Token for all flows used by OpenID Connect.
In addition to the basic clams, the ID token can be extended with additional Standard Claims. The inclusion of these claims depend on the scopes requested by the client and on the data available and policies for each Security Domain.
Required
The following claims are required by the definition of an ID Token.
| Claim | Scope | Description | Example |
|---|---|---|---|
| iss | openid | The Buypass ID Provider instance. The issuer of the token. | "iss": "https://auth.buypass.no/auth/realms/SECURITYDOMAIN" |
| sub | openid | The subject identifier. A locally unique and never reassigned identifier within the Issuer for the end-user. Intended to be consumed by the client as a possible end-user reference. NOTE: Even if the identifier is "never reassigned" it may still change for the same user! An user may be reassigned a new sub, but a used sub will never be assigned to a new user. Hence, do not use this as a user reference over time! | "sub": "7a9cb1cf-c495-4db1-a25e-d24d84accc6d" |
| aud | openid | The audience that this ID Token is intended for. It must contain the client_id of the RP as audience value. May be an array of client_ids. | "aud": "oidc-client" |
| exp | openid | Expiration time on or after which the ID Token MUST NOT be accepted for processing. Epoc time format. | "exp": 1510314829 |
| iat | openid | Time at which the JWT was issued. Epoc time format. | "iat": 1510313029 |
Optional
The following tokens are part of the standard definition of an ID Token, but the inclusion of these claims are optional.
| Claim | Scope | Description | Example |
|---|---|---|---|
| auth_time | openid | Time when the end-user authentication occurred. | "auth_time: "0" |
| nonce | openid | Case sensitive string value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the authentication request to the ID Token. Note: Required when using Implicit Flow! | "nonce": "681913a288be" |
| acr | openid | String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied. This can for example be values based on some definition of Level of Assurance (LoA). See Context specific claims below. | "acr": "edias-loa-high" |
| amr | openid | JSON array of strings that are identifiers for authentication methods used in the authentication. This can for example be values which indicate that both password and OTP authentication methods were used. See https://tools.ietf.org/html/rfc8176 for standardised values. See Context specific claims below. | "amr": ["sc", "pwd", "otp"] |
| azp | openid | Authorized party - the party to which the ID Token was issued. If present, will contain the client_id of the party. | "azp": "oidc-client" |
Flow specific claims
These claims part of the standard definition but specific for ID Tokens issued under the listed OIDC flows.
| Claim | Scope | Description | Example |
|---|---|---|---|
| at_hash | openid | Optional additional requirement for Authorization Code flow. Access Token hash value. See also Code ID Token. Required additional requirement for Implicit flow. Access Token hash value. See Implicit ID Token. Required additional requirement for Hyrid flow. Access Token hash value. See Hybrid ID Token. | "at_hash": "IoS3ZGppJKUn3Bta_LgE2A" |
| c_hash | openid | Required additional requirement for Hyrid flow. Code hash value. See Hybrid ID Token. | "c_hash": "mRNStYQm-QU4rwcfv88VKA" |
| nonce | openid | Required when using Implicit Flow and Hybrid flow, see above. | See above |
Implementation specific claims
These claims are added to the ID Token as a consequence of implementation details (f.ex. defined as best practice/default for a spesific server/library).
Note that the claims themselves may still have formal definitions/specifications.
| Claim | Scope | Description | Example |
|---|---|---|---|
| jti | openid | JWT ID. A unique identifier for the token, which can be used to prevent reuse of the token. See jti claim. | "jti": "805bb26b-d961-43a7-a18a-6fc91af0c7a9" |
| typ | openid | Implementation specific claim denoting the token type. Not to be used by clients! | "typ": "ID" |
| session_state | openid | Implementation specific claim for use with session handling. Not to be used by clients! | "session_state": "904cbda8-1e2f-4e90-a7e6-1606aa7c622b" |
| nbf | openid | Identifies the time before which the JWT must not be accepted for processing. | "nbf": 0 |
Context specific claims
These tokens have a defined semantic in the standard, but values are outside the scope of the OIDC specification and need to be defined in context of use.
| Claim | Scope | Description | Example |
|---|---|---|---|
| sub | openid | The value of this claim is dependent on the requirements and functionality defined in the context (Security Domain) for this ID token. This means that the values must be defined for each context and domain/issuer. | See above |
| acr | openid | The value of this claim is dependent on the requirements and functionality defined in the context (Security Domain) for this ID token. This means that the values must be defined for each context and domain/issuer. | See above |
| amr | openid | The value of this claim is dependent on the requirements and functionality defined in the context (Security Domain) for this ID token. This means that the values must be defined for each context and domain/issuer. | See above |
Example basic token
Authorization Code flow: Basic token without any end-user claims.
Scope requested: "openid".
{
"jti": "f946a21d-53e4-4b1b-b189-5805025d7d7c",
"exp": 1558702349,
"nbf": 0,
"iat": 1558702289,
"iss": "https://auth.test.buypass.no/auth/realms/SECURITYDOMAIN",
"aud": "oidc-client",
"sub": "d6cccb1c-4390-41c1-b956-184ac9213a64",
"typ": "ID",
"azp": "oidc-client",
"auth_time": 0,
"session_state": "1b3b3efa-a26b-4599-8a49-ee1888402416",
"acr": "edias-loa-substanital",
"preferred_username": "someuser"
}
Example extended token
Authorization Code flow: Basic token with some extended end-user claims.
In addition to the "openid" scope, the scopes "profile, bpid and bpnnin" are requested.
{
"jti": "1055d27f-8269-45e9-b41e-857ac698b329",
"exp": 1558703827,
"nbf": 0,
"iat": 1558703767,
"iss": "https://auth.test.buypass.no/auth/realms/SECURITYDOMAIN",
"aud": "oidc-client-2",
"sub": "f:6ba131e6-fce2-4a92-924b-26b47a5632c1:15089100213",
"typ": "ID",
"azp": "oidc-client",
"nonce": "0eQKh14zYgXrdLg1pSkcyHnVX4GiW4ztjgyHlPzayWY",
"auth_time": 1558703767,
"session_state": "92f817ea-190d-47e5-a323-44f4c2967ebe",
"acr": "edias-loa-substanital",
"name": "BRITT FOS EDLAND",
"preferred_username": "15089100213",
"bp_id_sub": "101430957",
"given_name": "BRITT FOS",
"family_name": "EDLAND",
"bp_nnin_sub": "15089100213"
}