About Token Storage Location

Identity Cloud OAuth 2.0-related services are stateless unless otherwise indicated; they do not hold any token information local to the Identity Cloud 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 Identity Cloud 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 Identity Cloud. 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. Identity Cloud 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.

  • Identity Cloud does not cache CTS-based tokens in memory. Therefore, every time a client presents a token ID in a request, Identity Cloud 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.

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

Client-Based OAuth 2.0 tokens (previously referred to as stateless tokens)
  • Identity Cloud 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 CTS-based tokens.

    The size of the client-based tokens also increases when you customize Identity Cloud 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 Identity Cloud to sign and encrypt them.

  • Identity Cloud does not store the decrypt sequence of the token in memory, so decrypting and verifying tokens incurs overhead for the Identity Cloud 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, Identity Cloud checks in the CTS token store if the token has been blacklisted (revoked). If it has not, then Identity Cloud 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, Identity Cloud 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 Identity Cloud for Client-Based OAuth 2.0 Tokens".

Read a different version of :