IBM Cloud Identity and Access Management — Clients

12 min readMar 19, 2020

Story Collection “IBM Cloud Identity and Access Management”

This story is part of a collection of stories that explain IBM Cloud Identity and Access Management. The following overview shows the stories that I have already published on medium:

Story 1: Overview
- What is Identity and Access Management?
- Scenarios covered by Identity and Access Management
- Tokens used in IBM Cloud
Story 2: Token in Details
- Response from the token endpoint
- Access, Refresh and ID Token
- UAA Token
- IMS Token
- Identity Cookie
- Delegated Refresh Token
Story 3: Clients (this story)
- The “client” in OAuth 2.0
- What is a “client” in IBM Cloud IAM
- The “default client” in IBM Cloud IAM
- Who can register clients in IBM Cloud IAM?
Story 4: Securely Sharing Long-Running Authentication & Authorization
- Recap of token types and their usage
- Scenarios that require long-running authorization
- Delegated Refresh Tokens in IBM Cloud IAM
- Conclusion

The “client” in OAuth 2.0

According to RFC 6749 — the specification for OAuth 2.0 — a client is:

client
An application making protected resource requests on behalf of the resource owner and with its authorization. The term “client” does not imply any particular implementation characteristics (e.g., whether the application executes on a server, a desktop, or other devices).

The specification distinguishes two basic types of clients :

confidential clients: Applications that can maintain client credentials securely. This typically applies to any server-side application like web applications that maintain credentials and tokens on the server-side.
In IBM Cloud, this would map to e.g. the IBM Cloud Console UI.
public clients: Applications that run on the end user's device, either native or as a browser-based application. This type applies to e.g. native applications running on smartphones or personal computers. End users will typically be able to retrieve client credentials somehow in this scenario.
In IBM Cloud, this would map to e.g. the IBM Cloud CLI or the IBM Cloud app for smartphones.

OAuth 2.0 section 2 describes the following attributes for confidential clients:

identifier: the client_id is a unique identifier for the client interacting with the authorization server
password: the client_secret is used authenticate a client to the authorization server; the specification alternatively also describes the option to issue a public/private key pair per client, but I am not aware of any implementation using this authentication for clients

As an additional attribute, public and confidential clients should register one or more redirection endpoints. There are no more mandatory or optional attributes listed for clients in the OAuth 2.0 specification.

What is a “client” in IBM Cloud IAM?

Each implementation of OAuth 2.0 requires additional attributes. In the following section, you see a very long, but complete list of attributes that clients in IBM Cloud IAM need to register. Typical adopters of IBM Cloud IAM only see a subset of those options. Nevertheless, a lot of these options were required to add specific behavior for special clients with specific needs.

