Configuring single sign-on using OpenID Connect (OIDC)
Using OIDC, you can configure single sign-on (SSO) between your product and supported providers.
OIDC is an authentication protocol layer that is built on the top of the OAuth 2.0 protocol. It allows the third-party applications to:
- Verify the identity of the end-users.
- Get the basic profile information about the end-users.
The following steps represent the flow that happens while configuring SSO using OIDC:
-
A user attempts to access a service in your product through a web browser.
-
Your product verifies whether an authentication token is present.
-
If no authentication token is present, your product redirects the request for authentication to the third-party authorization server of the user.
-
The authorization server presents a login page to the user.
-
If the user logs in successfully, the authorization server redirects the user, along with the OIDC response, to your product.
-
Your product generates an authentication token and grants access to the service that the user requested.
Configuring SSO in your product using OIDC
Note:
-
You can configure SSO with OIDC support by using the Identity Provider (IdP) V3 APIs. For more information, see IdP V3 APIs.
-
Currently, OpenID Connect (OIDC) is the only supported protocol with the IdP V3 version. From foundational services version 3.19 and later, you can register OIDC provider by using the IdP V3 API.
-
To verify if you have OIDC support or not, see Getting the list of registered OIDC clients by query.
Before you begin
Login to any of the following platforms by using the provided IdP links and register yourself in the application. While registering use application url as cp-console url and redirect URL as https://<cp-console-url>/ibm/api/social-login/redirect/<name of the oidc>
.
Once you are registered, you can get the unique client ID, client secret and discovery_url
endpoint. Currently, only these platforms are verified to register the OIDC by using the IdP V3 API.
Platform | IdP link |
---|---|
IBM Security Verify (ISV) | https://www.ibm.com/docs/en/erqa?topic=using-security-verify-as-oidc-provider Note: Whenever you perform the attributes mapping through the OIDC provider in the ISV application, enable the Send all known user attributes in the ID token option. And, ISV groups must not contain spaces. |
Google Cloud Platform | https://cloud.google.com/identity-platform/docs/web/google |
Microsoft | https://cloud.google.com/identity-platform/docs/web/microsoft |
Okta | https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm |
Procedure
To configure SSO, complete the following sequence of steps:
-
Register the OIDC clients. For more information, see Registering the OIDC clients.
-
Open the CloudPak home page to verify whether the OIDC is successfully configured.
Note: Once the OIDC is successfully configured, you can login to the cp-console. However, to login into the Cloud Pak Platform and to get the OIDC successfully configured, first you need to onboard the OIDC users into the Cloud Pak Platform. Then, the OIDC users will be able to login to the cloud pak Platform.
-
To authenticate, click the corresponding OIDC link in the CloudPak home page.
Onboarding OIDC users into the Cloud Pak Platform
To onboard OIDC users into the Cloud Pak Platform, run the following command:
cloudctl iam team-add-users <zen-team> CloudPakAdministrator -u <user e-mail>
Where, user e-mail is the email ID of the user that is going to onboard in the Cloud Pak Platform.
Now, complete the following steps to grant a Admin role for Cloud Pak Platform. The procedure is based on the APIs.
-
Configure environmental variables:
-
Obtain an IAM access token for the default admin user:
- Log in as an admin using the
cloudctl
, and run thecloudctl tokens
command to obtain the access token. The output resembles the following:
Access token: Bearer b399609f2d2cd8c3b3ec67b0188affc178444a8ea9845f4a11907b7eb3f0f41f20068e91c675a7336e82f8e69eea4d961a60fe3ac7c835eeb8d7922e4f3b2f0c150bbce37862b4f50aa11f0cea623e16cc278a039ce624944be0047f21fbc623cec024089d0b69c4f0f3407e7492e7867ae5ab280d8a410e3a92e0c06790ec09a47e9a3be2b5522413ed34c33f07d436ec5887b39143683fee86d0c32b67acab4855e2a33e5441e69f158bcb1d6d87d5bd0517748581efbb4ff7384182da26c0afc13a01e34aa228af3ac779b11de2f3fe521306534b7b7a97f7c9371352c98daddb28b602fb6113f37af3ed5f37fd10cae8b9c0179c37d6d48b48fe74380254a90dbda89d2d2db13a74edfa8878061eab652af2a89014c1f8765b33c44fd50991c7abb8811df857c9377aee7e9b1dd5083a61fdfff6edac196b37b59314065b840f99df516181ff2b06d11509a93a47438837ee3f257dc00e93c6b3e9e5a1cca269b00d8268d5dd788327cc92bd7b5281f457d9e17d8dd6816211f66107f9476f9a715bb2d9cc6251077d67b1f38729e94f0bdf9aadd932100d9dece0056dec1b34d0191d6bb7d216b1067279041ac88335d7549401e0d593c7aae51e3ed390eda4787face5f94502c516dc19a9bebda236c84d5d21d7ebb0a377af1ff25ff13a9a1c09181d6bbfd89b5a85fc285ee5360450761f781b40f189e301fac7f80f ID token: sha256~ET9DuuQoW8hbke4yr2CwatmkjA3jQKDRHCHnGsfDH58
- Then, copy the value after Bearer and paste the value to set the TOKEN environment variable. For example,
export TOKEN=b399609f2d2cd8c3b3ec67b0188affc178444a8ea9845f4a11907b7eb3f0f41f20068e91c675a7336e82f8e69eea4d961a60fe3ac7c835eeb8d7922e4f3b2f0c150bbce37862b4f50aa11f0cea623e16cc278a039ce624944be0047f21fbc623cec024089d0b69c4f0f3407e7492e7867ae5ab280d8a410e3a92e0c06790ec09a47e9a3be2b5522413ed34c33f07d436ec5887b39143683fee86d0c32b67acab4855e2a33e5441e69f158bcb1d6d87d5bd0517748581efbb4ff7384182da26c0afc13a01e34aa228af3ac779b11de2f3fe521306534b7b7a97f7c9371352c98daddb28b602fb6113f37af3ed5f37fd10cae8b9c0179c37d6d48b48fe74380254a90dbda89d2d2db13a74edfa8878061eab652af2a89014c1f8765b33c44fd50991c7abb8811df857c9377aee7e9b1dd5083a61fdfff6edac196b37b59314065b840f99df516181ff2b06d11509a93a47438837ee3f257dc00e93c6b3e9e5a1cca269b00d8268d5dd788327cc92bd7b5281f457d9e17d8dd6816211f66107f9476f9a715bb2d9cc6251077d67b1f38729e94f0bdf9aadd932100d9dece0056dec1b34d0191d6bb7d216b1067279041ac88335d7549401e0d593c7aae51e3ed390eda4787face5f94502c516dc19a9bebda236c84d5d21d7ebb0a377af1ff25ff13a9a1c09181d6bbfd89b5a85fc285ee5360450761f781b40f189e301fac7f80f
- Log in as an admin using the
-
Set the HOST environment variable. To get the value, run the following command:
oc get route -n ibm-common-services
Set the HOST to the cp-console route. For example,
export HOST=<cp-console>
. -
Set CPHOST to the cpd route with corresponding service name,
ibm-nginx-svc
. For example,CPHOST=cpd-cp4i.apps.bunny.cp.abc.ibm.com
.
-
-
Get the IBM CloudPak access token for the admin user by using the following command:
curl -ki -X GET 'https://'$CPHOST'/v1/preauth/validateAuth' --header 'username: admin' --header "iam-token: $TOKEN"
-
Create a user group with the role that you want to assign to the user.
curl -k -s -X POST 'https://'$CPHOST'/usermgmt/v2/groups' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header "Authorization: Bearer $CPTOKEN" \ -d '{"name": "isv group", "description": "Group default ISV group", "role_identifiers": ["zen_user_role"] }'
Note: To create an admin group, in "role_identifiers", specify the “zen_administrator_role”.
Verify whether the group is listed, and get the group ID:
curl -k -s -X GET 'https://'$CPHOST'/usermgmt/v2/groups' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header "Authorization: Bearer $CPTOKEN"
-
Add the
isv
group into the user groups:curl -k -s -X POST 'https://'$CPHOST'/usermgmt/v2/groups/<group_ID>/members' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header "Authorization: Bearer $CPTOKEN" \ -d '{ "ldap_groups": ["admin"] }'
Where, the group_ID is the
isv
group ID that you got in Step 3.The configuration is completed.
-
Verify whether the user who is a member of the
isv
group can log in to CloudPak Platform with proper permissions. To verify, open the CloudPak Platform in your browser by using the URL of $CPHOST.