How to Configure SAML 2.0 for AWS Account Federation



Supported Features

The Okta/AWS Account Federation SAML integration currently supports the following features:


Okta's integration with Amazon Web Services (AWS) allows end users to authenticate to one or more AWS accounts and gain access to specific roles using single sign-on with SAML. Okta admins have the ability to download roles from one or more AWS into Okta, and assign those to users. In addition, Okta admins can also set the duration of the authenticated session of users via Okta.

When logging in to AWS, end users will be presented with an AWS screen with a list AWS roles assigned to them in one or more AWS accounts. They can select the role to assume for login, which defines their permissions for the duration of that authenticated session.


Connecting Okta to your AWS instance to provide SSO into AWS roles for your users is a simple four step process:

Step 1: Configure Okta as your Identity Provider in your AWS Account

In order to use SAML for AWS, you will have to set up Okta as an identity provider in AWS and establish the SAML connection. The steps in this section will walk you through this process.

  1. Sign in to your AWS Console.

  2. Go to Identity and Access Management (IAM) Service.

  3. Select Identity Providers in the menu bar.

  4. Click Create Provider to create a new instance.

  5. On the Configure Provider screen, enter the following:

    • Provider Type: Select SAML from the dropdown menu.

    • Provider Name: Enter the name of your preference; for example, Okta.

    • Metadata Document: Upload the following metadata file:

      Sign into the Okta Admin dashboard to generate this value.

  6. Finish provider configuration.

  7. Locate the Identity Provider you just created in the list of Identity Providers and copy its Provider ARN value. You will need it later during this configuration.

  8. Step 2: Add Okta Identity Provider as Trusted Source in your AWS Roles

    Now that you have configured Okta as the Identity Provider in AWS, you can create or update existing IAM roles that Okta will be able to retrieve and assign to users in Okta. Note that Okta will only be able to provide SSO for your users to roles that have been configured to grant access to the Okta SAML Identity Provider you configured in the previous step (Step 1: Configure Okta as your Identity Provider in your AWS Account).

    To grant SSO access to existing roles in your account:

    1. Go to Roles and select the role that you would like to permit Okta SSO access to.
    2. Select the Trust Relationship tab for the role, then click Edit Trust Relationship.

    3. You now need to modify the IAM trust relationship policy to permit SSO into Okta using the SAML IDP you configured in the previous step:

      1. If your policy is currently empty, you can copy and paste the policy listed below and replace <COPY & PASTE SAML ARN VALUE HERE> with the ARN value you copied from step 1 (Step 1: Configure Okta as your Identity Provider in your AWS Account). { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "<COPY & PASTE SAML ARN VALUE HERE>" }, "Action": "sts:AssumeRoleWithSAML", "Condition": { "StringEquals": { "SAML:aud": "https://signin.aws.amazon.com/saml" } } } ] }
      2. If you have a current trust relationship in place, then you may need to modify your existing policy document to also include Okta SSO access. At a minimum, you will need to include everything within the Statement code block.

    To grant SSO access to a new role:

    1. Go to Roles > Create Role.

    2. Use SAML 2.0 federation type of trusted entity.

    3. Select Okta (name of your identity provider) as the SAML provider and Allow programmatic and AWS Management Console access, then proceed to Permissions.

    4. Select your preferred policy to be assigned to the role you're creating.

    5. Finish Role configuration.

    Step 3: Generate the AWS API Access Key for Okta to Download AWS Roles

    You now need to create an AWS User with specific permissions so that Okta can dynamically fetch a list of available roles from your account. This makes assigning users and groups to specific AWS roles easy and secure for your administrators.

    1. From the AWS Console, go to IAM > Users.

    2. Select Add user.

    3. Enter a User name; for example, OktaSSOuser, select Programmatic access as the Access type, then proceed to Permissions.

    4. Select Attach existing policies directly, then Create Policy.

    5. Use JSON to enter the Policy Document and replace the content with following:

      { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iam:ListRoles", "iam:ListAccountAliases" ], "Resource": "*" } ] }
    6. Review policy. Refer to AWS documentation for details if needed.

    7. Enter your preferred Policy Name and compete the policy configuration.

    8. Return to your Add user tab and attach your newly created policy.

      • Refresh the list.

      • Search for the policy you've just created and select it.

    9. Proceed to the final screen that displays your Secret access key and Access key ID. Make a copy of these values as you will need these later to configure the AWS app in Okta. Finish user creation.

    Step 4: Configure the AWS Account Federation App in Okta

    Now you have finished the required steps to be performed in the AWS console, open the AWS Account Federation app integration configuration in Okta and perform the following steps to complete the set up:

    1. In Okta, select the Sign On tab for the AWS Account Federation app, then click Edit.

      • Select your Environment Type from the dropdown menu. If your environment type is not listed, you can set your desired ACS URL in the ACS URL field. Note that that ACS URL field is optional; if your environment type is listed in the dropdown, you do not need to enter your ACS URL.
      • Enter the Identity Provider ARN from Step 1: Configure Okta as your Identity Provider in your AWS Account
      • Set the desired Session Duration.
      • Join all roles: This option enables merging all available roles assigned to a user as follows:

        For example, if a user is directly assigned Role1 and Role2 (user to app assignment), and the user belongs to group GroupAWS with RoleA and RoleB assigned (group to app assignment), then:

        • Join all roles OFF: Role1 and Role2 are available upon login to AWS
        • Join all roles ON: Role1, Role2, RoleA, and RoleB are available upon login to AWS
      • Use Group Mapping enables CONNECT OKTA TO MULTIPLE AWS INSTANCES VIA USER GROUPS functionality.
      • Click Save/Next.
    2. Still in Okta, select the Provisioning tab for the AWS app, then click Edit.

      Note: The AWS Account Federation app integration does not support provisioning. This setup under the Provisioning tab is required to provide API access to Okta to download a list of AWS roles to assign during the user assignment. It allows you to assign multiple roles to users and pass those roles in the SAML assertion.

      • Click Enable API Integration.

      • API URL (optional): If your Environment Type was listed in the dropdown under the Sign-on tab, you do not need to fill out this field. If your Environment Type was not listed in the dropdown, enter your API URL here. You may have to contact AWS to find out the API URL for your environment.

      • In the Access Key and Secret Key fields, enter the values you made copies of in Step 3 (Step 3: Generate the AWS API Access Key for Okta to download AWS Roles).
      • Connected Accounts ID (optional): Provide a comma-separated list of all of the IDs of your connected accounts. You can find this in each AWS account from the My Accounts page in the top-left hand corner of the AWS Console.

        Note: If you have an AWS instance that was configured to use the Amazon AWS IAM role as the Sign On mode, and remove an optional child account from that instance, their role provisioning will be removed and an event will be generated in the System Log.

      • Click Test API Credentials to verify API credentials are working:

      • To be able to update Roles and Permissions from AWS you need to enable Create Users and Update User Attributes:

        Note: As a reminder, you are not creating or updating any users in AWS, but this activates necessary parts of the API to allow Okta to retrieve Okta-trusted roles from the AWS account.

      • Click Save.
    3. In the Assign People screen, select a test user you wish to use to test the SAML connection for the AWS app.
    4. In the User Assignment screen, go to SAML User Roles, and select all the roles you would like to assign to this user, then click Save. In this example, we have assigned two roles to our test user:

      IMPORTANT: If you see the attribute IdP and Role Pairs (internal attribute), ignore it. It is an internal attribute and it doesn't affect user assignment.

    5. Once the assignment is complete, an AWS application icon will appear on the test user's Okta dashboard. Sign in to your Okta org as the test user, and click on the application icon.
    6. The user will be presented an AWS screen with a list of roles assigned to it in Okta. Here, select the role to assume when logging in to AWS.

    7. Ensure that there are no errors and the user is able to log in with the assumed role.
    8. Once this test is complete, you can go back in Okta and start assigning users and/or groups to the AWS app.


    Note that connecting multiple AWS accounts via the API is no longer supported. Use the following instructions to switch to multiple AWS accounts role management via groups.

    Managing User and Group Access to Accounts and Roles

    Note that although the following instructions apply to all applications, including AD/LDAP, profile-sourced ones. Local Okta groups can be used as well.

    AWS Role Specific Groups

    A group must exist in Okta for each specific account and role combination that you want to provide access to. You can think of these groups as AWS Role Specific Groups. The group name should follow a particular syntax (more details in Set Up Instructions).

    Any user who is a member of these role specific groups is granted a single entitlement: access to one specific role in one specific AWS account. These groups can be created by a script, exported as a list from AWS, or created manually.

    Management Groups

    However, it does not scale to manage user access by assigning each user to specific AWS Role Groups. To simplify administration, we recommend you also create a number of groups for all of the distinct user-sets in your organization that require different sets of AWS entitlements.

    These groups may already exist in your Okta or AD/LDAP hierarchy in the form of different department-specific groups, but can also be created solely for AWS.

    High-Level Design


    Set Up AWS Accounts for SAML

    Each of your AWS accounts must be configured for SAML access. This entails adding Okta as a trusted IDP to your AWS account and then creating a trust relationship for each of your roles that permits access via the new IDP. These are the same steps that one would follow to provide SAML SSO into any single AWS account, but must be performed across all of your accounts. For advanced organizations, this can be automated with Cloud Formation or AWS API scripts for a simple SAML setup in each account.

    Set Up Instructions


    Step 1: Setting Up Your AWS Accounts and Roles for SAML SSO

    First, setup all of your AWS accounts for SAML access with Okta.

    1. Begin by creating a new AWS app in Okta and select SAML from the Single Sign-On tab.

    2. Perform steps 1 and 2 of CONNECT OKTA TO A SINGLE AWS INSTANCE:

    3. Do this for all of your AWS accounts and roles that you want to grant users access to – and ensure that all of your accounts have been set up with the same exact SAML metadata and have been named the same exact name. Any account with a different SAML provider name or metadata document will not be accessible.

    Step 2: Creating AWS Role Groups

    Once all AWS accounts have been configured for SAML, groups must be created in AD for each AWS role in each account that you want users to have access to. This can be accomplished in a few different ways:

    Regardless of how you choose to create these AWS Role Specific Groups in your directory, we recommend the following format for the group names:

    aws#[account alias]#[role name]#[account #]

    For example:


If you prefer to use your own group syntax, make sure to include account alias, role name, and account # with recognizable delimiters in between each. This will also require you to be able to create a custom regex expression in later steps and therefore should only be done if you are comfortable with these advanced topics.

Step 3: Enabling Group Based Role Mapping in Okta

Once the groups have been created/imported into Okta, the AWS app you set up earlier must be configured to translate AWS Role group membership into entitlements that AWS can understand syntactically:

  1. Go to the AWS app you set up earlier.

  2. Select the Sign On tab, then click Edit.

  3. Locate the App Filter, Group Filter, and Role Value Pattern fields. These fields control how Okta maps your AWS role groups into entitlements for this feature. Configure these fields as follows:

    • App Filter: This filter narrows the list of groups that Okta can use for AWS entitlement mapping to a specific app or directory. This exists for security purposes, to avoid possible situations where rogue admins create groups following a certain syntax in order to intentionally gain unauthorized access to a specific AWS account/role. If you created your groups in Active Directory, you can input active_directory, if you want to limit usage by local Okta groups, input okta. For other application(s) you can use values such as bamboohr for Bamboo HR app or okta, egnyte for Okta + Egnyte groups.

    • Group Filter: This filter field uses a Regex expression to only inspect groups from your chosen app filter that follow a specific syntax. If you did chose to use the Okta recommended default AWS role group syntax listed above, then you can simply use the following regex string:


      This regex expression logically equates to: find groups that start with AWS, then #, then a string of text which contains only non-whitespace characters, then #, then the AWS role which contains word characters or minus sign, then #, then the AWS account ID

      If you didn’t use the default recommended AWS role group syntax, then you must create a regex expression that properly filters your AWS role groups, and captures the AWS role name and AWS Account ID within two distinct Regex groups named {{role}} and {{accountid}} respectively.

    • Role Value Pattern: This field takes the AWS role and account ID captured within the syntax of your AWS role groups, and translates it into the proper syntax AWS requires in Okta’s SAML assertion to allow users to view their accounts and roles when they sign in.

      This field should always follow this specific syntax:

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

      Replace [SAML Provider Name] with the name of the SAML provider that you set up in all of your AWS accounts. The rest of the string should not be altered, only copied and pasted.


Step 4: Assign All AWS Management Groups to the AWS App in Okta

Lastly, now that the AWS app has been properly configured to map AWS role groups to entitlements, assign all of your AWS Management Groups to the application in Okta. This will automatically assign all of the appropriate users to the AWS app, and the instructions you completed in the step above will ensure that they only see the appropriate entitlements they should have access to.

Setup is now complete! Verify that users can access the AWS app from their Okta end-user dashboard and sign-on is seamless.