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 is 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-byte, 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

   E19C77561880BBF24F9E60B0D9051401FE2216A93F8683438A0DF2169CFE078F

JWTs as access tokens

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 configured for a web client. It contains the user identifier when the access token is created for a specific user.

Certificate-bound access tokens

Access tokens can be cryptographically bound to the client's X.509 certificate when using Mutual TLS (mTLS) authentication. This feature, specified in RFC 8705, prevents token theft by ensuring that tokens can only be used by the client that possesses the corresponding private key.

When certificate-bound tokens are enabled for a web client:

• JWT tokens include a cnf (confirmation) claim containing the SHA-256 thumbprint of the client certificate.
• Opaque tokens have the certificate binding stored server-side and validated during introspection.
• Resource servers must validate that the certificate presented matches the token binding.

Example of a cnf claim in JWT:

{
  "cnf": {
    "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
  }
}

DPoP-bound access tokens

Demonstrating Proof of Possession (DPoP) is an alternative sender-constraining mechanism that binds tokens to a client-held key pair rather than an X.509 certificate.

When DPoP-bound access tokens are enabled for a web client:

• The client must include a DPoP proof JWT in token requests.
• Issued access tokens are bound to the DPoP public key.
• For JWT access tokens, the binding is expressed via the cnf.jkt confirmation claim.
• For opaque access tokens, the binding can be returned via token introspection as cnf.jkt.

Example of a cnf.jkt claim in a JWT access token:

{
  "cnf": {
    "jkt": "<JWK-thumbprint>"
  }
}

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

{
  "kid": "f463bf2c-81a6-4979-82a5-aa5d032b6fe5",
  "alg": "RS256"
}

Payload example

{
  "ver": 1,
  "jti": "AT.d405c8b0-2afc-4720-a567-e890fecd28b2",
  "iss": "https://tenant.onewelcome.io/oauth",
  "aud": "profile-api",
  "iat": 1537437991,
  "nbf": 1537437991,
  "exp": 1537441591,
  "client_id": "example-client",
  "cid": "example-client",
  "scp": [
    "profile",
    "read"
  ],
  "scope": "profile read",
  "sub": "1c0e2c84-b05f-4c23-9175-c238f70901be",
  "usl": 5
}

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.