This topic provides an example of how to implement role-based single sign-on (SSO) to Alibaba Cloud from Active Directory Federation Services (AD FS). It describes the end-to-end SSO process from a cloud identity provider (IdP) to Alibaba Cloud.
Background information
You can use AD FS to manage your users and configure enterprise applications such as Alibaba Cloud. After role-based SSO is configured, your AD administrators can manage user access to Alibaba Cloud. In this example, you have two Alibaba Cloud accounts (Account1 and Account2) and four AD user groups (Aliyun-<account-id>-ADFS-Admin and Aliyun-<account-id>-ADFS-Reader). An employee's AD user account named Alice belongs to these groups. You want to implement role-based SSO from AD FS to Account1 and Account2.
SSO process
The following figure shows the process of role-based SSO.

After an AD administrator completes the configurations of role-based SSO, Alice can log on to the Alibaba Cloud console by following the process shown in the figure. For more information, see Overview of role-based SSO.
The SSO process shows that users can be authenticated without the need to provide Alibaba Cloud usernames and passwords during logon.
Configure AD FS as a trusted SAML IdP in Alibaba Cloud
Configure Alibaba Cloud as a trusted SAML SP in AD FS
In AD FS, a SAML service provider (SP) is also known as a relying party. To configure Alibaba Cloud as a trusted SAML SP in AD FS, follow these steps:
Configure SAML assertion attributes for the Alibaba Cloud SP
The SAML assertion issued by AD FS must contain the attributes such as NameID
, Role
, and RoleSessionName
. AD FS can provide these attributes by issuing transform rules.
NameID
Follow these steps to configure the
NameID
attribute in the SAML assertion to contain the Windows account name of AD:- Right-click the display name of the relying party and select Edit Claim Rules.
- Click Issuance Transform Rules.
Note Issuance transform rules indicate how to transform a known user attribute and issue it as an attribute in the SAML assertion. You need to issue the Windows account name of a user in AD as
NameID
. This means that a new rule is required. - Select Transform an Incoming Claim from the Claim rule template drop-down list.
- Configure the claim rule as follows, and then click Finish.
- Specify the Claim rule name parameter as NameID.
- Select Windows account name for the Incoming claim type parameter.
- Select Name ID for the Outgoing claim type parameter.
- Select Persistent Identifier for the Outgoing name ID format parameter.
- Select the Pass through all claim values option.
After you complete the configurations, AD FS will send the required
NameID
attribute 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 value of the
RoleSessionName
attribute in the SAML assertion to be the User Principal Name (UPN) of AD:- Click Add Transform Claim Rule.
- Select Send LDAP Attributes as Claims from the Claim rule template drop-down list.
- Configure the claim rule as follows, and click Finish.
- Specify the Claim rule name parameter as RoleSessionName.
- Select Active Directory from the Attribute store drop-down list.
- Select User-Principal-Name in the LDAP Attribute column. You can select other attributes, such as Email, as needed.
- Select
https://www.aliyun.com/SAML-Role/Attributes/RoleSessionName
in the Outgoing Claim Type column.
After you complete the configurations, AD FS will send the required
RoleSessionName
attribute 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 configure a custom attribute whose value contains the name of the Alibaba Cloud RAM role that is associated with the AD group of the user:
- Click Add Transform Claim Rule.
- Select Send Claims Using a Custom Rule from the Claim rule template drop-down list and click Next.
- Configure the claim rule as follows, and click Finish.
- Specify the Claim rule name parameter as Get AD Groups.
- Specify the Custom rule parameter as follows:
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);
Note This rule is used to obtain the AD group to which the user belongs and save it to http://temp/variable. - Click Add Transform Claim Rule.
- Repeat the preceding steps to create a custom rule, configure the rule as follows,
and then click Finish.
- Specify the Claim rule name parameter as Role.
- Specify the Custom rule parameter as follows:
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"));
Note According to this rule, if the user belongs to the Aliyun-<account-id>-ADFS-Admin or Aliyun-<account-id>-ADFS-Reader group, a SAML attribute will be generated and sent to Alibaba Cloud to match the RAM role ADFS-Admin or ADFS-Reader.
After you complete the configurations, 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>