Example of role-based SSO with Microsoft Entra ID

Prerequisites

• You have a RAM administrator with the AliyunRAMFullAccess permission for operations in the RAM console. For information about how to create a RAM user and grant permissions, see Create a RAM user and Manage RAM user permissions.

• You have a Microsoft Entra ID administrator with the Global Administrator role for operations in Microsoft Entra ID. For information about how to create a user and grant permissions in Microsoft Entra ID, see the Microsoft Entra ID documentation.

Configuration process

This configuration establishes a trust relationship between the IdP and the SP, and maps application roles in Microsoft Entra ID to RAM roles in Alibaba Cloud.

1. Step 1: Create an enterprise application in Microsoft Entra ID. Create an enterprise application from the Microsoft Entra ID application gallery by using the Alibaba Cloud Service (Role-based SSO) application template.

2. Step 2: Configure SAML in Microsoft Entra ID. Configure Alibaba Cloud role-based SSO as a trusted SAML service provider.

3. Step 3: Create an identity provider in Alibaba Cloud. Configure Microsoft Entra ID as a trusted SAML IdP in Alibaba Cloud RAM.

4. Step 4: Create a RAM role in Alibaba Cloud. Create a RAM role in Alibaba Cloud RAM and set its principal type to IdP.

5. Step 5: Create an app role and assign users in Microsoft Entra ID. Create and configure an app role for the Alibaba Cloud role-based SSO application in Microsoft Entra ID, and assign a test user to the enterprise application.

6. Verify the SSO logon. Verify that the role-based SSO logon works as expected.

Step 1: Create an enterprise application in Microsoft Entra ID

1. Log on to the Azure portal as a Microsoft Entra ID global administrator.

2. In the upper-left corner of the page, click the icon.

3. In the left-side navigation pane, choose Microsoft Entra ID > Manage > Enterprise applications > All applications.

4. Click New application.

5. Search for and select Alibaba Cloud Service (Role-based SSO).

6. Enter a name for the application and click Create.

   This example uses the default application name Alibaba Cloud Service (Role-based SSO). You can also specify a custom name.

Step 2: Configure SAML in Microsoft Entra ID

1. On the Alibaba Cloud Service (Role-based SSO) page, in the left-side navigation pane, choose Manage > Single sign-on.

2. Click SAML.

3. Configure SSO information.

   1. In the upper-left corner of the page, click Upload metadata file, select the metadata file for Alibaba Cloud role-based SSO, and then click Add.

      Note

      To obtain the metadata file, open https://signin.aliyun.com/saml-role/sp-metadata.xml in a new browser window and save the federation metadata XML file to your computer.

   2. On the Basic SAML Configuration page, configure the following information, and then click Save.

      • identifier (entity ID): This value is automatically populated from the entityID attribute in the metadata file.

      • reply URL (assertion consumer service URL): This value is automatically populated from the Location attribute in the metadata file.

      • relay state: This optional parameter specifies the Alibaba Cloud page where users land after a successful role-based SSO logon.

        Note

        For security reasons, you can only enter a URL for an Alibaba-owned domain as the value of relay state, such as *.aliyun.com, *.hichina.com, *.yunos.com, *.taobao.com, *.tmall.com, *.alibabacloud.com, or *.alipay.com. Otherwise, the configuration is invalid. If you do not configure this parameter, users are redirected to the Alibaba Cloud console homepage by default.

   3. In the Attributes & Claims section, click the icon and verify that the following two claims exist.

      If these claims are missing, click Add new claim and add them as described in the following table.

      Name	Namespace	Source	Source attribute
      Role	https://www.aliyun.com/SAML-Role/Attributes	Attribute	user.assignedroles
      RoleSessionName	https://www.aliyun.com/SAML-Role/Attributes	Attribute	user.userprincipalname

   4. In the SAML Certificates section, find Federation Metadata XML and click Download.

Step 3: Create an identity provider in Alibaba Cloud

1. Log on to the RAM console as a RAM administrator.

2. In the left-side navigation pane, choose Integrations > SSO.

3. On the Role-based SSO tab, click the SAML tab, and then click Create IdP.

4. On the Create IdP page, enter AAD for IdP Name.

5. Click Upload Metadata File and upload the federation metadata XML file that you downloaded in Step 2: Configure SAML in Microsoft Entra ID.

6. Click Create IdP.

7. Click the AAD identity provider that you created. In the Basic Information section, find and copy the identity provider ARN.

Step 4: Create a RAM role in Alibaba Cloud

1. In the left-side navigation pane of the RAM console, choose Identities > Roles.

2. On the Roles page, click Create Role.

3. In the upper-right corner of the Create Role page, click Switch to Policy Editor.

4. Specify the SAML identity provider in the editor.

   The editor supports a visual editor and a script editor. You can use either one. This example uses the visual editor. For Principal, select IdP and click Edit. Then, specify AAD as the identity provider and select SAML for IdP Type.

5. In the Create Role dialog box, enter a Role Name, such as AADrole, and then click OK to create the role.

6. Click the RAM role that you created. In the Basic Information section, find and copy the role ARN.

Step 5: Create app roles and assign users

