PingAM 7.5.0

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 cache the OAuth 2.0/OpenID Connect tokens in the Core Token Service (CTS) token store (server-side), or present them to the client (client-side). 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.

By default, OAuth 2.0 tokens are configured for server-side storage. You can update the token storage location for the realm by setting the Use Client-Side Access & Refresh Tokens property in the AM admin UI:

  • On the OAuth 2.0 provider:

    Go to Realms > Realm Name > Services > OAuth2 Provider.

  • To override provider settings on the client:

    Go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client ID > OAuth2 Provider Overrides.

    Note that Enable OAuth2 Provider Overrides must be enabled for the setting to apply.

For information about configuring client-side OAuth 2.0, refer to Configure AM for client-side OAuth 2.0 tokens.

Both server-side and client-side token configurations support all AM’s OAuth 2.0 features.

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, which does not contain any of the token information. In this example, the reference is stored in the access_token property:

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

  • 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. Each 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 a layer of security for the stored tokens, consider one of the following options:

    • 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, refer to 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 this 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]

  • Client-side tokens are larger than the reference returned for server-side tokens, so consider their size if they must be sent in a header. You must ensure the size of the token does not exceed the maximum header size allowed by your end users' browsers.

  • The size of client-side tokens also increases when you customize AM to store additional attributes in the tokens.

  • 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.

  • Clients can introspect tokens without calling the authorization server.

  • 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.

    Each 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 doesn’t exist.

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