How do I troubleshoot SAML 2.0 authentication issues in WorkSpaces?

Resolution

Prerequisite: Before you troubleshoot SAML 2.0 authentication issues, make sure that no Service Control Policies (SCPs) are blocking the WorkSpaces:Stream API. For information about how to troubleshoot SCP issues, see Access denied due to a Service Control Policy - implicit denial.

To troubleshoot SAML 2.0 authentication issues, review the troubleshooting steps for error message that you receive:

• My users receive the message, "Something went wrong: An error occurred while launching your WorkSpace" when they attempt to sign in to the WorkSpaces client application after federating to the Identity provider (IdP).
• My users receive the message, "Unable to validate tags" when they attempt to sign in to the WorkSpaces client application after federating to the IdP.
• My users are getting disconnected from their WorkSpaces session every 60 minutes.
• Error: Your request included an invalid SAML response. To logout, click here.
• Error: Not authorized to perform sts:AssumeRoleWithSAML (service: AWSSecurityTokenService; status code: 403; error code: AccessDenied).

If you complete the preceding troubleshooting steps and still encounter authentication issues, then complete the following steps.

Verify your IAM policy

Check that the AWS Identity and Access Management (IAM) role that you use for SAML 2.0 authentication has the required permissions.

Complete the following steps:

1. Open the IAM console.
2. Choose the IAM Role tab.
3. Select the IAM role that you use for SAML 2.0 authentication.
4. Choose Trust relationships, and then check your trust relationship policy configurations:
   Verify that the AWS account information for Principal is accurate.
   Make sure that the policy includes the sts:AssumeRoleWithSAML and sts:TagSession actions.
   Make sure that under Attribute, the value for SAML:sub_type is persistent.
   Example:

   {
       "Version": "2012-10-17",
       "Statement": [{
           "Effect": "Allow",
           "Principal": {
               "Federated": "arn:aws:iam::ACCOUNT-ID:saml-provider/IDENTITY-PROVIDER"
           },
           "Action": [
               "sts:AssumeRoleWithSAML",
               "sts:TagSession"
           ],
           "Condition": {
               "StringEquals": {
                   "SAML:aud": "https://signin.aws.amazon.com/saml"
               }
           }
       }]
   }    

   Note: Replace ACCOUNT-ID with your account ID, and IDENTITY-PROVIDER with your IdP.
5. Choose Permissions, and then verify that your policy has the workspaces:Stream action.
   Example:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "workspaces:Stream",
               "Resource": "arn:aws:workspaces:REGION-CODE:ACCOUNT-ID:directory/DIRECTORY-ID",
               "Condition": {
                   "StringEquals": {
                       "workspaces:userId": "${saml:sub}"
                   }
               }
           }
       ]
   }

   Note: Replace REGION-CODE with your AWS Region, ACCOUNT-ID with your account ID, and DIRECTORY-ID with your directory.

Get the SAML 2.0 response from the browser

View the SAML 2.0 response in your browser.

Analyze your SAML 2.0 response

Check the NameID

The NameID element must have the persistent value.

Example:

<saml2:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">workspaceUsername</saml2:NameID>

Note: Replace workspaceUsername with your WorkSpaces username.

Also, make sure that workspaceUsername matches the samaccountname value in your Active Directory.

Check the Role attribute

The Role attribute format must start with the ARN of the associated IAM role, then a comma, and finally the ARN of the IdP.

Example:

<saml2:Attribute Name="https://aws.amazon.com/SAML/Attributes/Role"
                      NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
                      >
         <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                               xsi:type="xs:string"
                               >arn:aws:iam::123456789123:role/SAML_Role,arn:aws:iam::123456789123:saml-provider/SAMLIDP</saml2:AttributeValue>
 </saml2:Attribute>

Note: Replace arn:aws:iam::123456789123:role/SAML_Role with the IAM role ARN and arn:aws:iam::123456789123:saml-provider/SAMLIDP with the IdP ARN.

Check the RoleSessionName attribute

The RoleSessionName value must be an email address or a user principal name (UPN).

Example:

<saml2:Attribute Name="https://aws.amazon.com/SAML/Attributes/RoleSessionName"
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
                >
      <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                            xsi:type="xs:string"
                            >workspaceUsername@example.local</saml2:AttributeValue>

Note: Replace workspaceUsername@example.local with your user's email address.

If RoleSessionName is an email address, then the email address must match the user's Active Directory email.

To verify the email address, complete the following steps:

1. Log in to the domain controller or member server that manages your Active Directory.
2. Choose Active Directory Users and Computers.
3. Select the user.
4. Open the context (right-click) menu for Properties.
5. Choose the General tab. The user's email address is listed as the value for E-mail.

The RoleSessionName value must contain only valid characters and be within the expected character count. Also, verify that the attribute type, syntax, formatting, and spelling are accurate.

Check the PrincipalTag:Email attribute

The PrincipalTag:Email value must match the user's email address in Active Directory.

Example:

<saml2:Attribute Name="https://aws.amazon.com/SAML/Attributes/PrincipalTag:Email"
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
                >
<saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                      xsi:type="xs:string"
                      >workspaceUsername@example.local</saml2:AttributeValue>
</saml2:Attribute>

Note: Replace workspaceUsername@example.local with your user's email address.

If any of the preceding attributes have different or incorrect values, then update your SAML 2.0 IdP configuration.

Relation information

Troubleshoot SAML federation with IAM

Troubleshoot specific issues