Tokens and login sessions in IBM Cloud

IBM Cloud authentication and authorization relies on the industry-standard protocol OAuth 2.0. You can read more about OAuth 2.0 in RFC 6749—The OAuth 2.0 Authorization Framework. Like most adopters of OAuth 2.0, IBM has also extended some of OAuth 2.0 functionality to meet the requirements of IBM Cloud and its customers.

Access and refresh tokens

As specified in RFC 6749, applications are getting an access token to represent the identity that has been authenticated and its permissions. Additionally, in IBM Cloud, the access token also represents the current account selected. When applications invoke IBM Cloud Services, this access token is transmitted as part of the API call as HTTP authorization header to provide information about the caller. The target IBM Cloud Service will do its authorization decision based on the content inside the access token:

Figure 1: API key is exchanged into an IAM access token, which is then used to call a service.

For specific use cases, applications can also retrieve refresh tokens from IAM. This way, applications can retrieve a new access token when the previous one expires. This is important for the IBM Cloud Console or IBM Cloud CLI, for example, because otherwise, the end user would need to log in again after the access token expires (i.e., after at least 60 minutes or even earlier). Refresh tokens need to be stored in a safe place—and even then, they eventually time out. 

Customer applications in IBM Cloud have two ways to create an access token to be able to invoke IBM Cloud services:

1. Use an API key to get an access token (see here for more information):

Figure 2: Exchanging an IAM API key into an access token.

2. Get an access token when running on an IBM Cloud-managed compute platform. For instructions on how to do that, please refer to the following blogs:

Figure 3: Exchanging a Compute Resource Token into an access token.

In both cases, the application has access to the API key or the Compute Resource Token from the IBM Cloud-managed compute platform anyway. Therefore, there is no benefit in the application storing and using the refresh token. When the application requires a new access token, it can use the API key or Compute Resource Token again. Therefore, IBM Cloud IAM will not produce refresh tokens for those use cases.

Token format

IBM Cloud is designed to scale. Therefore, access tokens in IBM Cloud use the JSON Web Token format (see also RFC 7519). JSON Web Tokens have a standard format:

Figure 4: Format of a standard JSON Web Token.

The signature of IBM Cloud access tokens is created using the asymmetric algorithm RS256. This means only IBM Cloud IAM can sign those access tokens, but any IBM Cloud Service (and even third-party applications) can verify the validity of a token signature using the public part of the signature key. IBM Cloud IAM announces the public part of currently valid signature keys here.

Figure 5: Sample output of keys endpoint.

IBM Cloud Services and other applications should download and cache those keys for one hour. Using those public signature keys, they can now validate the signature of those tokens. This way, IBM Cloud Services and APIs can validate those tokens without any relevant latency. They do not need to call out to IAM for each access token to check its validity. This method scales very well, as the validation load is scaled up with each IBM Cloud Service and API. As a consequence, those access tokens cannot be revoked—a revocation would require each adopter to check the access token with IAM. Such a call to IAM would destroy all advantages described above.

Refresh tokens do not follow any documented format. Only IBM Cloud IAM can create and understand them. To get a new access token for a refresh token, the refresh token needs to be sent to IAM. IAM will then validate the refresh token and its related entity and create an access token if the various validations are successful. This means a refresh token will fail to create a new access token if, for example, the related user was deleted from IBMid or the related Service ID does not exist anymore.

Login sessions

A login session is created at the time when an end user is logging in to IBM Cloud Console or to the IBM Cloud Command Line Interface (CLI) client. A user can view and manage login sessions using the interface. The user can end individual login sessions using this user interface or get an overview of login sessions for themselves. This way, the user can review and revoke their login sessions:

Figure 6: Login session overview.

A login session will end if one of the following events occur:

• The login session is expiring (24 hours by default)
• The login session was not actively used for a predefined time (two hours, by default)
• A user manually logs out from a login session or revokes a login session
• Too many login sessions have been opened (no limit, by default)

Figure 7: Login session expires after 24 hours. Figure 8: Login session becomes inactive after two hours of not seeing any activity. Figure 9: Login session gets revoked by a user hitting the logout or revoke button.

Configuring login session settings

The IAM Administrator of an IBM Cloud account can configure certain parameters for login sessions:

