Example: Configuring single sign-on between KeyCloak and Cloud SSO

Background

Assume your organization uses a local directory service (based on the LDAP protocol) to manage users and has set up a multi-account architecture in Alibaba Cloud Resource Directory (RD). You will configure Keycloak to allow users from your local directory service to use SSO to access specific resources in designated member accounts within your resource directory.

Before you configure SSO, set up the Keycloak service on a server and synchronize users from your local directory service to Keycloak. This example uses the official Keycloak Docker image.

Step 1: Obtain SP metadata

1. Log on to the Cloud SSO console.

2. In the left-side navigation pane, click Settings.

3. In the SSO Login section, copy the ACS URL and Entity ID of the service provider (SP), or download the SP metadata file.

Step 2: Create a realm in Keycloak

1. Log on to the Keycloak service and go to the Admin Console.

2. In the left-side navigation pane, select Manage realms.

3. On the Manage realms page, click Create realms.

Step 3: Create a client in Keycloak

1. In the left-side navigation pane, select Manage > Clients.

2. On the Clients page, click Import Client.

3. Import the Cloud SSO metadata file from Step 1 to create a client. Keycloak automatically parses the information.

   On the Clients page, click Import client. In the Resource file section, upload the metadata XML file. Keycloak automatically parses the file, populates the Client ID with the Cloud SSO login URL, sets Type to saml, and sets both Encrypt assertions and Client signature required to Off.

4. Click Save.

5. On the Clients page, select the new client to open its Client Details page. On the Settings tab, scroll to the SAML capability section and set Name ID format to username.

Step 4: Obtain IdP metadata

1. In the left-side navigation pane, select Realm Setting.

2. On the General tab, scroll to the bottom of the page and download the SAML 2.0 Identity Provider Metadata file.

Step 5: Enable SSO login in Cloud SSO

1. In the left-side navigation pane of the Cloud SSO console, click Settings.

2. In the SSO Login section, click Configure Identity Provider Information.

3. In the Configure Identity Provider Information dialog box, select Upload Metadata Document.

4. Click Upload File and upload the IdP metadata file from Step 4.

5. Turn on the SSO login switch.

   After you enable SSO login, the page displays the Service Provider (SP) Information (including ACS URL, Entity ID, and a link to Download SP Metadata Document) and the Identity Provider (IdP) Information (including Entity ID, Login URL, and SAML Signing Certificate). You can click Configure Identity Provider Information or Clear Identity Provider Information to manage the settings.

Step 6: Create users in Cloud SSO

If you have not already done so, create users in Cloud SSO with the same usernames as in Keycloak. The username in Cloud SSO must exactly match the username in Keycloak for SSO to work. For more information, see Basic operations.

(Optional) Step 7: Grant permissions to users

To allow users to access specific resources in designated member accounts after SSO login, create an access configuration and grant permissions to the users on the accounts in your resource directory.

1. Create an access configuration in Cloud SSO to define a permission policy.

   For more information, see Create an access configuration.

2. Grant permissions to the users on the RD accounts.

   For more information, see Grant permissions on an RD account.

Verify the results

After completing the configuration, initiate an SSO login from either Alibaba Cloud or Keycloak.

• Initiate SSO login from Alibaba Cloud

  1. On the Overview page of the Cloud SSO console, copy the user login URL.

  2. Open the user login URL in a new browser window.

  3. Click Redirect. You are redirected to the Keycloak login page.

  4. Log in with your Keycloak username and password. You are logged in through SSO and redirected to the page specified as the Default RelayState. If no Default RelayState is specified, you are redirected to the Cloud SSO user portal.

• Initiate SSO login from Keycloak

  1. In the left-side navigation pane of the Keycloak console, click Clients and select the SAML client you created.

  2. On the Settings tab, scroll to the Access Settings section and enter a name in the IDP-Initiated SSO URL name field. Confirm that the Valid redirect URIs field contains the Cloud SSO callback URL. To view the URL format, click the help icon next to IDP-Initiated SSO URL name. The IdP-initiated SSO URL uses the following format:

     {server-root}/realms/{realm}/protocol/saml/clients/{client-url-name}.

  3. Open the URL in a new browser window and log in with your Keycloak username and password. You are logged in through SSO and redirected to the page specified as the Default RelayState. If no Default RelayState is specified, you are redirected to the Cloud SSO user portal.