client_id: (from OAuth 2.0) A unique identifier for the client interacting with the authorization server. This value is not a secret — end users will see its value e.g. during the authorization request in the browser’s address bar.
client_secret: (from OAuth 2.0) A credential that is used to authenticate the client to the authorization server. Typically, the client_id and client_secret are sent via basic authorization HTTP header in requests to the token endpoint. This value must not be sent via a query parameter to the server in any API. In exceptional cases, these values can be sent via POST body, too.
external_flow_secret: This credential is used for a special grant type “external flow” that will be described in a later post. Each client can optionally have a separate secret for this grant type to limit the blast radius if one of the secrets got compromised. If the external_flow_secret is not set, but the grant type “external flow” is used, the client_secret is used instead.
source: Describes the way how this client was created.
Potential values are:
- STATIC: this client is pre-defined in IBM Cloud IAM
- ADMIN: this client was created manually via administration tooling
- RMC: this client was created and is managed via the RMC tool — tooling to onboard 3rd party services and IBM services to IBM Cloud; the RMC tool will be described in the section “Who can register clients in IBM Cloud IAM?”
- CFEE and ROKSA: this client was created by another IBM Cloud Service automated
state: Describes the current state of the client.
Potential values are:
- ACTIVE: this client can be used for authentication & authorization
- PENDING: this client is about to be deleted — it cannot be used anymore for authentication & authorization requests, but it will still be shown in the RMC tool (see source)
- DELETED: this client is deleted — this client will not be shown in the RMC tool (see source)
ibmid_client: During authentication, if using IBMid as a delegated authorization server, IBM Cloud IAM is using a default IBMid client id for authorization requests. Some IBM Cloud IAM clients have specific requirements to use a different IBMid client id for this operation, e.g. to use a tailored IBMid login UI. Those IBM Cloud IAM clients can pre-register such an IBMid client id with the IAM team. The IAM team will assign this IBMid client id a symbolic “ibmid_client name”. This value can now be used as “ibmid_client” that is pointing to this pre-registered IBMid client id.
description: A textual description of the client, its application or its owners. This value is only visible for the IBM Cloud IAM team.
service_name: If registering a service with the RMC tool (will be described in the section “Who can register clients in IBM Cloud IAM?”), a client can be created, too. This attribute stores the link between client and service, i.e. this client belongs to the service “service_name” in RMC.
compliance: This attribute decides if this client expects to be handled as an OAuth 2.0 or Open ID Connect client.
- OAUTH2: This client will not get an ID token, it will only retrieve an access token and refresh token. This is the default setting and usually sufficient for IBM Cloud IAM clients.
- OIDC: This client will get an ID token according to the Open ID Connect specification. IBM Cloud IAM clients will only be assigned this setting if they have special requirements, e.g. they need to integrate with a 3rd party application or library that can only work with Open ID Connect compliant authorization servers.
authorized_grant_types: List of grant types that this client id is authorized to use. Each grant type will be explained in one of the next stories in more details, therefore just a quick overview:
- authorization_code: Used for browser-based logins according to OAuth 2.0 / Open ID Connect.
- password: Used to authenticate with username/password. Also known as “resource owner password credentials grant type” according to OAuth 2.0.
- refresh_token: This OAuth 2.0 grant type allows to get a fresh access token from a previously issued refresh token.
- urn:ibm:params:oauth:grant-type:iam-authz: This grant type is an IBM Cloud IAM extension and allows to create tokens based on an IAM authorization decision.
- urn:ibm:params:oauth:grant-type:apikey: This grant type is an IBM Cloud IAM extension and allows to create tokens using an API key for a User or a Service Id.
- urn:ibm:params:oauth:grant-type:passcode: This grant type is an IBM Cloud IAM extension and allows to create tokens based on a code that is generated using a browser-based login. This grant type can be used to allow secure logins to Command Line Interface clients without requiring the password grant.
- urn:ibm:params:oauth:grant-type:identity-cookie: This grant type is an IBM Cloud IAM extension and allows clients that run in the cloud domain, i.e. any URL that ends with .cloud.ibm.com to create a token in a performance-optimized way. More details will be described in a later story.
- urn:ibm:params:oauth:grant-type:iam-cookie: This grant type is an IBM Cloud IAM extension. Clients can decide to share a common authorization state with an “IAM cookie” e.g. as a browser cookie. IAM itself is not setting the cookie on the browser nor reading it from the browser, but supports the creation and consumption of those cookies via API. This grant type supports the consumption of such a cookie and returns access token and refresh token, if the API call returns correctly. Also here, more information will follow in subsequent stories.
- urn:ibm:params:oauth:grant-type:ims-portal: This grant type is an IBM Cloud IAM extension and allows to create tokens based on an internal “IMS” token that is used internally in SoftLayer UIs and APIs. Only those clients who can explain their need for this grant type and why other ways do not work will get this authorization.
- urn:ibm:params:oauth:grant-type:derive: This grant type is an IBM Cloud IAM extension and can be used to derive a public CloudFoundry “UAA” token and/or an “IMS” SoftLayer token based on an IAM access token.
- urn:ibm:params:oauth:grant-type:delegated-refresh-token: This grant type is an IBM Cloud IAM extension and designed to allow passing a refresh token from one client id to another client id in a controlled and secure way. One client can retrieve a “delegated refresh token” by specifying the appropriate response_type in the request. In addition, the receiving list of client ids must be specified. Only clients that were listed during the creation of that “delegated refresh token” are able to consume this token type using this grant type. The response will contain an IAM access and refresh token belonging to the actual client id. Also here, a separate story with detailed explanation and sample will follow.
response_types: An enumeration of response types that a client is allowed to request when asking for tokens:
- cloud_iam: Default response type and typically enabled for all clients.
- uaa: Adopters that require to call public CloudFoundry APIs can request a UAA token that represents the IAM token best.
- ims_portal: Adopters that require to call Infrastructure APIs (previously SoftLayer) with their native token system can request a suitable token with this response type. In the meantime, these APIs support IAM tokens directly, so there are only few cases that require that response type at all.
- identity_cookie: This response type represents the logged in user. This value is typically set by the IAM server during the UI login interaction, the response type here is meant to build automated test cases. Therefore, only selected clients are authorized for this response type.
- iam_cookie/delegated_refresh_token: This cookie value supports sharing refresh tokens across a well-defined set of client ids. The iam cookie is the older and deprecated version, new clients should only use the delegated refresh token. More details about delegated refresh tokens will be covered in a follow-on story.
subject types: This client is authorized to created tokens for either UserId, ServiceId, or both types of subjects.
emails: Each client is registered to at least one owner. These owners are stored in this property and they are used to contact the owner of client ids when necessary and make sure that one user is not registering more than 5 client ids.
redirect URIs: A preregistered set of URIs that the client is allowed to pass as redirect_uri during an OAuth2.0 / Open ID Connect UI interaction. Redirect URIs are allowed to contain a wildcard star ( * ) to represent any string up to the next dot ( . ) or slash ( / ). A sequence of two wildcard stars ( ** ) are representing any string without exception. Using two wildcard stars is a very broad wildcard and should only be used with caution in cases where any other solution fails.
post logout redirect URIs: If using the browser-based logout UI, clients can specify non-default redirect URI that should be used after logging out. This property contains a whitelist of those redirect URIs. Also here, the same wildcards as in the Redirect URI property can be used.
scopes: List of scope values that this client can use. IBM Cloud Services typically have ibm and their serviceName as registered values. There will be a separate story on scopes.
CLI scopes: Same as scopes, but only applicable for CLI-kind logins, i.e. the grant types password, urn:ibm:params:oauth:grant-type:apikey and urn:ibm:params:oauth:grant-type:passcode.

