Enabling authentication from an external identity provider

You can integrate with your external identity provider (IdP) to securely authenticate external users to your IBM Cloud® account. By using your IdP, you can provide a way for users in your company to use single sign-on (SSO). Connecting your cloud account with an IBM Cloud App ID instance of your choice makes it all possible.

A more commonly used authentication method in IBM Cloud that federates you for all IBM products and has no usage charges is IBMid federation by registering your company's domain. Registering a company's domain with IBM enables users to log in to IBM products and services by using their existing company user credentials. Authentication is then handled by your company's IdP through single sign-on (SSO). For information about how to register your company for a federated ID, see the IBMid Enterprise Federation Adoption Guide. An IBM sponsor, such as a product advocate or client advocate, is required when you request to register federated IDs.

To begin setting up IBMid for enterprise federation, open a case at ibm.com/mysupport and select IBMid Enterprise Federation as the product.

If you choose to use an external IdP reference through IAM, each account can have up to five IdP references added through the Identity providers page in the Access (IAM) section of the console. You set up your IdP reference by selecting which App ID instance to integrate with IAM. Then, the IdP reference is given a random realm ID that is the unique prefix for users of that App ID service instance.

Setting up the integration between your App ID instance, which is already configured with your IdP, and your IBM Cloud account makes it so you can continue to manage all users externally in your IdP. It also simplifies the log in process to your cloud account for users in your enterprise. After the integration is complete, you must provide your users with a custom URL that they use to log in each time. There is no need to invite anyone to your account because if they exist as a user in your connected IdP's user repository, they can log in with their credentials through the custom URL.

Before you begin

To decide which is the right federation option for you, check the IBM Cloud SAML Federation Guide.
Create an instance of App ID from the IBM Cloud catalog. For more information, see the Getting started tutorial.
Configure your App ID instance. For more information about how to do this depending on your use case, see the App ID documentation about managing authentication.
Make sure you have the required access to view and manage IdP references, if you aren't the account owner. You must be assigned the operator role or higher on the App ID instance and the operator or administration role on the IAM Identity Service.

Configuration of your App ID instance for IAM integration

Review the following requirements about how your App ID instance must be configured to work properly as an IAM identity provider (IdP) for your IBM Cloud account.

If you plan to use your App ID instance for IAM IdP integration, then any user can log in to your account who can authenticate with that App ID instance. Therefore, consider following these guidelines when you configure your instance:

Disable the following types of authentication:

Facebook
Google
IBMid
Anonymous

If you decide to use Cloud Directory as an authentication method, disable the option for users to sign up through the app, and instead add only known users individually to your Cloud Directory.

Setting IAM-specific attributes in App ID tokens

For IAM to work correctly with your external IdP, you must ensure that the App ID instance provides all of the required attributes. See the following table for the required attributes:

Required attributes for App ID tokens
Attribute	App ID ID Token Claim	Source	Description
identifier (required)	ID	App ID generated	A unique identifier that identifies a user. It can't be changed during the life time of that user. App ID creates this identifier.
email (required)	email	Mapped from SAML assertion "email", which is mandatory for Cloud Directory and SAML configurations.	The user's email address.
username (recommended)	preferred_username if present, otherwise sub	Mapped from SAML assertion "preferred_username", "username", "user_name" or "userName" if available. Otherwise, the App ID generated "sub" claim is used	When you work with the CLI, APIs, or the IBM Cloud Kubernetes Service, the username displays. A username is often an email address, but can also be a different value. If the username is not provided by App ID, IAM uses the identifier instead.
firstname (recommended)	given_name if available, otherwise "notset" as default	Mapped from SAML assertion "given_name", "givenname", "givenName", "first_name", "firstname" or "firstName" if available, otherwise IAM uses the constant "notset"	The first name of the user that logs in.
lastname (recommended)	family_name if available, otherwise "notset" as default	Mapped from SAML assertion "family_name", "familyname", "familyName", "last_name", "lastname" or "lastName" if available, otherwise IAM uses the constant "notset"	The last name of the user that logs in.
name (optional)	name if present, otherwise built by the firstname, a space, and the last name	There is no automatic mapping from SAML	Full name, including middle initial, title, or anything that is not covered by first name and last name

When a user authenticates successfully by using the App ID service instance in the IBM Cloud account, the user is automatically added to the account. Added users don't get any access policies assigned by default. However, by using access groups and dynamic rules, you can set up automatically assigned access policies.

Enabling and connecting your identity provider

If you haven't configured any IAM IdP references before in your account, you must enable the login setting for your account first.

