How do I troubleshoot SAML 2.0 authentication issues in WorkSpaces?

Resolution

If you try to use SAML 2.0 authentication to login to WorkSpaces, then you might get one of the following error messages:

"Your request included an invalid SAML response"

"Something went wrong"

"Not authorized to perform sts:AssumeRoleWithSAML".

Prerequisite: Make sure that Service Control Policies (SCPs) don't block 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, see Troubleshoot specific issues.

If you still encounter authentication issues, then take the following actions.

Verify your IAM policy

Check that you assigned the AWS Identity and Access Management (IAM) role that you use for SAML 2.0 authentication 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. On the Permissions tab, confirm 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 AWS account ID, and DIRECTORY-ID with your directory.

5. Choose the Trust relationships tab, and then check your trust relationship policy configurations:
   Confirm that you speficied the correct account information for Principal.
   Make sure that the policy includes the sts:AssumeRoleWithSAML and sts:TagSession actions.
   Make sure that under Condition, 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:sub_type": "persistent" 
              }  
          }  
      }]  
   } 

   Note: Replace ACCOUNT-ID with your account ID, and IDENTITY-PROVIDER with your identity provider (IdP).

Review your SAML 2.0 response

View the SAML 2.0 response in your browser.

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 Amazon Resource Name (ARN) of the associated IAM role, followed by a comma, and end with 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 address.

To verify the Active Directory 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 menu for Properties.
5. Choose the General tab, and find the value for E-mail.

The RoleSessionName value must contain only valid characters and be within the expected character count. Confirm 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.

Related information

Troubleshoot SAML federation with IAM