Single sign-on (SSO) FAQ

Cause

Resolution

Alibaba Cloud uses the User Principal Name (UPN) to locate a RAM user, so the SAML response from your identity provider (IdP) must contain the user's UPN. The UPN suffix can be a domain alias, auxiliary domain name, or default domain name. If the username suffix in your IdP does not match the RAM user's UPN suffix, matching fails. Check the NameID element and NameID example sections in SAML response for user-based SSO.

Set an auxiliary domain name so the RAM user's UPN suffix matches the one in your IdP. Configure SAML settings for user-based SSO on Alibaba Cloud.

The RAM user does not exist, or the RAM user's name does not match the corresponding username in the IdP.

• Change the RAM username to match the username in the IdP.

• RAM usernames allow up to 64 characters: letters, numbers, and -_.. If the IdP username does not meet these requirements, try one of the following:

  • Modify the username in your IdP to meet the RAM character requirements.

  • Change the unique identifier field in your IdP's SSO configuration to one that meets RAM requirements, such as an email address.

  • Set up a transformation rule for username mapping in your IdP's SSO configuration.

SCIM user synchronization has failed.

Check the SCIM synchronization logs in your IdP to identify and fix the failure.

The UPN for a user in the IdP does not match the UPN synchronized to RAM. Possible causes include:

• The username synchronized to RAM by using SCIM is not the user's UPN.

• A transformation rule for username mapping is configured for SCIM synchronization.

Ensure the username mapping rule in your IdP's SSO configuration matches the one configured for SCIM synchronization.

The value of the Audience element in the SAML response is incorrect, often because the accountId is wrong.

In the SAML response, find the AudienceRestriction element in Conditions. Verify that Audience is set to https://signin.aliyun.com/${accountId}/saml/SSO, where ${accountId} is your Alibaba Cloud account ID.

If your IdP has a separate Audience URL setting, ensure it is configured correctly.

Cause

Resolution

In the AttributeStatement element, the attribute where Attribute Name is https://www.aliyun.com/SAML-Role/Attributes/Role combines the RAM role and IdP names. This error occurs if the RAM role or IdP does not exist in Alibaba Cloud, or if the IdP in the RAM role's trust policy does not match the IdP name in the attribute value. SAML response for role-based SSO.

• Ensure the RAM role name and IdP name match those in the SAML response. Configure SAML settings for role-based SSO on Alibaba Cloud and Configure SAML settings for role-based SSO in your IdP.

• Ensure the IdP name in the RAM role's trust policy matches an existing IdP. Example 3: Change the trusted entity of a RAM role to an identity provider.

Cause

Resolution

The Attribute element, where the Name attribute is set to https://www.aliyun.com/SAML-Role/Attributes/Role, is either missing or incorrectly configured in your IdP.

Fix the Attribute configuration in your IdP. SAML response for role-based SSO.

Cause

Resolution

The Attribute element, where the Name attribute is set to https://www.aliyun.com/SAML-Role/Attributes/RoleSessionName, is incorrectly configured in your IdP.

Fix the Attribute element in your IdP. Verify the Attribute value is 2 to 64 characters and contains only letters, numbers, and -_.@=. SAML response for role-based SSO.

The user signing in has no value for the attribute mapped to RoleSessionName. For example, if your IdP uses Email as RoleSessionName, this error occurs when the user has no email address in the IdP.

Identify the attribute specified for RoleSessionName in your IdP and set the attribute value for the user.

Cause

Resolution

The public-private key pair used for signing in your IdP has been rotated, but the IdP metadata in Alibaba Cloud has not been updated.

Update the IdP metadata in Alibaba Cloud. Download the latest metadata file from your IdP and re-upload it.

The public-private key pair in your IdP has been rotated and the IdP metadata in Alibaba Cloud has been updated. However, the IdP might still use the old private key during the rotation period, while the metadata in Alibaba Cloud contains only the new public key.

The IdP metadata in Alibaba Cloud must contain both the old and new public keys. To configure metadata with two public keys:

• Create a new certificate. Do not disable or delete the old certificate.

• Download the new metadata file and check whether it contains both old and new certificate public keys.

  • Some IdPs, such as Azure AD, automatically include both certificates in the metadata file.

  • If the metadata file does not include both public keys, manually add the old certificate. Download the old metadata file from the SSO configuration in RAM, copy the X509Certificate from the KeyDescriptor section, and paste it into the new metadata file.

  • Upload the new metadata file to the SSO configuration in RAM.

  • In your IdP's SSO configuration, activate the new certificate and deactivate the old one.

The upload failed because the metadata file is too large.

After uploading, wait for the process to complete. Download the metadata file to verify the upload was successful and the content is complete.

Cause

Resolution

The metadata parameters do not conform to the SAML 2.0 protocol.

Configure the parameters to conform to the SAML 2.0 protocol. SAML 2.0.