Tokens and login sessions in IBM Cloud

IBM Cloud authentication and authorization uses the industry standard protocol OAuth 2.0. You can read more about OAuth 2.0 in RFC 6749 – OAuth 2.0 Authentication Framework. Like most OAuth 2.0 adopters, IBM has extended some OAuth 2.0 features to meet the needs of IBM Cloud and its customers.

Access and refresh tokens

As specified in RFC 6749, the application obtains an access token representing the authenticated identity and corresponding permissions. Additionally, in IBM Cloud, an access token represents the current account selected. When an application calls an IBM Cloud service, this access token is sent in the HTTP authentication header as part of the API call to provide information about the caller. The target IBM Cloud service makes authorization decisions based on the content inside the access token.

For certain use cases, your application can also retrieve a refresh token from IAM. This allows your application to retrieve a new access token when the old access token expires. For example, this is important for the IBM Cloud Console or IBM Cloud CLI. Otherwise, end users will have to log in again after their access token expires (i.e. at least 60 minutes or sooner). Refresh tokens should be stored in a safe location, or doing so will eventually cause a timeout.

Customer applications on IBM Cloud have two ways to create access tokens so they can call IBM Cloud services.

1. Obtain an access token using your API key (see details here).

2. Obtain an access token when running on the IBM Cloud managed computing platform. For instructions on how to do this, see the following blog:

In both cases, the application has access to the API key or compute resource token of the IBM Cloud managed computing platform. Therefore, there is no benefit to applications that store and use refresh tokens. If your application requires a new access token, you can reuse the API key or compute resource token. Therefore, IBM Cloud IAM does not generate refresh tokens for that use case.

token format

IBM Cloud is designed to scale. Therefore, access tokens in IBM Cloud use the JSON web token format (see RFC 7519). JSON web tokens have the following standard format:

The signature of the IBM Cloud access token is generated using the asymmetric algorithm RS256. This means that only IBM Cloud IAM can sign that access token, but any IBM Cloud service (and even third-party applications) can use the public portion of the signing key to verify the validity of the token signature. IBM Cloud IAM publishes the public portion of the currently valid signing key here.

IBM Cloud services and other applications must download the key and cache it for one hour. You can now verify the signature of that token using the public signing key. This way, IBM Cloud services and APIs can validate that token without any associated latency. There is no need to call IAM for each access token to check its validity. This method scales very well as the validation load scales with each IBM Cloud service and API. As a result, that access token cannot be revoked. Cancellation requires each adopter to verify the access token with IAM. This call to IAM destroys all the benefits described above.

Refresh tokens do not follow a documented format. Only IBM Cloud IAM can create and understand it. To obtain a new access token for a refresh token, you must send the refresh token to IAM. IAM then validates the refresh token and associated entities and generates an access token if the various validation checks are successful. This means that a refresh token will not generate a new access token, for example if the relevant user has been deleted from the IBM ID or the relevant service ID no longer exists.

login session

A login session is created when an end user logs in to the IBM Cloud console or IBM Cloud command line interface (CLI) client. Users can use the interface to view and manage their login sessions. This user interface allows users to terminate individual login sessions or view an overview of login sessions directly. This way, users can review and cancel their login sessions.

Your login session ends when one of the following events occurs:

• Your login session expires (by default 24 hours).
• The login session has not been actively used for a predefined period of time (2 hours by default).
• The user manually logs out of the login session or cancels the login session.
• Too many login sessions are open (no limit by default).

Configure login session settings

The IAM administrator for your IBM Cloud account can configure certain parameters for login sessions.

• Active Session: Maximum lifetime of a single login session. If this lifetime is exceeded, the login session is marked as expired. You can start a new login session by re-entering your login credentials. The default is 24 hours. IAM administrators can extend this period up to 720 hours or reduce it by 15 minutes. Figure 7 above illustrates a scenario where the default lifetime of 24 hours is exceeded.
• Logout due to inactivity: Login sessions are marked as active based on the application’s interaction with IAM. For example, using a refresh token will reset the inactivity timer. The value for detecting inactivity can be set by your IAM administrator to a minimum of 15 minutes or a maximum of 24 hours. By default, 2 hours are used. Figure 8 above illustrates this scenario, terminating the login session after two hours of inactivity.
• Concurrent Sessions: By default, you can create an unlimited number of login sessions. There may be reasons to limit the maximum amount of login sessions (for example, to limit the number of scripts running in parallel for a particular user). In this scenario, you can set a concurrent session limit. When the concurrent sessions limit is extended due to new login sessions, the longest running session is canceled. The session state is the same as if it had been manually canceled, as depicted in Figure 9.

