Connect Okta to multiple AWS instances using an API

If you do not expect to exceed 60 AWS accounts and want a simplified user assignment process all contained within Okta, then connect to Okta using the AWS API.

High-level design

Okta can provide SSOAn acronym for single sign-on. In a SSO system, a user logs in once to the system and can access multiple systems without being prompted to sign in for each one. Okta is a cloud-based SSO platform that allows users to enter one name and password to access multiple applications. Users can access all of their web applications, both behind the firewall and in the cloud, with a single sign in. Okta provides a seamless experience across PCs, laptops, tablets, and smartphones. and fetch roles across multiple AWS accounts using a single Identity and Access Management (IAM) user account, having permissions to read IAM roles and account information across all connected accounts.

  • The IAM user account is created in an AWS account, known as the master account in Okta.

  • The IAM user account accesses connected accounts. These accounts are children of the IAM user master account. You can designate any AWS account as the IAM user master, as long as there is at least one IAM user account (with the proper permissions) in the AWS instance.

Step 1: Configure Okta as the identity provider in all AWS accounts

Configure Okta as a trusted SAMLAn acronym for Security Assertion Markup Language, SAML is an XML-based standard for exchanging authentication and authorization data between an identity provider (IdP) and a service provider (SP). The SAML standard addresses issues unique to the single sign-on (SSO) solution, and defines three roles: the end user, the IdP, and the SP. Here's how SAML works through Okta: SP-initiated flow: the end user requests (principally through a browser) a service from the SP. The SP requests and obtains an identity assertion from the IdP (in this case, Okta). On the basis of this assertion, the SP can decide whether or not to authorize or authenticate the service for the end user. IdP-initiated flow: with Okta as the IdP, an end user goes to the Okta browser and clicks on an app, sending a SAMLResponse to the configured SP. A session is established with the SP, and the end user is authenticated. SSO identity provider in all of your AWS accounts (see Step 1: Configure Okta as the identity provider in the AWS account). Use the same metadata and name throughout your accounts. This includes your master account and connected accounts.

Step 2: Add Okta identity provider as trusted source in your all AWS roles across all AWS accounts

Repeat Step 2: Add Okta Identity Provider as a trusted source in your AWS roles for each role in all accounts you wish to set up. This includes roles that you want to access from your master account and connected accounts.

Step 3: Generate the AWS API access key for Okta to download AWS roles from all accounts


You need to create an AWS user with specific permissions so Okta can dynamically fetch a list of available roles from your accounts. This makes assigning users and groupsGroups allow you to organize your end users and the apps they can access. Assigning apps to large sets of end users is made easier with groups. to specific AWS roles easy and secure for administrators.

