Integrating Okta with AWS Single Sign-On in an AWS Control Tower environment
AWS Control Tower provides a ready-to-use native integration with AWS Single Sign-On (AWS SSO) to manage users, roles, and multi-account access. Some customers’ organizations have more complex SSO requirements, including integrating with external identity providers to handle authentication and authorization. Okta is an enterprise-grade identity management service that is built for the cloud, but is compatible with many on-premises applications. You can find and subscribe to Okta in AWS Marketplace.
In this blog post, I show how to integrate AWS Control Tower, AWS SSO, and Okta as an external identity provider so that you can manage users, entitlements, accounts, and roles in Okta. I show how to use System for Cross-domain Identity Management capabilities (SCIM rfc7644) to allow Okta to manage users, groups, and group memberships for integration with AWS SSO.
When you integrate AWS Control Tower with Okta, you must choose one of the following options:
- Manually create AWS Identity and Access Management (IAM) roles on every AWS Control Tower managed account, including new accounts provisioned by Account Factory
- Use the SCIM capability in AWS SSO to automatically synchronize users and roles between Okta and AWS, providing administrators with a single location to manage users and permissions.
This solution uses the SCIM option.
In this solution, you create an Okta application to manage the identity federation between Okta and AWS Control Tower. You manage users and groups inside Okta, and that access is replicated into AWS SSO via SCIM. A second application inside Okta automates provisioning of users and groups from Okta to AWS SSO. AWS SSO handles the mapping between groups and permissions sets and accounts. These mappings require eventual modifications as you create accounts or define new permission sets.
The following image shows the solution architecture.
- Users authenticate against Okta.
- Users log on to AWS SSO upon successful authentication with Okta.
- Users now can assume roles to perform tasks within their AWS environment using Security Assertion Markup Language (SAML), which is managed by AWS SSO.
Authenticated users are managed and validated by Okta with their usernames and groups pushed to AWS SSO via SCIM. Refer to the following diagram.
- An AWS Control Tower environment. Follow this Getting Started with AWS Control Tower guide to set up one if needed.
Complete the following steps to integrate Okta and AWS Control Tower with automatic user provisioning.
- Subscribe to Okta in AWS Marketplace.
- Create the Okta SAML application (login flow) and connect it with AWS SSO for identity federation.
- Create the Okta SCIM application (SCIM synchronization flow).
- Create and map Okta groups to permission sets.
Step 1: Subscribe to Okta in AWS Marketplace
Step 2: Create the Okta SAML application and connect it with AWS SSO
A. Configure AWS SSO to use Okta as an external identity provider
For more information, see Connect to Your External Identity Provider in the AWS Single Sign-On User Guide. To configure AWS SSO to use Okta as an external identity provider, do the following:
- Sign in to the AWS Management Console and navigate to the AWS SSO service.
- On the left pane of AWS SSO console, choose Settings.
- On the Settings page, in Identity Source, choose Change.
- Select External Identity Provider.
- In Service provider metadata, choose Show individual metadata values.
- Open a browser tab to access the Okta console. Keep the AWS SSO console tab open.
B. Create an Okta application to connect with AWS SSO
You might see existing applications for AWS in the Okta gallery, but these tend to be for authenticating directly into individual AWS accounts. For this solution, you need to create your own application to connect to AWS SSO.
- Log in to the Okta console. If the top of the screen shows Developer Console, change it to Classic UI. In the toolbar, choose Applications and then Applications. Choose Add Application.
- Choose Create New App. For Platform drop-down menu, choose Web. For Sign on method, select SAML 2.0. Choose Create. Specify a name for the application (for example, AWS SSO) and choose Next.
- Copy and paste the following fields from the AWS SSO console browser tab:
- Single sign on URL: AWS SSO ACS URL
- Audience URI (SP Entity ID): AWS SSO Issuer URL
- Name ID format: EmailAddress
- Leave other parameters at default
- Choose Next. Select I’m a software vendor. I’d like to integrate my app with Okta and choose Finish. In the toolbar, choose Applications and then the created application (AWS SSO). Choose the Sign On sub-tab.
- Choose Identity Provider metadata, the browser will open a new tab with the XML data. Save the XML that it displays as okta-idp.xml on your computer and close the browser tab that displays the metadata.
- On the Okta console, choose Back to Applications or choose Applications on the toolbar.
C. Upload the metadata
To complete the configuration of Okta as the external identity provider, upload the metadata of the Okta identity provider to AWS SSO.
- Switch to the AWS SSO console browser tab you opened in step 2.A.1.
- Choose Browse and select the okta-idp.xml document that you saved from step 2.B.5.
- In the Identity Source section, in the Identity Source row, choose Change.
- Choose Next: Review.
- Review the information provided.
- In the field at the bottom, enter CONFIRM.
- Choose Change Identity source. After the reconfiguration has completed, choose Return to settings.
Now Okta and AWS SSO are integrated, but there are no permissions mapped.
Step 3: Create the Okta SCIM application
A. Enable SCIM to synchronize users and groups from Okta into AWS SSO
For more information, see Automatic Provisioning in the AWS Single Sign-On User Guide.
- Switch to the AWS SSO console browser tab you opened in Step 2.A.1.
- In the navigation pane, choose Settings.
- Choose Enable automatic provisioning.
- Copy the SCIM endpoint and token to a text editor for use in the next section.
B. Create an application to push to AWS SSO
Now that SCIM is enabled, create an application to automatically push users and groups from Okta to AWS SSO via SCIM. For more information, see Create your application in the Okta documentation.
- Switch to the Okta console browser tab you opened in Step 2.A.6.
- Choose Add Application.
- In the suggestions, search for SCIM 2 Oauth. Select SCIM 2.0 Test App (OAuth Bearer Token). Choose Add.
- On the General Settings page, enter Application label: AWS SSO – SCIM 2.0 (OAuth Bearer Token). Select Do not display application icon to users. And then Do not display application icon in the Okta Mobile App. Choose Done.
- On the Provisioning tab, choose Configure API Integration. Select Enable API integration. Enter the parameters that you copied in step 3.A.4.
- For SCIM 2.0 Base Url, use the SCIM endpoint.
- For OAuth Bearer Token, use the access token.
- Choose Save and then Edit. Choose Enable Create Users and then choose Save.
C. Create a rule to push to AWS SSO
Next, create a rule for the application to automatically push groups that meet the condition from Okta to AWS SSO thru SCIM. Under the same application we have just created (AWS SSO – SCIM 2.0 (OAuth Bearer Token) from step 3.B, do the following:
- Select Push Groups Choose + Push Groups and then Find Groups by Rule. For Rule name, enter AWS Groups. For Group name: starts with, enter awssso. You can use any prefix. Choose Immediately push groups found by this rule and then Create Rule. On the top ribbon, choose Directory – Groups.
- Choose Add Group. It will show you a pop-up prompt called Add Group. On the Add Group prompt, for Name, enter AWS Users. Choose Add Group, which takes you back to the main Add Group page.
- Choose the AWS Users group in the list.
- Choose Manage Apps. You will see a pop-up window Assign Applications. For the AWS SSO app, choose Assign. This is the app that users will actually launch into the AWS Management Console.
- For the AWS SSO – SCIM 2.0 (OAuth Bearer Token) app, choose Assign. The user doesn’t see this, but it makes sure that their account and groups are provisioned into AWS SSO. Choose Save and go back. Choose Done.
Step 4: Create and map Okta users and groups
In step 3, you created a rule to push to AWS SSO groups that have the prefix awssso. For this step, create a group named awwssoPowerUsers with the operations team members, who should have full access to AWS services and resources except for users and groups management. For more information, see Managing Users and Access Through AWS Single Sign-On in the AWS Control Tower User Guide.
A. Create a new group in Okta
Create a new group in Okta and verify that it’s synchronized to AWS SSO.
- On the Okta console, on the top ribbon, choose Directory and then Groups.
- Choose Add Group. You will see you a pop-up prompt called Add Group. On the Add Group page, for Name, enter awsssoPowerUsers. Choose Add Group.
- On the top ribbon, choose Applications.
- Open the AWS SSO – SCIM 2.0 (OAuth Bearer Token) app and choose Push Groups. You should see that awsssoPowerUsers is listed and marked as Active.
- Switch to the AWS SSO console browser tab. In the navigation pane, choose Groups. You should see that awsssoPowerUsers is listed with No users.
B. Assign a permission set in AWS SSO
Assign a permission set in AWS SSO with appropriate privileges to the group.
- If necessary, switch to the AWS SSO console browser tab.
- In the navigation pane, choose AWS accounts and then AWS organization. Select all of your accounts. The users belonging to the operations team will have access to all accounts.
- On the Assign Users page, choose Groups. Select awsssoPowerUsers. Choose Next: Permission sets.
- On the Select permission sets page, select AWSPowerUsersAccess.
- Choose Finish. Choose Proceed to AWS accounts.
C. Create a user in the Okta portal
To create a user in the Okta portal, do the following:
- Switch to the Okta console browser tab.
- On the top ribbon of the console, choose Directory and then People. Choose Add Person. On the Add Person page, enter the following information:
- For User type, choose User.
- For First name, enter user first name.
- For Last name, enter user last name.
- For Username, enter user email.
- For Primary email, enter user email.
- For Groups, start entering awssso and choose Add next to awsssoPowerUsers. Then start entering AWS and choose Add next to AWS Users.
- For Password, choose Set by admin and enter a password.
- Clear the User must change password on first login check box. Choose Save.
- Switch to the AWS SSO console browser tab.
- In the navigation pane, choose Users. You should see the account that you created in the list. Choose the Display name of user first name user last name with Username of user email.
- Confirm that the user appears as Created By: SCIM.
D. Verify the new user is authenticated and has access
The new user should be authenticated by Okta and have access to assigned AWS accounts. To verify this is the case, do the following:
- Verifying authentication
- Switch to the AWS SSO console browser tab.
- In the navigation pane, choose Dashboard.
- Copy the user portal URL.
- Open a browser window in private or incognito mode and paste the user portal URL into the address bar. The browser should redirect you to your Okta login page.
- Enter the following information:
- For username, enter user email
- For password, enter the user password that you created in the previous section
- Provide additional security questions based on your Okta configuration. When you’re logged in, you should be returned to the AWS SSO start page.
- Verify AWS account access. To verify account access, do the following:
- Verifying authentication
- From the AWS SSO start page, choose AWS Account (3).
- Choose the name of your management account.
- On the AWSPowerUserAccess line, choose Management Console.
You should now be logged in on the management account with the AWSPowerUserAccess permissions.
For a video tutorial of this information, view Integrating Okta with AWS SSO in AWS Control Tower. At this point, you have a fully functional integration between Okta, AWS SSO, and AWS Control Tower. Now you must develop an attribute-based access control (ABAC) strategy with the different roles and groups. To do this, you create them on Okta and assign them to the appropriate accounts and permission sets in AWS SSO.
From now on, you can manage users and groups in Okta without using the AWS SSO console. However, you must use AWS SSO if there are new accounts or any changes to the mapping between groups, accounts, and permission sets.
In this post, I showed how to manage your AWS Control Tower environment by procuring Otka from AWS Marketplace and integrating it with AWS SSO. I also showed how to enable automatic user and group replication from Okta to AWS SSO and manage permissions for groups and users.
About the authors
Chris Pates is a Technical Account Manager with AWS, where he helps customers to operate at scale, with a particular interest in management, governance, and security. Chris has over 25 years of experience in software development, operations, federation, and identity management across verticals such as education, government, retail, manufacture, pharmaceuticals, and life sciences. Outside work, Chris enjoys spending time with his family, building things.
Jose Olcese is a Cloud Application Architect with AWS, where he helps customers build cutting-edge, cloud-based solutions. Jose has over 20 years of experience in software development for a variety of different industries and has helped hundreds of customers to integrate identity solutions with AWS. Outside work, Jose enjoys spending time with his family, running, and building things.
Nam Le is a Senior Partner Solutions Architect with AWS Marketplace team. He focuses on security and governance with close to 20 years of experience in consulting, sales and engineering. He specializes in AWS Control Tower, AWS Service Catalog, AWS Marketplace, and AWS Data Exchange. As an AWS Marketplace Solutions Architect, he also works with AWS partners to build and deliver best-practices solutions to customers. Outside of work, he enjoys biking, car building, travel photography, and spending time with family.