Token storage location

AM OAuth 2.0-related services are stateless unless otherwise indicated; they do not hold any token information local to the AM instances. Instead, they either store the OAuth 2.0/OpenID Connect tokens in the Core Token Service (CTS) token store, or present them to the client. This architecture lets you scale your AM infrastructure horizontally, because any server in the deployment can satisfy any token request.

The OAuth 2.0 token storage location is a property of the OAuth 2.0 service, configured by realm. You can configure each realm to store tokens in the CTS token store, or to hand the tokens to the clients as required.

Both server-side and client-side token configurations support all of AM’s OAuth 2.0 features. Before you decide to keep server-side tokens, or to configure client-side tokens, consider the following:

Server-side OAuth 2.0 tokens

The CTS token store is the authoritative source for the tokens. AM returns a reference to the token to the client. That reference does not contain any of the token information. In the following example, the reference is stored in the access_token property:

{
  "access_token": "sbQZuveFumUDV5R1vVBl6QAGNB8",
  "scope": "write",
  "token_type": "Bearer",
  "expires_in": 3599
}

Server-side tokens are configured by default for all realms.
Clients cannot access the tokens other than to introspect them, making tokens less vulnerable to tampering attacks.
AM does not cache server-side tokens in memory. Therefore, every time a client presents a token ID in a request, AM checks if the token exists in the CTS token store (in case it has been revoked) and, if available, retrieves its information.

Reading from and writing to the CTS token store incurs overhead for the CTS DS instances.
If you need to add an additional layer of security for the stored tokens, consider one of the following alternatives:
- Configure AM to encrypt the tokens before storing them in the CTS token store.
- Configure DS to encrypt the CTS token store data.

For more information about both options, see Manage CTS tokens.

Tokens can only be introspected using a call to the authorization server.

Client-side OAuth 2.0 tokens

AM returns the token to the client after successfully completing one of the grant flows. In the following example, the token is stored in the access_token property:

{
   "access_token":"eyJ0eXAiOiJKV1QiLOT05FIiwiYWxnQY1lIjoxNTM5MDEzMzYyLsbSI6Ii8iLCj….",
   "scope":"write",
   "token_type":"Bearer",
   "expires_in":3599
}

A decoded access token produces JSON structures similar to the following:

{
     typ: "JWT",
     zip: "NONE",
     alg: "HS256"
}
{
     sub: "(usr!myClient)",
     subname" "myClient",
     cts: "OAUTH2_STATELESS_GRANT",
     auditTrackingId: "f20f4099-5248-4399-a7f0-2d54d4020099-108676",
     iss: "https://openam.example.com:8443/openam/oauth2",
     tokenName: "access_token",
     token_type: "Bearer",
     authGrantId: "1LUgI8zcDWqcfEnnLdZDnNqA2wc",
     aud: "myClient",
     nbf: 1539075967,
     grant_type: "client_credentials",
     scope: [
      "write"
     ],
     auth_time: 1539075967,
     realm: "/alpha",
     exp: 1539079567,
     iat: 1539075967,
     expires_in: 3600,
     jti: "FTQT6eZkDhm6PHEaSthORoTLB80"
}
[signature]

Token size may be a concern if tokens need to be sent in a header, since they are larger than the token reference returned for server-side tokens.

The size of the client-side tokens also increases when you customize AM to store additional attributes in the tokens. You are responsible for ensuring that the size of the token does not exceed the maximum header size allowed by your end users' browsers.
Can be configured by realm.
Tokens are presented to the client after successfully completing an OAuth 2.0 grant flow. Therefore, tokens are vulnerable to tampering attacks and you should configure AM to sign and encrypt them.
AM does not store the decrypt sequence of the token in memory, so decrypting and verifying tokens incurs overhead for the AM instances.

Token denylisting is a feature that maintains a list of revoked tokens and authorization codes stored in the CTS token store. This feature protects against replay attacks, and it is always enabled for client-side tokens.

Every time a client presents a client-side token in a request, AM checks the CTS token store to see whether the token has been denylisted (revoked). If it has not been denylisted, AM decrypts the token to retrieve its information.

Client-side refresh tokens have corresponding entries in a CTS allowlist, rather than a denylist. When presenting a client-side refresh token, AM checks that a matching entry is found in the CTS allowlist, and prevents reissue if the record does not exist.

Adding a client-side OAuth 2.0 token to the denylist removes the associated refresh token from the allowlist.

Clients can introspect the tokens without calling the authorization server. This can be advantageous in global deployments where keeping the CTS token store replication in sync fast enough to serve clients at any time by any server proves difficult. For more information about configuring client-side OAuth 2.0, see Configure AM for client-side OAuth 2.0 tokens.

AM 7.2.2

Token storage location