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

Short description

This error might occur if the information for the AWS Identity and Access Management (IAM) role attribute in a SAML response is missing or is incorrect. The expected value of this attribute is one or more comma-separated pairs of an IAM role and the IAM SAML provider similar to the following:

Example IAM role attribute in a SAML response provider

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, follow the instructions to View a SAML response in your browser.

Resolution

To connect to Okta with multiple AWS accounts or a single AWS account, follow these instructions.

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 to sign on. For more information, see Connect to multiple Amazon Web Services instances and Enable group-based role mapping on the Okta website.

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

1. Log in to the Okta Admin Console.

2. Choose Applications, and then choose Applications again.

3. Choose Sign On, and then choose Edit.

4. Enter the Group Name and Group Filter variables. The Group Filter is a custom regex expression that captures information such as the AWS account ID and IAM role name for your Okta group name. For more information, see Enabling Group Based Role Mapping on the Okta website.

   The Okta 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. Use delimiters that aren't part of your Role Name (for example, '#' or '|') if you get an error caused by the group filter.
   When you use IAM Federation to log in, your IAM role name can't contain ',' (comma). This restriction is necessary because the Role Value Pattern in the example bellow uses a comma to separate the SAML provider and the role name. Create a new IAM role without a comma in the name when you use this name with IAM Federation.

5. Enter the Role Value Pattern variables. 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 the 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 that the error is resolved.

Connect to Okta with a single AWS account

For a single account setup, Okta automatically sets up the Role Value Pattern. For more information, see Connect Okta to a single Amazon Web Services instance on the Okta website.

Related information

How to configure SAML 2.0 for AWS Account Federation (on the Okta website)

Troubleshoot SAML federation with IAM