How do I troubleshoot an "invalid SAML response" error for Okta and AWS IAM Federation?

Short description

When you use the AWS Account Federation in Okta, you might receive an invalid SAML error when logging into AWS. This can happen if you provide missing or incorrect information for the role attribute in a SAML response. The expected value of this attribute is one or more comma-separated pairs of an AWS Identity and Access Management (IAM) role and the SAML provider, as shown here:

<Attribute Name="https://aws.amazon.com/SAML/Attributes/Role">
  <AttributeValue>arn:aws:iam::ACCOUNT_NUMBER:role/ROLE_NAME_1,arn:aws:iam::ACCOUNT_NUMBER:saml-provider/PROVIDER_NAME/AttributeValue>
  <AttributeValue>arn:aws:iam::ACCOUNT_NUMBER:role/ROLE_NAME_2,arn:aws:iam::ACCOUNT_NUMBER:saml-provider/PROVIDER_NAME</AttributeValue>
  <AttributeValue>arn:aws:iam::ACCOUNT_NUMBER:role/ROLE_NAME_3,arn:aws:iam::ACCOUNT_NUMBER:saml-provider/PROVIDER_NAME</AttributeValue>
</Attribute>

To check your SAML response from your browser, follow the steps in How to view a SAML response in your browser for troubleshooting.

Resolution

If you are using the Use Group Mapping setting in Okta, follow the steps under Connect to Okta with multiple AWS accounts. If not, go to Connect to Okta with a single AWS account. 

Connect to Okta with multiple AWS accounts

If you connect to Okta with multiple AWS accounts, then Okta uses group-based role mapping. This means that Okta uses the Group Name to identify the AWS account ID and IAM role name for SSO.

Note: Be sure to enter the Group Filter and Role Value Pattern correctly in Okta to accurately capture the information:

1.    Login to the Okta admin console.

2.    Choose Applications, and then choose Applications again.

3.    Choose Sign On, and then choose Edit.

4.    The Group Filter is a custom Regex expression that captures information like the AWS account ID and IAM role name for your Okta Group name. For more information, see Okta's setup document.

The setup guide gives this example:

Group name: "aws#[account alias]#[role name]#[account #]" 
Group Filter: "^aws\#\S+\#(?{{role}}[\w\-]+)\#(?{{accountid}}\d+)$"

You can extend this example if you want to customize the Group Name. See these examples of Group Names and Group Filters:

Group Name: [account alias]|[role name]|[account #] 
Group Filter: ^\S+\|(?{{role}}[a-zA-Z0-9+=.@\-_]+)\|(?{{accountid}}\d+)$

Group Name: aws_[account #]_[role name] 
Group Filter: ^aws\_(?{{accountid}}\d+)\_(?{{role}}[a-zA-Z0-9+=.@\-_]+)$

Note:

• The IAM role name allows alphanumeric and '+=,.@-_' characters. Consider using delimiters that are not part of your Role Name (e.g. '#' or '|') if you get an error caused by the group filter.
• Your IAM role name should not contain ',' if you want to login using IAM Federation. This is because the Role Value Pattern shown below uses a comma to separate the SAML provider and role name. Create a new IAM role without a comma in the name to use with IAM Federation.

5.    The Role Value pattern must contain the ARN of the IAM role and SAML provider, separated by a comma. Replace the SAML Provider Name in this example with the Provider name of the Okta instance. You can find this information in AWS IAM console, under Identity providers.

arn:aws:iam::${accountid}:saml-provider/[SAML Provider Name],arn:aws:iam::${accountid}:role/${role}

Note: The SAML Provider Name must be identical for all your AWS accounts.

6.    Choose Save.

7.    Test the user login from Okta to AWS to confirm if the error resolved.

Connect to Okta with a single AWS account

For a single account setup, Okta automatically sets up the Role Value Pattern. If you are seeing the "Your request included an invalid SAML response. To logout, click here" error for a single account integration, raise a support case with Okta to investigate the issue.

---

Related information

Error: Your request included an invalid SAML response. to logout, click here

How to configure SAML 2.0 for AWS Account Federation