• Active sessions: Maximum lifetime of one single login session. After this lifetime has exceeded, the login session is marked as expired. You can start a new login session by entering login credentials again. The default is 24 hours. IAM Administrators can extend this duration up to 720 hours or lower this duration to 15 minutes. Figure 7 above describes a scenario when the default lifetime of 24 hours has been exceeded.
• Sign out due to inactivity: A login session is marked as being active based on the interaction of the application with IAM. For example, the usage of a refresh token resets the inactivity timer. The value to detect inactivity can be set by an IAM Administrator to at least 15 minutes or at most 24 hours. By default, two hours is used. Figure 8 above describes this scenario and ends the login session after two hours of inactivity.
• Concurrent sessions: By default, you can create an unlimited number of login sessions. There might be reasons to limit the maximum amount of login sessions (e.g., to limit the number of scripts running in parallel for a given user). For this scenario, you can set a limit of concurrent sessions. If a new login session extends the limit of concurrent sessions, the oldest running session is revoked. The state of the session is the same as if it would have been revoked manually as described in Figure 9.

The configuration settings for Access tokens and Refresh tokens on the Token expiration section are not related to tokens that are created for login sessions. These settings control the behavior of tokens that exist without a connected login session. You will find more details later in this blog.

Login sessions and tokens

As explained before, the IBM Cloud Console and the IBM Cloud CLI internally work with access and refresh tokens to be able to invoke IBM Cloud Services and IBM Cloud APIs. IBM Cloud combines the security of the OAuth 2.0 model with the session management capabilities of login sessions.

For login time, the calling application (e.g., the IBM Cloud Console) gets an access token and refresh token from IAM. In the background, IAM starts a login session and connects the access and refresh token with the login session. As access tokens cannot be revoked, the lifetime of access tokens is limited to 20 minutes or fewer.

Whenever the access token expires, the calling application must use the refresh token to obtain a new access token. The session has an inactivity timer that is started at login time and reset whenever an activity (e.g., a refresh token operation) is detected. The session ends if the session is actively revoked, the overall session expiration is met or the session detects inactivity. All refresh tokens stop working if the session ends.

Figure 10: Relation between login session, access token and refresh token.

Tokens without login sessions

Creating and persisting login sessions is a compute-intensive operation. Therefore, IBM Cloud cannot create a login session for every interaction. Especially for service invocations, there is often no need for login sessions or the ability to revoke sessions or refresh tokens (if reasonable lifetimes are chosen).

Access tokens without refresh tokens

If you—as described at the beginning of this blog—create an access token using an API key or you retrieve access token based on your compute platform, you have no need to use a refresh token. You can always create a fresh access token using the API key or based on the Compute Resource Token that the compute platform provides. Therefore, IBM Cloud IAM will not generate a refresh token in those scenarios. Also, you will not create a login session in the background.

Access and refresh tokens without login sessions

If you log in to the IBM Cloud CLI using an API key that represents a Service ID, this interaction will not create a login session. Nevertheless, the CLI expects to run longer than it takes for an access token to expire, so the CLI will require a refresh token. IBM Cloud IAM will create an access and refresh token that are not connected to a login session.

Those tokens are usually expected to be used inside a CLI only, and therefore on an environment that has reasonable protection against misuse.

Configuring token expiration

The IAM settings allow you to configure the lifetime for access tokens and refresh tokens that have no related login session:

• Access tokens: The lifetime for access tokens created inside this account is independent from login sessions. The default value is 60 minutes. This means that if you are creating an access token for an API key, you will, by default, retrieve an access token that is treated as valid for the next 60 minutes by IBM Cloud Services. If you want to limit the lifetime for access tokens, you can choose a smaller value. Consider choosing a value that still allows you to execute all required IBM Cloud Services. Some longer-running operations like searching with the Data Engine inside COS buckets might stop working.
• Refresh tokens: By default, refresh tokens are valid for up to 72 hours. This means that if you logged in to the IBM Cloud CLI with an API key for a Service ID, this IBM Cloud CLI can continue working for the next 72 hours, as it can refresh the access token whenever required. If your account does not have such a requirement, you can lower the lifetime for refresh tokens to a lower value. Please consider that this limits the maximum execution time for long-running services that use a refresh token to proceed. Again, this configuration only applies to refresh tokens that are created independent from login sessions.

Summary

IBM Cloud IAM uses access tokens to allow clients to call IBM Cloud Services. For API interactions, IBM Cloud IAM avoids having to generate refresh tokens as much as possible. One exception to that rule is the use of Service IDs for IBM Cloud CLI operations. To also allow long-running interactions with IBM Cloud that go beyond the lifetime of an access token, IBM Cloud IAM offers login sessions that give the end user control over the session expiration and revocation.

Please review the IAM Settings to see if they match your needs:

Figure 11: IAM settings related to login sessions and tokens.

Please remember that the two expiration settings for access and refresh tokens in the section Token expiration only relate to API interactions and Service ID sessions inside the IBM Cloud CLI. Normal user sessions in the IBM Cloud Console or similar applications will create a Login session. The expiration of access tokens and refresh tokens are indirectly influenced by the session configuration parameters under Login session.

To learn more, check out these resources: