This topic provides an example of how to implement role-based Single Sign On (SSO) from AD FS to Alibaba Cloud, detailing the end-to-end identity SSO process from an enterprise identity provider (IdP) to Alibaba Cloud.

Scenario

You use Active Directory (AD) to manage your users and use AD FS to configure enterprise applications such as Alibaba Cloud. Your AD administrator manages the access permissions on Alibaba Cloud accounts according to users' AD groups. In this example, you have two Alibaba Cloud accounts (Account1 and Account2), and the permissions managed by your AD administrator are Admin and Reader. You have a user named Alice. The AD groups of Alice are Aliyun-<account-id>-ADFS-Admin and Aliyun-<account-id>-ADFS-Reader. You want to implement SSO from AD FS to Account1 and Account2.
Note In the preceding groups, <account-id> is the account ID of Account1 or Account2. Therefore, Alice belongs to four AD groups, which correspond to the Admin and Reader permissions respectively.
The following figure shows the basic SSO process through the console.
Console logon process

After the AD administrator has completed role-based SSO configurations, Alice can log on to the Alibaba Cloud console by following the steps in the preceding figure. For more information, see Role-based SSO overview.

The preceding SSO process shows that users of an enterprise can be authenticated with no need to provide Alibaba Cloud usernames and passwords during logon.

Configurations