Enable the login settings for your account. You can skip this step if you've already enabled this setting.
1. Go to Manage > Access (IAM) > Identity providers in the IBM Cloud console, and click Enable.
2. Enter an alias for the default account URL, which you provide to users to log in to your account.
Since you're sharing the URL with external users, make sure that the alias is unique and simple. A common format might be to use your company name or a variation of it.
Click Create to create your IdP reference.
Enter a name for the IdP reference, and select the App ID instance that you want to connect.
Select how you want to onboard users:
- Static: (Default) Add each user to your account when they log in the first time.
- Dynamic: Add users to your account only if they log in and don't select a trusted profile.
- Never: Users aren't added to your account but can access your account by using trusted profiles. For more information about trusted profiles, see Creating trusted profiles.
If you have onboarding set to Static and the user selects a trusted profile when they log in the first time, the user is still added to the account.
Then, select the following settings (Optional):
- Enable for account login?: Enable your IdP references to be used for users to log in to your account. This option is set by default when you first create an IdP reference.
- Set as the default?: Users can use the default IdP reference URL that you created when you enabled this feature to log in to your account. You can have only one default IdP reference. For all other IdP references that you create, users must use the realm IDs to log in.
Click Create.

Your IdP reference is now available on the Identity providers list and the realm ID is generated automatically as the value that represents your IAM IdP in IBM Cloud.

Logging in with external identity provider credentials

After your App ID instance is connected to your IdP, and your App ID instance is integrated with IAM, your users can start logging in to your account. If the IdP reference is set as the default, then you can share the Default IdP URL for your account.

However, since you can have only one set as the default, but you can have up to five set-up in your account, you might need to get the URL for another IdP reference:

From the Identity provider pages, click the Actions icon for the row of the IdP reference you need a URL for.
Select View IdP URL.
Copy the IdP URL link to give to users to log in.

Using App ID instances to build dynamic rules in access groups

In addition to the required and recommended attributes, you can pass any kind of information with your SAML assertion. These attributes are available for you to use in dynamic rules in access groups.

To successfully build a dynamic rule, the following information is required:

Identity provider: Use the prefix appid:// and the realm ID from the IAM IdP. For example, appid://A1B2C3D4 if the realm ID of the user was A1B2C3D4.
Add users when: Use the name of the additional SAML assertion. This property is passed through unchanged.
If you are using the Cloud Directory option or the SAML federation option in App ID, notice that you can add custom attributes to each user's profile. You can use those properties for dynamic rules too. However, if you have the same property as a custom attribute and as a SAML assertion, then the custom attribute from the SAML assertion is used.

The IBM Cloud Kubernetes Service up to release 1.18 relies on unique usernames in an account. To work correctly, you must ensure that all usernames are unique across all IdPs. This means that you must make sure that the usernames that are onboarded to your account from IBMid and users that are onboarded to your account by an IAM IdP don't overlap. Otherwise, the IBM Cloud Kubernetes Service RBAC rules might get confused and give incorrect permissions.

If you are working with an external IdP, it is recommended that you connect with one external IdP only, and let users onboard automatically through this IdP.

Don't invite users by using the IBM Cloud invite process since this works only for users with IBMids. If you used IBM Cloud invites for your account, you would end up with a mixture of users coming from IBMid and users being automatically onboarded from your external IdP. This can easily lead to confusion because IBMid users log in through the IBM Cloud website while users from your external IdP must log in with a special URL. This can lead to duplicate usernames in one account, which is discouraged due to limitations in the Kubernetes Service as previously mentioned.

Using IdP data to build trusted profiles

After you have enabled and connected your IdP, you can start creating trusted profiles. To build trust with federated users, you can use the personal data from your IdP to search attribute names and values that exist in your organization.

If the users that you are creating a trusted profile for use IBM Cloud App ID, you should create the trusted profile as an App ID user, and likewise for IBMid. This way, your own SAML attributes can give you an idea of how to structure the trusted profile conditions. Other users with the same IdP can have different SAML attributes and you should use your own only as a hint. To use attributes in a claim that are different than your own, input them manually.

The conditions that you create filter out or allow federated users to apply the trusted profile depending on which attributes the federated users are assigned in your corporate user directory. When you create a trusted profile, you can view IdP data to see your own user claims from your organizations corporate user directory.

Let's say there is an attribute that is called groups that identifies departments, teams, and more granular internal organizations within your company. If there are developers in the US on the finance team that need the same level of access for a project, you might create a trusted profile with the following conditions:

Allow users when groups equals finance-dev
Allow users when country equals us

To make sure that your conditions allow only the federated users you intend to grant access to, contact your corporate directory architect for more information on available attributes.

For more information about the fields that are used to create conditions, see IAM condition properties.

It is recommended to create narrow conditions. You share the same IdP URL as everyone in your organization, so if a claim rule is too open, you might let users apply a trusted profile with access to your account unintentionally.