1. Create an app role in Microsoft Entra ID.

   1. Log on to the Azure portal as an administrator.

   2. In the left-side navigation pane, choose Microsoft Entra ID > Manage > App registrations.

   3. Click the All applications tab, and then click Alibaba Cloud Service (Role-based SSO).

   4. In the left-side navigation pane, choose Manage > App roles.

   5. Click Create app role.

   6. On the Create app role page, configure the following role information, and then click Application.

      • Display Name: In this example, enter Admin.

      • Allowed member types: In this example, select Users/groups.

      • Value: Enter the RAM role ARN and the identity provider ARN, separated by a comma (,). For example, enter acs:ram::187125022722****:role/aadrole,acs:ram::187125022722****:saml-provider/AAD.

        Note

        The value must be in the format RAM role ARN,identity provider ARN. If the order is incorrect, the SSO logon will fail.

      • Description: Enter a description for the role.

      • Select Do you want to enable this app role?.

   Note

   If you need to create multiple app roles in Microsoft Entra ID, repeat the preceding steps and set different display names and application role values.

2. Assign a user to the enterprise application and specify an app role.

   1. In the left-side navigation pane, choose Microsoft Entra ID > Manage > Enterprise applications > All applications.

   2. In the Name list, click Alibaba Cloud Service (Role-based SSO).

   3. In the left-side navigation pane, choose Manage > Users and groups.

   4. In the upper-left corner, click Add user/group.

   5. On the Add Assignment page, select the target user, and then click Select.

   6. Ensure that the selected role is Admin, and then click Assignments.

      Note

      In a production environment, it is a best practice to add users to groups in Microsoft Entra ID and then assign the groups to the enterprise application.

      If you have multiple roles, you can associate different user groups with different roles, such as associating an ecs-admin group with an ecs-admin role and an oss-admin group with an oss-admin role. This practice enables finer-grained access control and more efficient user management.

Verify the SSO logon

Role-based SSO supports only IdP-initiated SSO. You must initiate the logon from Microsoft Entra ID to verify the configuration.

1. Obtain the user access URL.

   1. Log on to the Azure portal as an administrator.

   2. In the left-side navigation pane, choose Microsoft Entra ID > Manage > Enterprise applications > All applications.

   3. In the Name list, click Alibaba Cloud Service (Role-based SSO).

   4. In the left-side navigation pane, choose Manage > Properties and obtain the User access URL.

2. As the user (ssotest01@example.onmicrosoft.com), open the User access URL in a browser and log on with your account. After a successful logon, the user is redirected to the Alibaba Cloud console by default. The RAM role that you defined (aadrole) appears before the account name.

   You are automatically logged on through SSO and redirected to the page specified for relay state. If relay state is not specified or its value is out of the allowed scope, the system redirects you to the Alibaba Cloud console homepage.

Advanced: Configure SSO for multiple Alibaba Cloud accounts

Assume that you have two Alibaba Cloud accounts (Account1 and Account2). You want to configure SSO so that an employee (ssotest01@example.onmicrosoft.com) can log on to Microsoft Entra ID and use role-based SSO to access both Account1 and Account2.

1. Add the Alibaba Cloud Service (Role-based SSO) application from the Microsoft Entra ID gallery.

   For more information, see Step 1: Create an enterprise application in Microsoft Entra ID.

2. Configure Microsoft Entra ID SSO.

   For more information, see Step 2: Configure SAML in Microsoft Entra ID.

3. Create identity providers in Alibaba Cloud.

   You must create an IdP named AAD in each of the two Alibaba Cloud accounts (Account1 and Account2).

   For the specific operations in each Alibaba Cloud account, see Step 3: Create an identity provider in Alibaba Cloud.

4. Create RAM roles in Alibaba Cloud.

   You must create RAM roles in each of the two Alibaba Cloud accounts. For this example, assume that you create two RAM roles in Account1 and one RAM role in Account2. The details are as follows:

   • RAM roles for Account1: adminaad and readaad.

   • RAM role for Account2: financeaad.

   For the specific operations in each Alibaba Cloud account, see Step 4: Create a RAM role in Alibaba Cloud.

5. Associate the Alibaba Cloud RAM roles with the Microsoft Entra ID user.

   In Microsoft Entra ID, create three application roles and assign them to the user (ssotest01@example.onmicrosoft.com). The values for the three roles are as follows:

   • acs:ram::<Account1_ID>:role/adminaad,acs:ram::<Account1_ID>:saml-provider/AAD

   • acs:ram::<Account1_ID>:role/readaad,acs:ram::<Account1_ID>:saml-provider/AAD

   • acs:ram::<Account2_ID>:role/financeaad,acs:ram::<Account2_ID>:saml-provider/AAD

   For more information, see Step 5: Create an app role and assign users in Microsoft Entra ID.

6. Access Alibaba Cloud by using role-based SSO as a Microsoft Entra ID user.

   The user (ssotest01@example.onmicrosoft.com) logs on to the Azure My Apps portal and clicks the Alibaba Cloud Service (Role-based SSO) application. On the Alibaba Cloud page, you are prompted to select an Alibaba Cloud account (Account1 or Account2) and a role to assume to access Alibaba Cloud by using role-based SSO.

Troubleshooting

See Single sign-on (SSO) FAQ.