IBM Cloud® authentication and authorization rely on the industry-standard protocol OAuth 2.0. You can read more about OAuth 2.0 in RFC 6749 (link resides outside ibm.com)—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.
As specified in RFC 6749, applications are getting an access token to represent the identity that has been authenticated and its permissions. Also, 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 1 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 (for example, 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 2 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.
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.
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 1 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.
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 1 of the following events occur:
Figure 7: Login session expires after 24 hours.
Figure 8: Login session becomes inactive after 2 hours of not seeing any activity.
Figure 9: Login session gets revoked by a user hitting the logout or revoke button.
The IAM Administrator of an IBM Cloud account can configure certain parameters for login sessions:
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.
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 (for example, 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 (such as 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.
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).
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.
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.
The IAM settings allow you to configure the lifetime for access tokens and refresh tokens that have no related login session:
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: