Access tokens
An access token is a short-lived credential that an application can use to access an API. Its purpose is to inform that the bearer of this token has been authorized to access a specific API. Access tokens must be sent to an API according to the Bearer token Usage specification. Specifically, the access token must be sent to the API in the HTTP Authorization header.
To obtain an access token, see OAuth endpoints.
Opaque tokens
An opaque access token is a random, 32-bytes, hex-encoded, string consisting of 64 characters. It does not contain any information about the validity of the token. The opaque token is returned to all clients of a mobile app and to the web clients that the opaque token is configured for.
Example opaque access token
JWTs
The OneWelcome Identity Platform can issue a JSON Web Token (JWT) as an access token. However, the receiver does not have to treat it as a JWT, but can also treat it as an opaque token and present it to the OneWelcome Identity Platform for validation. For details about access token validation, see Token Introspection.
The JWT token is returned when this is configured for a web client. It contains the user identifier when the access token is created for a specific user.
Example JWT access token
A JWT contains three sections: a header, a payload, and a signature. Only the header and payload sections are shown in the example below.
Header example
Payload example
Access token claims
The payload of a JWT access token contains a number of claims. These claims can be used to validate the access token but also tell what authorizations have been granted and for whom.
| Claim | Description |
|---|---|
| ver | Version indication for this access token |
| jti | JWT ID. A unique identifier of this JWT |
| iss | Issuer of this access token |
| aud | Audiences that this token is intended for |
| iat | Time when the access token was issued |
| nbf | Time before which the access token is not valid |
| exp | Time when the access token expires |
| client_id | Client ID of the client that requested the access token |
| cid | [DEPRECATED] Client ID of the client that requested the access token. |
| scope | String value containing a space-separated list of scopes that were granted for this access token. |
| scp | [DEPRECATED] Array of scopes that were granted for this access token. |
| sub | User identifier |
| usl | [DEPRECATED] Usage limit. Integer value that represents the usage limit for this access token. |
| group_permissions | [DEPRECATED] Stringified representation of the user's group memberships and permissions. Requires configuration of delegated administration. The group_permissions claim is omitted when the size of the JWT access token exceeds the limit. This is to prevent the JWT access token from being used to request data. When a group_permissions is expected, but it exceeds the limit, it can be requested via the token introspection endpoint. This claim is only returned when the OAuth client requesting the access token has the Group permissions version set to Legacy: V1 within its client configuration. |
| urn:onegini.com:oidc:group_policies | User's policies and group memberships. Requires configuration of delegated administration. The urn:onegini.com:oidc:group_policies claim is omitted when the size of the JWT access token exceeds the limit. This is to prevent the JWT access token from being used to request data. If the length of the token is exceeded, the urn:onegini.com:oidc:group_policies claim can be requested using token introspection or user-info endpoints, or included in the id-token. |
