About 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 CTS token store, or present them to the client. This architecture lets you scale your AM infrastructure horizontally, since any server in the deployment can satisfy any token request.

OAuth 2.0 token storage location is a property of the OAuth 2.0 service, which is 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 CTS-based and client-based token configurations support all OAuth 2.0 features present in AM. Before you decide to keep CTS-based tokens or to configure client-based tokens, consider the information in the following list:

CTS-Based OAuth 2.0 tokens (previously referred to as stateful tokens)
  • The CTS token store is the authoritative source for the tokens. AM returns to the client a reference to the token, but 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
    }
  • CTS-based 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 CTS-based 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 Managing CTS Tokens.

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

Client-Based OAuth 2.0 tokens (previously referred to as stateless 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: "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: "/",
         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 CTS-based tokens.

    The size of the client-based 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 blacklisting 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-based tokens.

    Every time a client presents a client-based token in a request, AM checks in the CTS token store if the token has been blacklisted (revoked). If it has not, then AM decrypts it to retrieve its information.

    Note

    Client-based refresh tokens have corresponding entries in a CTS whitelist, rather than a blacklist. When presenting a client-based refresh token, AM will check that a matching entry is found in the CTS whitelist, and prevent reissue if the record does not exist.

    Adding a client-based OAuth 2.0 token to the blacklist will also remove associated refresh tokens from the whitelist.

  • 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-based OAuth 2.0, see "Configuring AM for Client-Based OAuth 2.0 Tokens".

Read a different version of :