AWS migration options

Okta’s integration with Amazon Web Services (AWS) has evolved over the years. With the addition of AWS’s own SSO and SCIM integration, we want to give you options to improve your existing integration setup.

• If you have a single AWS instance configured to connect roles to Okta users via the AWS Identity and Access Management (IAM) API. We encourage you to either:

  • Consider using AWS’s new SSO and SCIM integration: AWS has built their own OIN app that handles SSO and SCIM provisioning. If you have made the transition to AWS organizations or would like to, this is a great opportunity to use AWS’s new integration.

  • Update your AWS policy to be more restrictive.

• If you have multiple AWS instances configured to connect roles to Okta users via the IAM API, this approach is no longer supported by Okta. We encourage you to either:

  • Consider using AWS’s new SSO and SCIM integration: AWS has built their own OIN app that handles SSO and SCIM provisioning. If you have made the transition to AWS organizations or would like to, this is a great opportunity to use AWS’s new integration.

  • Migrate to using user groups to manage multiple AWS instances: We provide full instructions on how to migrate from using the API to using user groups.

  • Update your AWS policy: The best approach is to migrate to the new AWS’s new integration or to user groups, but we understand this can be difficult and complex with multiple app instances so we offer an option to adjust your AWS policy to be more restrictive.

Using the AWS SSO and SCIM Integration

In May 2020, we announced a new AWS SSO and SCIM integration. The details can be found here: https://www.okta.com/blog/2020/05/how-okta-aws-sso-simplifies-admin-and-adds-cli-support/. If you are using AWS Organizations or would like to, you can setup the new integration using the following instructions.
 

Prerequisites

• Log into your Okta tenant and add the AWS SSO application.

• Follow the instructions linked here: How to Configure SAML 2.0 for AWS Single Sign-On.

• Ensure your AWS account has SSO enabled. See Enable AWS SSO for more details.

Step 1: Enable Provisioning in AWS SSO

In this first step, you use the AWS SSO console to enable automatic provisioning.

1. After you have completed the prerequisites, open the AWS SSO console.

2. Choose Settings in the left navigation pane.

3. On the Settings page, under Identity source > Provisioning, choose Enable automatic provisioning. This immediately enables automatic provisioning in AWS SSO and displays the necessary endpoint and access token information.

4. In the Inbound automatic provisioning dialog box, copy each of the values for the following options. You will need to paste these in later when you configure provisioning in your IdP.

5. SCIM endpoint

6. Access token

7. Choose Close.

You have set up provisioning in the AWS SSO console. Now you need to do the remaining tasks using the Okta user interface as described in the following procedures.

Step 2: Configure Provisioning in Okta

Use the following procedure in the Okta admin portal to enable integration between AWS SSO and the AWS Single Sign-On app.

1. In a separate browser window, login to the Okta admin portal and navigate to the AWS Single Sign-On app.

2. In the AWS Single Sign-On app page, choose the Provisioning tab, and then choose Integration.

3. Choose Configure API Integration, and then select the check box next to Enable API integration to enable provisioning.

4. In the previous procedure you copied the SCIM endpoint value in AWS SSO. Paste that value into the Base URL field in Okta. Make sure that you remove the trailing forward slash at the end of the URL. Also, in the previous procedure you copied the Access token value in AWS SSO. Paste that value into the API Token field in Okta.

5. Choose Test API Credentials to verify the credentials entered are valid.

6. Choose Save.

7. Under Settings, select To App, choose Edit, and then select the Enable checkbox for each of the Provisioning Features you want to enable.

8. Choose Save.

By default, no users or groups are assigned to your Okta AWS Single Sign-On app so you will need to complete the next procedure to begin synchronizing users and groups to AWS SSO.

Step 3: Assign Access for Users and Groups in Okta

Use the following procedures in Okta to assign access to your users and groups. Okta users who belong to groups that you assign here are synchronized automatically to AWS SSO. To minimize administrative overhead in both Okta and AWS SSO, we recommend that you assign and push groups instead of individual users.

After you complete this step and the first synchronization with SCIM is completed, the users and groups that you have assigned appear in AWS SSO. Those users are able to access the AWS SSO user portal using their Okta credentials.

To assign access for users in Okta:

1. In the AWS Single Sign-On app page, select the Assignments tab.

2. In the Assignments page, choose Assign, and then choose Assign to People.

3. Select the Okta user or users whom you want to assign access to the AWS Single Sign-On app. Choose Assign, choose Save and Go Back, and then choose Done. This starts the process of provisioning the user or users into AWS SSO.

To assign access for groups in Okta:

1. On the AWS Single Sign-On app page, choose the Assignments tab.

2. In the Assignments page, choose Assign, and then choose Assign to Groups.

3. Select the Okta group or groups that you want to assign access to the AWS Single Sign-On app. Choose Assign, choose Save and Go Back, and then choose Done. This starts the process of provisioning the users in the group into AWS SSO.

4. Choose the Push Groups tab, choose the Okta group or groups that you selected in the previous step. Then choose Save. The group status changes to Active after the group and its members have successfully been pushed to AWS SSO.

To grant your Okta users access to AWS accounts and cloud applications, complete the following applicable procedures from the AWS SSO console:

• To grant access to AWS accounts, see Assign User Access.

• To grant access to cloud applications, see Assign User Access.

You can now disable the previous AWS app to avoid any conflicts.

The instructions can be found here: https://docs.aws.amazon.com/singlesignon/latest/userguide/okta-idp.html.
 

Migrate to Using User Groups

If you have connected multiple AWS instances via the API and now wish to use user groups instead, please follow these instructions. We suggest creating a new AWS app to avoid any conflicts or issues with your existing one.

Managing User and Group Access to Accounts and Roles

Note that although the following instructions apply to all applications, including AD/LDAP, profile-mastered 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.

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.

I’m skipping the Set Up Instructions because you’re going to delete those 2 steps we talked about Creating AWS Role Groups

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

• Option 1: Script between AWS and AD/LDAP connected to Okta that creates AD groups for each role in each account

• Option 2: CSV Export from AWS

• Option 3: Manual Creation

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:

aws#northamerica-production#Tier1_Support#828416469395

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.

Enabling Group Based Role Mapping in Okta – I omitted the image

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. Navigate 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:

   1. 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.

   2. 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:

   3. 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.

   4. 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. You can now disable the previous AWS app to avoid any conflicts.

Next steps

Update your AWS policy

If you have multiple AWS instances configured via the API, please follow these instructions to have more restrictive policy setup.

1. Login to AWS console and navigate to IAM Service

2. Find the IAM User that’s being used by Okta integration for API calls

3. Review the Policies attached to the User
   If you have sts:AssumeRole action assigned to a wildcard R
   Please update the policy to limit resources allowed for sts:AssumeRole action to "arn:aws:iam::*:role/Okta-idp-cross-account-role".
   You can do it by creating a separate statement in the Policy like so:

...{"Effect": "Allow","Action": "sts.AssumreRole","Resource": "arn:aws:iam::*:role/Okta-Idp-cross-acount-role"}...

4. Review and save updated Policy

Please refer to AWS documentation on IAM Policies for more details.