Complete this procedure for each account you want to connect.


  1. From the AWS Console, choose Identity and Access Management (IAM) > Users and then click Add user.

  2. From the Add user page (step 1 view), specify a user name.

    Example: OktaSSOuser

  3. From the Select AWS access type area, select Programmatic access and then click Next Permissions.

  4. From the Add user page (step 2 view), click Attach existing policies directly and then Create policy.

    The Create policy page (step 1 view) opens in a new IAM Management Console browser tab.

  5. Click the JSON tab.

  6. Delete the existing code in the JSON tab and then paste the following code in the tab:

        "Version": "2012-10-17",
        "Statement": [
              "Effect": "Allow",
              "Action": [
              "Resource": "*"
  7. Click Review policy.

  8. From the Create policy page (step 2 view), enter a policy name and description.

    Example policy name: OktaMasterAccountPolicy

  9. Click Create Policy.

    The appAn abbreviation of application. Essentially, it is a web-based site used to perform any number of specific tasks, and requires authentication from end users by signing in. returns you to the first browser tab where you can continue assigning policies to your IAM user.

  10. Click the first IAM Management Console browser tab.

  11. From the Add user page (step 2 view), ensure that Attach existing policies directly is selected.

  12. Locate and select the policy you just created.

    Use the refresh button to update your search.

  13. Click Next: Tags.

  14. From the Add user page (step 3 view), click Next: Review.

  15. From the Add user page (step 4 view), click Create user.

  16. From the Add user page (step 5 view), make a copy of your access key ID and secret access key.

    The keys are needed in Step 5: Configure the AWS app in Okta to configure the AWS app in Okta.

    This is the only time that you will be able to see and copy these keys.

Step 4: Set up an IAM role in each of the connected accounts


Now that you have created an AWS user with read permissions for accounts and roles in your master account, each of your remaining connected accounts need to trust the master account user and permit it to read roles.


  1. From a connected account, go to Roles > Create Role.

  2. From the Create role page, click Another AWS account, enter the master account ID, and then click Next: Permissions.

    The master account ID can be found by choosing My Account from the drop-down in the top right of the AWS Console.

  3. Attach a policy with read access to IAM roles.

    Example: IAMReadOnlyAccess

    Alternatively, you can create a new policy with minimum read permissions attached and then attach the policy to the role that you're creating (see below).

        "Version": "2012-10-17",
        "Statement": [
              "Effect": "Allow",
              "Action": [
              "Resource": "*"
  4. Name the role Okta-IdpAn acronym for Identity Provider. It is a service that manages end user accounts analogous to user directories such as LDAP and Active Directory, and can send SAML responses to SPs to authenticate end users. Within this scenario, the IdP is Okta.-cross-account-role.


    This is a predefined name for this integration. A different name cannot be used.

  5. Repeat this procedure for each connected account, ensuring to use the same master account ID and role name (Okta-Idp-cross-account-role).

Step 5: Configure the AWS app in Okta

  1. From the Okta AdminAn abbreviation of administrator. This is the individual(s) who have access to the Okta Administrator Dashboard. They control the provisioning and deprovisioning of end users, the assigning of apps, the resetting of passwords, and the overall end user experience. Only administrators have the Administration button on the upper right side of the My Applications page. Dashboard, select the Sign On tab for the AWS app and then click Edit.
  2. From the Advanced Sign-On Settings area, select your environment type from the AWS Environment drop-down.

    If your environment type is not listed, you can set the desired ACS URLACS Endpoint – Assertion Consumer Service URL – often referred to simply as the SP login URL. This is the endpoint provided by the SP where SAML responses are posted. The SP needs to provide this information to the IdP. in the ACS URL field.

  3. Paste in the Identity Provider ARN field the identity provider ARN that you copied earlier.
  4. Specify in the Session Duration field the desired session duration for users.
  5. Click Save/Next.

  6. Click the ProvisioningProvisioning is the enterprise-wide configuration, deployment, and management of multiple types of IT system resources. Specifically, provisioning provides users access to equipment, software, or services. This involves creating, maintaining and deactivating required business process automation objects and attributes in systems, directories, and applications. tab for the AWS app and then click Edit.


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

  7. Select the Enable API Integration check box.

    • If your environment type is listed in the AWS Environment drop-down under the Sign-on tab, you do not need to complete the ACS URL field.

    • If your environment type is not listed in the AWS Environment drop-down, then enter your API URL in the ACS URL field. You may have to contact AWS to learn the API URL for your environment.

  8. In the Access Key and Secret Key fields, enter the keys you retrieved and stored in Step 3: Generate the AWS API access key for Okta to download AWS roles from all accounts.

  9. Provide a comma-separated list in the Connected Accounts IDs field of all IDs of the connected accounts.

    You can find the IDs in each AWS account from the My Accounts page in the top- right area of the AWS Console.

  10. Click Test API credentials to ensure the credentials work for all connected accounts and fix any errors.

  11. Enable the desired options to update roles and permissions from AWS.

    • Enable Create Users and Update User Attributes

    • Enable Create Users (but not Update User Attributes).


    You are not creating or updating any users in AWS, but activating parts of the API that enables Okta to retrieve Okta-trusted roles from the AWS account.

  12. Click Next (or Save).
  13. Assign the AWS app to a test user.

    • From the User Assignment page, you can view a list of roles from your master account and connected (secondary) accounts.
    • Okta displays roles in the format: Account Name - Role Name.
    • If AWS accounts have an alias setup, Okta uses the account alias instead of the account name.

      Example: [Account Alias] - Role Name.

    • In the following example, starks is used as the account alias.

  14. Complete the app assignment.
  15. Log in to your Okta orgThe Okta container that represents a real-world organization. as the test user and then click the AWS app.

    The AWS window lists the roles available to the user in Okta.

  16. Select the role to use when logging in to AWS.

  17. Ensure that there are no errors and the user is able to log in with the assigned role.

  18. You can return to Okta and assign users and groups (or only groups) to the AWS app.