The configuration settings for access tokens and refresh tokens in the Token Expiration section are not relevant to tokens generated for login sessions. These settings control the behavior of tokens that exist without an associated login session. More details can be found later in this blog.

Login session and token

As previously explained, the IBM Cloud console and IBM Cloud CLI can use access and refresh tokens internally to call 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.

When you log in, the calling application (such as the IBM Cloud console) gets an access token and refresh token from IAM. In the background, IAM starts a login session and associates access and refresh tokens with the login session. Because access tokens are irrevocable, their lifetime is limited to 20 minutes or less.

Whenever an access token expires, the calling application must use a refresh token to obtain a new access token. The session has an inactivity timer that starts at login and is reset whenever activity (e.g. refresh token activity) is detected. A session is terminated when it is actively canceled, when the overall session expiration is met, or when the session detects inactivity. When a session ends, all refresh tokens stop working.

Token without login session

Creating and maintaining a login session is a computationally intensive task. Therefore, IBM Cloud cannot create a login session for every interaction. Service calls in particular often do not require a login session or have the ability to revoke a session or refresh token (if you choose a reasonable lifetime).

Access token without refresh token

If you use an API key to generate an access token or retrieve an access token based on your compute platform, as described at the beginning of this blog, you do not need to use a refresh token. You can generate new access tokens at any time using your API key or based on a computing resource token provided by your computing platform. Therefore, IBM Cloud IAM does not generate a refresh token in that scenario. It also doesn’t create a login session in the background.

Access and refresh tokens without a login session

If you log in to the IBM Cloud CLI using an API key that represents your service ID, this interaction does not create a login session. Nonetheless, the CLI expects the access token to run longer than it takes to expire, so the CLI requires a refresh token. IBM Cloud IAM generates access and refresh tokens that are not tied to your login session.

These tokens are typically used only within the CLI and therefore in an environment that provides reasonable protection against misuse.

Configure token expiration

IAM settings allow you to configure the lifetime of access tokens and refresh tokens without an associated login session.

• Access Token: The lifetime of access tokens generated within this account is independent of the login session. The default is 60 minutes. This means that when you create an access token for an API key, by default the IBM Cloud service retrieves the access token, which is treated as valid for the next 60 minutes. If you want to limit the lifetime of the access token, you can choose a smaller value. Consider choosing a value that allows you to run all the IBM Cloud services you need. Some long-running operations, such as searches using the data engine inside a COS bucket, may stop working.
• Refresh token: By default, refresh tokens are valid for up to 72 hours. This means that if you log in to the IBM Cloud CLI using the API key for your service ID, you can refresh your access token whenever necessary, allowing this IBM Cloud CLI to continue to function for the next 72 hours. If your account does not have these requirements, you can lower the refresh token’s lifetime to a lower value. Consider that this limits the maximum execution time of long-running services that use refresh tokens to continue. Again, this configuration only applies to refresh tokens generated independently of the login session.

summary

IBM Cloud IAM uses access tokens to allow clients to call IBM Cloud services. For API interactions, IBM Cloud IAM avoids the need to generate as many refresh tokens as possible. One exception to that rule is the use of service IDs for IBM Cloud CLI operations. Additionally, to allow long-running interactions with IBM Cloud that exceed the lifetime of the access token, IBM Cloud IAM provides login sessions that give end users control over session expiration and cancellation.

Review your IAM settings to make sure it meets your needs.

Remember to set two expiration settings for access and refresh tokens in the section. Token Expiration Relevant only to API interactions and service ID sessions within the IBM Cloud CLI. A regular user session in the IBM Cloud Console or similar application login session. Expiration of access tokens and refresh tokens is indirectly affected by the session configuration parameters below. login session.

Check out these resources to learn more: