IAM Federation - Okta


In this lab we will walk through how to deploy Okta with AWS Control Tower using IAM federation. We will be using AWS CloudFormation StackSets to deploy IAM roles (Admin, PowerUser, ReadOnly) and register Okta as Identity providers on each linked accounts.


  • This lab requires fully provisioned AWS Control Tower and administrator role access to AWS Control Tower management account.
  • AWS Control Tower Audit account id, you can find this by navigating to AWS Control Tower console and look at the Accounts list.
  • We will be utilizing an Okta Developer free account to create our Okta instance and test users for this lab. Sign up for an account here https://developer.okta.com/signup/


INFO: Depending on when you sign up for Okta (developer or enterprise version), your Okta admin console might look slighly different from the screenshot provided.

1. Add a new Amazon Web Services Application on the Okta console

In this section we are going to setup integration app in Okta for AWS SSO. First we need to create an AWS Account Federation integration app.

1.1 Sign in to the Okta admin console: https://developer.okta.com/login/ (if you don’t have one, Sign up here)

  • Optional: On the very top of the screen if it shows Developer Console, change this to Classic UI
  • Optional: If you login to Okta user dashboard, click on Admin at the upper right of the console

1.2 Select Applications then Add Application

1.3 Search for AWS Account Federation and select Add

1.4 On the Okta App General Settings section:

  • Rename the Application label as required, for example AWS Control Tower IAM Federation
  • Select Next to continue

1.5 On the Okta App Sign-On Options section:

  • On Sign on methods select SAML 2.0
  • Leave the Default Relay State as blank
  • Locate the Identity Provider metadata link, Right Click and copy the link address / URL. Keep this Identity Provider metadata URL value as you will need it on the next section.
  • Identity Provider metadata URL should be in format like: https://[your okta id].okta.com/app/[random id]/sso/saml/metadata?isNewAppInstanceSetup=true
  • Keep others parameter default value as is, and click Done

1.6 Dont close this brower tab, you will return to this later

2. Deploy Okta IAM federation integration in AWS Control Tower

INFO: template used in this lab is based on the Landing Zone add-on for Okta

In this section, we will launch the CloudFormation StackSet using the URL for Identity Provider metadata that we setup earlier.

2.1 Open this CloudFormation template in new tab aws-okta-integration.template and save it to your local computer.

2.2 Sign in to AWS Control Tower management account using Administrator role.

2.3 Ensure your AWS console are in the home region where your AWS Control Tower is deployed.

2.4 Navigate to CloudFormation StackSet using this quick link

2.4 Select Upload a template file , choose the file that you downloaded earlier on step 2.1

2.5 Select Next

2.6 Enter the StackSet name, for example OktaIAMFederation

2.7 On the Parameters section, fill in the following parameters:

  • OktaMetadataURL : enter the URL value for Identity Provider metadata (from step 1.5)
  • Identity Account : enter the AWS Account id of AWS Control Tower Audit account.
  • Optionally, you can also modify the role name as required.

2.8 Click Next

2.9 On the Permissions section:

  • Select Self-service permissions
  • On the IAM admin role ARN select AWSControlTowerStackSetRole
  • On the IAM execution role name replace the value with AWSControlTowerExecution

IMPORTANT : make sure to double check the value that you enter on step 2.9 to ensure successfull deployment.

2.10 Click Next

2.11 On the Accounts section:

  • You can choose to enter comma delimited list of all target accounts, or Organizational Units (OUs).
  • Regardless the method, make sure to include the Audit account id or the Core OU where this account resides.
  • At minimum you must enter the Audit account and one additional account to test. These are the accounts that you will configure to all Okta access to.

2.12 On the Specify regions section:

  • Choose the AWS region where you deployed AWS Control Tower
  • Do not select more than one region

2.13 Click Next

2.14 On the Review section:

  • Select the I acknowledge that AWS CloudFormation might create IAM resources with custom names
  • Click Submit to deploy

2.15 Refresh the AWS CloudFormation StackSet console, wait until operation completed and all StackSet instances deployed successfully.

TIP : When integrating with a third party IdP it is a good practice to keep AWS SSO available for break glass scenarios. For example access can be restricted only to the Infosec team but quickly expanded to others. Unlike other IdP AWS SSO can dynamically generate IAM policies to all accounts of the Organization without going through stackset deployments

3. Generate IAM user credentials for OktaSSOUser

On the previous steps, you have deployed AWS CloudFormation StackSet that creates IAM user OktaSSOUser in the Audit account. In this section you will generate AccessKey and SecretKey to allow Okta to programmatically access the Audit account.

3.1 Sign in to AWS Control Tower Audit account using Administrator role. (Tips: use AWS SSO portal)

3.2 Navigate to IAM console using this quicklink

3.3 Select Users from the sidebar

3.4 Select the IAM user OktaSSOUser

3.5 Select Security credentials tab

3.6 Click Create access key

3.7 Write down the AccessKey and SecretKey value in secure temporary notes.

Warning : keep this information secure and treat it like regular password

On this section, we will complete the setup on Okta portal by entering the credentials from the previous section.

4.1 Return to your Okta tab

4.2 On the Okta app AWS Control Tower IAM Federation screen, select Sign On tab and select Edit

4.3 On Advanced Sign-on Settings

  • On Identity Provider ARN enter the Audit account IDP ARN
  • Format: arn:aws:iam::[audit account_id]:saml-provider/OktaIDP where [audit account_id] is the Audit account you selected for Identity management.
  • TIP: You can lookup your IdP ARN in your Audit account/IAM Console/Identity providers

4.5 On the Okta app AWS Control Tower IAM Federation screen, select Provisioning tab

4.5 Select Integration from the side bar.

  • Optional: select Configure API Integration
  • Select Enable API Integration
  • Enter Access Key : use the AccessKey value from step 3.7
  • Enter Secret Key : use the SecretKey value from step 3.7
  • Enter Connected Accounts IDs : enter comma delimited list of AWS accounts included in the StackSet (step 2.11)
  • Select Test API Credentials
  • Click Save

4.6 Still on Provisining tab, two new side menu should appear now.

4.7 Select To App from the side bar.

  • Click Edit
  • On Create Users select Enable
  • Click Save

5. Create Okta user and assign to Okta app

On this section we will create test user in Okta and assign the user to the AWS Control Tower IAM Federation Okta app.

5.1 Return to your Okta admin console (https://developer.okta.com/login/)

5.2 From the sidebar, select Directory and select People, then select Add person

  • Add all required parameters to create new user
  • Select Save when you complete

5.3 From the sidebar, select Applications, and then select the AWS Control Tower IAM Federation Okta app.

  • Select Assignments tab
  • Click Assign
  • Select users or groups that you wish to assign access to this Okta app
  • Select the IAM role that Okta users / groups can assume

6. Test login to Okta

On this section, you will try to login as Okta regular user (non Admin) and use the provided Okta app to login to AWS.

6.1 Login to the Okta Console as a regular user

  • Use your Okta domain URL, you can find it on your Okta URL. Example: https://dev-[random id].okta.com/
  • Login using test user that you created earlier or any existing users

6.2 Select the AWS Control Tower IAM Federation Okta app

6.3 Select the AWS account and IAM role you want to assume and access the AWS Console

Congratulations, you have completed the IAM Federation labs for Okta!

Exploring the Solution

Deleting AWS resources deployed in this lab

There is nothing that incurs charges but you can:

  1. Delete the Stacks deployed from the OktaIntegration StackSet
  2. Delete the StackSet OktaIntegration itself
  3. Delete the application and users created in the Okta portalß


Copyright 2021, Amazon Web Services, All Rights Reserved.