The “default client” in IBM Cloud

IBM Cloud API keys were introduced to allow customers to easily get IAM access tokens that can be used to call IBM Cloud APIs. The simplest way to get an access token is this curl command:

curl
--data-urlencode “grant_type=urn:ibm:params:oauth:grant-type:apikey” \
--data-urlencode “apikey=…” \
“https://iam.cloud.ibm.com/identity/token"

As you can see, this request does not contain any authorization information. No client_id / secret is sent as authorization header though the OAuth 2.0 specification would expect that.

If strongly following the OAuth 2.0 specification, IBM Cloud IAM could

enable any customer of IBM Cloud to create their own client_id / secret as a prerequisite before being able to call IAM to create an access token

use and publish a wide-known, public secret like e.g. CloudFoundry is using the client id cf with an empty password for their CLI interactions

Generating a customer-owned client_id / secret pair is an inconvenient step without adding any relevant security. Most customers would have a hard time understanding the benefit of this step, instead, because of the increased complexity, they would more likely not adopt this type of authentication model. Therefore, IBM Cloud IAM decided to not require each customer to create their own client_id / secret pair just for leveraging API keys. The second option, i.e. publishing a wide-known, public secret has no real security benefit either.

Therefore, IBM Cloud IAM introduced the notion of a “default client”. This means any operation that would expect a basic authorization header containing the client id/secret of the client can also run without any authorization header. In that case, IBM Cloud IAM assumes that the “default client” is used for the API interaction.

The “default client”’s settings are:

client_id: default
client_secret: none
external_flow_secret: none
source: STATIC, i.e this client is pre-defined in IBM Cloud IAM
state: ACTIVE, i.e. this client can be used for authentication & authorization
ibmid_client: none
description: none
service_name: iam-identity
compliance: OAUTH2, i.e. this client will not get an ID token, it will only retrieve an access token and refresh token.
authorized_grant_types: urn:ibm:params:oauth:grant-type:apikey
Allows to create IAM access tokens using an API key.
response_types: cloud_iam & delegated_refresh_token
subject types: UserId & ServiceId
emails: none
redirect URIs: none
post logout redirect URIs: none
scopes: ibm
CLI scopes: none

The “default client” is very limited and only usable for converting an API key into an IAM access token or generated a delegated refresh token. There is no support for any other grant type. This means, the “default client” also does not support the grant type refresh_token. This means an API Key will return an IAM access token that will be valid for about an hour. To refresh that token, instead of using the grant type refresh_token, you must generate the IAM access token from the API key again. The “default client” is preinstalled and available for every customer of IBM Cloud.

Who can register clients in IBM Cloud IAM?

IBM Cloud is dealing with the following groups of users:

Customers of IBM Cloud i.e. registered users that have created an IBM Cloud Account
Users running third-party services that can be consumed by customers of IBM Cloud
Users running IBM Cloud services that can be consumed by customers of IBM Cloud

As outlined above in The “default client” in IBM Cloud, customers do not need to create clients. The only use case in which customers require to create IAM access tokens is the scenario in which they use an API key to get an IAM access token for a User or Service Id.

If a user wants to offer a third-party service that he is offering to customers in IBM Cloud, this user needs to follow this onboarding process:
https://cloud.ibm.com/docs/third-party?topic=third-party-get-started
As part of this onboarding process, the third-party service is registering technical details in the resource management console (RMC) dashboard: https://cloud.ibm.com/onboarding/dashboard
As part of this registration process, the owner of the third-party service can create an IBM Cloud IAM client that can be used to integrate with User Interfaces, Command-Line Interfaces and the service implementation itself.

The process to register an IBM Cloud service is similar to the process for third-party services. Also here, during the onboarding process in the resource management console, the owner of the IBM Cloud service can register an IBM Cloud IAM client to be able to integrate with the IBM Cloud Console under https://cloud.ibm.com , integrate with the IBM Cloud CLI and for usage inside the IBM Cloud service itself.

What’s next?

This story is a very detailed description of IBM Cloud IAM clients. You can keep this story as a reference that you can visit again if you need to understand the details of a client’s definition. The next stories will concentrate more on individual grant types and their usage.

If you have comments, questions, or want to see a specific topic being covered in one of the next stories, please leave a comment or contact me. Your feedback is welcome!