Rate this page

Access tokens and ID tokens

When a Data Governance Broker client makes an OpenID Connect request to the Data Governance Broker, its payoff comes in the form of two JWTs, the access token and the ID token. The access token represents an authorization result, and the ID token represents an authentication result. Because both tokens use the JWT format, they may be processed similarly, but an application uses them quite differently.

Access tokens

The access token is a credential representing an end user’s authorization for the client to access the user’s resources on the user’s behalf. By using access tokens, clients are able to access scoped user data without requiring the user to divulge his or her password to the client. Because access tokens expire after a time and can also be revoked, client access can be managed and abuses can be avoided or mitigated easily.

Once an access token is in the client’s possession, it must be stored securely and confidentially, as a resource server will accept the token as proof of authorization from any party until the token expires or is revoked. A resource server, for its part, must ensure that any access token that it accepts is not in fact expired, revoked, or otherwise invalid.

Access tokens issued by the Data Governance Broker are always signed JWTs. As they contain no sensitive claims, they are never encrypted. The Data Governance Broker’s access token format is described in the API reference.

ID tokens

The ID token is an assertion of the end user’s authentication state that the authentication server makes to the client. That is, an ID token can be considered proof that a specific user is logged in.

If a client is satisfied with a user’s authentication state as represented by the ID token, it will typically use it as the basis for establishing an application session for the user. The user ID (the sub claim) contained in the ID token may be used as a correlation key for the client’s local user data. Some clients use ID tokens directly as a session mechanism, storing them in cookies.

A resource server itself does not use ID tokens in any way.

ID tokens issued by the Data Governance Broker are always signed. In some cases, ID tokens may contain sensitive claims; if so, they should be configured to be encrypted. The Data Governance Broker’s ID token format is described in the API reference.

Two kinds of authorization

The two token types make two distinct kinds of authorization possible.

Scopes-based authorization is the most common form, as well as the most simple. When a client needs to access protected resources from a resource server, it obtains an access token from an authentication server, and the client’s range of behavior is thereby determined by the data that it can access from the resource server. Under this model, all authorization is handled by the Data Governance Broker.

A more complex form of authorization is authentication-based authorization. In this model, the client might restrict access to its own features based on information about the authentication state given in an ID token. For example, the client might use the acr claim in the ID token to determine if a user has authenticated in a sufficiently secure manner before allowing the user to update a sensitive record, such as a stored credit card number. Note that by using authentication-based authorization, a client assumes more risk and complexity for itself, and it must ensure that it does so in a secure and robust manner.

Validating access tokens

Depending on its needs, a client may not need to validate an access token. For example, it may simply use an access token until it is no longer accepted by the resource server, at which point it can request another token from the authentication server.

A resource server must always validate an access token before accepting it. If the resource server is the Data Governance Broker itself, then this happens automatically, of course.

In any case, two options are available for validating access tokens.

The token validation endpoint

An access token may be validated by submitting it to the Data Governance Broker’s token validation endpoint, also called the token introspection endpoint. This is a simple POST request to /oauth/validate.

POST /oauth/validate HTTP/1.1
Accept: application/json
Content-Length: 617
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: example.com:443

token=eyJhbGciOi...

And this is the validation response.

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Length: 182
Content-Type: application/json
Date: Thu, 01 Sep 2016 05:48:25 GMT
Pragma: no-cache

{
    "active": true,
    "client_id": "test_client",
    "exp": 1473140860,
    "iat": 1472708860,
    "jti": "a.3ReZAQ",
    "scope": "email openid",
    "sub": "Users/05e96d61-d5dc-4a72-bdb3-4348757be5fe",
    "token_type": "bearer"
}

If the token is still valid, then the active claim will have a value of true. If the token is expired, revoked, or invalid for any other reason, then the active claim will have a value of false. The Data Governance Broker API reference describes the response format in greater detail.

JWT access token validation

All access tokens issued by the Data Governance Broker are signed JWTs. A client or resource server can therefore determine if an access token is still active by simply decoding the token and checking its expiration time (exp) claim.

The token’s signature should also be verified to ensure its authenticity. Access tokens issued by the Data Governance Broker are always signed using an RSA-based JWA, so the verifying entity must have a copy of the Broker’s public signing key. This can be obtained out of band, or it may be obtained dynamically through the JWKS. In the latter case, it will typically be advisable to cache the downloaded JWKS, updating it periodically.

Validating an access token as a JWT has a decided advantage over using the Data Governance Broker’s token validation endpoint: It doesn’t require the client or resource server to make a request over the network. The disadvantage, however, is that the client or resource server cannot know if a token has been revoked. This can be mitigated by configuring a short expiration period for access tokens.

The following Java example uses the Nimbus JOSE+JWT library to retrieve a JWK public key from a Data Governance Broker’s JWKS endpoint, uses the JWK to verify an access token’s signature, then checks the exp claim against the current time.

SignedJWT accessToken = SignedJWT.parse("eyJraWQiOi...");
String kid = accessToken.getHeader().getKeyID();

JWKSet jwks = JWKSet.load(new URL("https://example.com/jwks"));
RSAKey jwk = (RSAKey) jwks.getKeyByKeyId(kid);

JWSVerifier verifier = new RSASSAVerifier(jwk);
if (accessToken.verify(verifier)) {
  System.out.println("valid signature");
} else {
  System.out.println("invalid signature");
}

JWTClaimsSet claims = accessToken.getJWTClaimsSet();
if (claims.getExpirationTime().toInstant().isAfter(Instant.now())) {
  System.out.println("active token");
} else {
  System.out.println("expired token");
}

Validating ID tokens

Clients must validate ID tokens that they receive, though the extent of that validation will depend upon the client’s requirements and concerns. The procedure for validating an ID token is specified by section 3.1.3.7 of the OpenID Connect specification. The following list describes the most pertinent validation rules for Data Governance Broker clients:

  1. If the ID token is encrypted, decrypt it. If the Data Governance Broker is configured to encrypt ID tokens for the client, then client must be in possession of the secret needed to decrypt those tokens.
  2. Confirm that the issuer (iss) claim is the value expected for the authentication server.
  3. Confirm that the audience (aud) claim matches the client’s client ID. This ensures that the application doesn’t use an ID token intended for a different client.
  4. Verify the ID token’s signature. This validation may be skipped at the client’s discretion when HTTPS was used to receive the ID token. HTTPS is always used, but it is incumbent on the client to ensure that HTTPS is used properly and that key security features such as hostname validation are not disabled.
  5. The expiration time (exp) claim must not precede the current time.
  6. If the client sent a nonce value in the authentication request, then the same value must be present in the ID token’s nonce claim.
  7. If the client requires a particular level of authentication, then it should confirm that the authentication context class reference (acr) claim contains an acceptable value.

Unlike access tokens, ID tokens may be signed using either an RSA-based JWA or an HMAC-based JWA. HMAC-based JWAs are symmetric cryptography methods requiring that both parties use a shared secret (the client secret), so they are only suitable for use by server-side applications that do not expose the shared secret on the client side.

Here’s a Java example that uses the Nimbus JOSE+JWT library, similar to the access token validation example above.

SignedJWT idToken = SignedJWT.parse("eyJraWQiOi...");
String kid = idToken.getHeader().getKeyID();

JWKSet jwks = JWKSet.load(new URL("https://example.com/jwks"));
RSAKey jwk = (RSAKey) jwks.getKeyByKeyId(kid);

JWSVerifier verifier = new RSASSAVerifier(jwk);
if (idToken.verify(verifier)) {
  System.out.println("valid signature");
} else {
  System.out.println("invalid signature");
}

JWTClaimsSet claims = idToken.getJWTClaimsSet();

if (claims.getExpirationTime().toInstant().isAfter(Instant.now())) {
  System.out.println("active token");
} else {
  System.out.println("expired token");
}

if (claims.getStringClaim("nonce").equals("unique-nonce-value")) {
  System.out.println("nonce matches");
} else {
  System.out.println("unexpected nonce");
}

// And so on for aud, iss, acr, etc. claims

A few ID token claims deserve extra consideration, and we’ll discuss them in the following sections.

Authentication time

The ID token’s auth_time claim provides the timestamp of the last time the user actively interacted with the Data Governance Broker during authentication. Note that the authentication time doesn’t necessarily correspond with the time that the client made an OpenID Connect authentication request — often, when the authentication server receives such a request, it will determine that the user’s authentication state is still valid and in no need of further interaction for the time being.

If the client would nevertheless prefer to force such an interaction, it does have some options. It can issue another authentication request, this time providing one of the following request parameters:

Parameter Value
prompt login, which will force the authentication server to prompt the user to log in.
max_age A number of seconds. If the difference between the current time and the last authentication time is greater than this value, then the authentication server will prompt the user to log in.

Authentication context class references (ACRs)

The acr claim lists the name of the authentication context class reference (ACR) that was satisfied when a user was authenticated. When a user authenticates to the Data Governance Broker, certain conditions must be met in order for the authentication to be considered successful by the server. The server configuration may define one or more sets of conditions; these sets of conditions are ACRs.

Often, a particular ACR will represent a particular level of authentication (LOA) relative to other ACRs. For example, a Data Governance Broker might have a ‘Default’ ACR that requires only username/password authentication, plus an ‘MFA’ ACR that requires both username/password authentication and a one-time password, indicating a stronger level of authentication.

To give a couple usage examples with the above ‘MFA’ and ‘Default’ ACRs:

  1. An application could include the parameter acr_values=MFA in its authentication request, meaning that it will only accept the higher level of authentication represented by the ‘MFA’ ACR. The server will not return a successful authentication response to the application if the requirements of this ACR cannot be met.
  2. An application could include the parameter acr_values=MFA Default in its authentication request, meaning that it will accept any authentication that satisfies either ACR. When the application receives an ID token, it could then check the acr claim to find out which ACR was actually satisfied.

The meanings of particular ACRs are entirely determined by the Data Governance Broker configuration, so a client developer must coordinate with the Data Governance Broker administrator in order to understand how an application should interpret the acr claim.

ACRs are used most effectively if treated as high-level encapsulations of authentication criteria, as when using LOAs. In most cases, the client developer should have no need to understand the specific details of how a particular ACR is configured.

Authentication method references (AMRs)

An authentication method reference (AMR) is an identifier representing a type of authentication that was used to achieve an end user’s current authentication state. These values are configurable, but the API reference lists some default AMR values. Examples of typical values are pwd (password) and otp (one-time password).

If possible, clients should ignore the amr claim, as it’s generally preferable to make decisions based on the higher level of abstraction represented by the acr claim. Leaving fine-grained authentication and authorization decisions up to the Data Governance Broker ensures that your organization’s security policies are applied consistently.