To implement role-based SSO, the administrator must configure Alibaba Cloud and AD FS by following these steps:

  • Configure AD FS as a trusted SAML IdP in Alibaba Cloud:
    1. Create an IdP named ADFS under Account1 in the Alibaba Cloud RAM console, and configure the corresponding metadata file. The metadata file of your AD FS can be obtained from https://<ADFS-server>/federationmetadata/2007-06/federationmetadata.xml.
      Note In the preceding URL, <ADFS-server> is the server domain name or IP address of your AD FS.

      For more information, see Configure the SAML for role-based SSO.

    2. Create two RAM roles named ADFS-Admin and ADFS-Reader under Account1, select ADFS you have created as the trusted entity, and attach the AdministratorAccess and ReadOnlyAccess policies to these two RAM roles respectively. For more information, see RAM role management.
    3. Create an IdP and two RAM roles under Account2 as described in the preceding steps, and attach policies to these two RAM roles.
    Note After the configurations are completed, your Alibaba Cloud accounts (Account1 and Account2) will trust the user identity and role information in the SAML requests sent from your AD FS.
  • Configure Alibaba Cloud as a trusted SAML SP in AD FS.

    In AD FS, SAML SP is also known as a relying party. To set Alibaba Cloud as a trusted SAML SP in AD FS, follow these steps:

    1. On the Server Manager page, choose Tools > AD FS Management.
    2. Select Add Relying Party Trust.
      Add relying party trust wizard
    3. Set the SAML SP metadata of Alibaba Cloud for the relying party. The metadata URL is https://signin.alibabacloud.com/saml-role/sp-metadata.xml.
      Add relying party trust wizard
    4. Complete the configurations as prompted.
  • Configure the SAML assertion attributes for the Alibaba Cloud SP.

    The SAML assertion issued by your AD FS must contain the attributes such as NameID, Role, and RoleSessionName. Your AD FS can provide these attributes by issuing transform rules.

    • NameID

      Follow these steps to configure the Windows account name of AD to be the NameID in the SAML assertion:

      1. Right-click the display name of the relying party and select Edit Claim Rules.
      2. Click Issuance Transform Rules.
        Note Issuance Transform Rules indicates how to transform a known user attribute and issue it as an attribute in the SAML assertion. You must issue the Windows account name of a user in AD as a NameID. This means that a new rule is required.
      3. Select Transform an Incoming Claim from the Claim rule template drop-down list.
        Add transform claim rule wizard
      4. Configure the claim rule as follows, and click Finish.
        • Claim rule name: NameID
        • Incoming claim type: Windows account name
        • Outgoing claim type: Name ID
        • Outgoing name ID format: Persistent Identifier
        • Pass through all claim values: Selected

        Add transform claim rule wizard
        After the configurations are completed, AD FS will send the required NameID format to Alibaba Cloud. The following is an example:
        
        <NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">
            YourDomain\rolessouser
        </NameID>
        
    • RoleSessionName

      Follow these steps to configure the UPN of AD to the RoleSessionName in the SAML assertion:

      1. Click Add Transform Claim Rule.
      2. Select Send LDAP Attributes as Claims from the Claim rule template drop-down list.
        Add transform claim rule wizard
      3. Configure the claim rule as follows, and click Finish.
        • Claim rule name: RoleSessionName
        • Attribute store: Active Directory
        • LDAP Attribute: User-Principal-Name (You can select other attributes, such as Email, as needed.)
        • Outgoing Claim Type: https://www.aliyun.com/SAML-Role/Attributes/RoleSessionName

        Add transform claim rule wizard
      After the configurations are completed, AD FS will send the required RoleSessionName format to Alibaba Cloud. The following is an example:
      
      <Attribute Name="https://www.aliyun.com/SAML-Role/Attributes/RoleSessionName">
          <AttributeValue>rolessouser@example.com<AttributeValue>
      </Attribute>
      
    • Role

      Follow these steps to transform the user's AD group membership into the role name of Alibaba Cloud by using custom rules:

      1. Click Add Transform Claim Rule.
      2. Select Send Claims Using a Custom Rule from the Claim rule template drop-down list and click Next.
        Add transform claim rule wizard
      3. Configure the claim rule as follows, and click Finish.
        • Claim rule name: Get AD Groups
        • Custom rule:
          
          c:[Type ==
          "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccount
          name", Issuer == "AD AUTHORITY"] => add(store = "Active Directory",
          types = ("http://temp/variable"), query = ";tokenGroups;{0}", param =
          c.Value);

        Add transform claim rule wizard
        Note This rule is used to obtain the user's AD group membership and save it to http://temp/variable.
      4. Click Add Transform Claim Rule.
      5. Repeat the preceding steps and click Finish.
        • Claim rule name: Role
        • Custom rule:
          
          c:[Type == "http://temp/variable", Value =~ "(?i)^Aliyun-([\d]+)"]
           => issue(Type = "https://www.aliyun.com/SAML-Role/Attributes/Role",
          Value = RegExReplace(c.Value, "Aliyun-([\d]+)-(.+)", "acs:ram::
          $1:role/$2,acs:ram::$1:saml-provider/ADFS"));

        Add transform claim rule wizard
        Note According to this rule, if the user's AD group contains Aliyun-<account-id>-ADFS-Admin or Aliyun-<account-id>-ADFS-Reader, an SAML attribute will be generated and sent to Alibaba Cloud to match the RAM role ADFS-Admin or ADFS-Reader.
      After the configurations are completed, your IdP will return a required SAML assertion to Alibaba Cloud. The following is an example:
      
      <Attribute Name="https://www.aliyun.com/SAML-Role/Attributes/Role">
          <AttributeValue>acs:ram::<account-id>:role/ADFS-Admin,acs:ram::<account-id>:saml-provider/ADFS</AttributeValue>
      </Attribute>
      

Verification

    1. Log on to the AD FS SSO portal (URL: https://<ADFS-server>/adfs/ls/IdpInitiatedSignOn.aspx), select Alibaba Cloud application, and enter the username and password.
      Note In the preceding URL, <ADFS-server> is the server domain name or IP address of your AD FS. If the URL does not work, run the PowerShell Set-AdfsProperties –EnableIdpInitiatedSignonPage $True.

      AD FS SSO portal
    2. On the Alibaba Cloud role-based SSO page, select the target role and click Sign In.
      Note If your user belongs to only one AD group, the user can log on to Alibaba Cloud with no need of selecting a role.

      Alibaba Cloud role-based SSO page