Scenario

I’ve now worked at a handful of different companies utilizing Okta as the primary Identity and Access Management tool in their environment. Similarly, those companies have also been utilizing AWS as one of their cloud service providers. I was recently tasked with integrating Okta with AWS with the end state of Okta becoming the primary Identity Provider for AWS services.

While researching the solution, I came acrossmany articles that allow Okta to directly integrate with AWS SSO. In fact, the Okta in-product guides provide instruction for this use-case. In this scenario, the user experience has the user login to Okta and open the AWS SSO chicklet on their dashboard. This allows for SAML authentication to the AWS SSO portal where they are then able to select which AWS account they would like to log into. This can be a fairly easy integration with Okta and AWS insofar that the Okta Administrator doesn’t have to configure many things on the Okta side of the house. All role administration is handled in AWS. This certainly provides less complexity. However, this still leaves role and account management to be handled on the AWS side. My goal was to provide a way to access accounts and roles directly from Okta. Below is a list of high-level tasks needed to perform this request followed by the detailed step by step process.

• [In Okta] Create the AWS application
• [In AWS] Add Okta as a third-party Identity Provider
• [In AWS] Add new roles using SAML 2.0 Federation
• [In AWS] (Optional) Add Okta as a trusted source for existing AWS roles
• [In Okta] Create AWS Role Groups
• [In Okta] Create AWS Management Groups
• [In Okta] Configure the AWS application
• [In Okta] Assign Okta Groups to AWS application
• [In AWS] Generate AWS API Access Key
• [In Okta] Enable API Integration
• [In Okta] Add User to Management Group
• Testing

[In Okta] Create the AWS application

Note: To perform the necessary steps outlined in this post in Okta, you must possess at least both the Application Administrator and Group Administrator built-in roles in Okta Administrator. You should also have the Administer All Applications and Administer All Groups extensions in order to create new apps and groups. If you are not permitted to create new apps or groups, you will need to have a higher-level Okta Administrator create the necessary apps/groups and then entitle you to be an administrator of each item respectively.

First, log into Okta with your username, password, and (if prompted) your multifactor authenticator. From your Dashboard, select the Admin tile at the top right-hand side of the screen.

You will likely be prompted a second time for multifactor authentication. Okta made a change sometime in the last year or so to require all Okta Administrator access to require multifactor authentication when accessing it for the first time.

Once in Okta Administrator, navigate to Applications and select Applications from the menu drop-down.

In the Applications menu, select Browse App Catalog, search for AWS, and then select AWS Account Federation. On the following screen, select Add.

On the Add AWS Account Federation screen, click Next to move to Sign-On Options. In the Sign-On Options tab, select the SAML 2.0 radio button. Leave all of the remaining settings at defaults and click Done at the bottom of the screen.

Once finished, navigate back to the Sign On tab of the application. Below the View Setup Instructions button, right-click the link titled “Identity Provider Metadata” and select Save Link As. Save this file somewhere on your desktop ensuring that the file has the .xml file extension. We’ll need the metadata file in the next step.

[In AWS] Add Okta as a third-party Identity Provider

Open new tab and head over to the AWS Console login screen. Enter username, password, and MFA if prompted. Once at the AWS Management Console, head over to IAM by navigating to Services > Security, Identity, & Compliance > IAM (or just search for IAM).

At the IAM Dashboard, select Identity Providers from the left-hand side of the screen. Refrain from noticing how pathetic my AWS account is with so few users and roles.

On the Identity Providers screen, click the button Add Provider. On the Add an Identity Provider screen, ensure that the Provider Type is set to SAML (the default), enter a Provider Name, and then select Choose File, selecting the metadata file you saved right after creating the AWS application in Okta. The Provider Name should be something simple and reflective of your Okta org. I chose Okta, but if you had multiple Okta orgs for different use-cases you could enter something like Okta-Prod. Okta-Dev, etc. When finished, click Add Provider at the bottom of the screen.

This brings you back to the Identity Providers screen where there will now be an Identity Provider with the name you specified in the last step. Click on the name of the Identity Provider to view the Summary information. On this screen, copy the Provider ARN and drop it into a notepad somewhere for future use.

[In AWS] Add new roles using SAML 2.0 Federation

With Okta created as an identity provider, we now need to create roles for use with the federation we’re building. On the left-hand side of the screen, select Roles. On the Roles screen, comment again on the lack of roles in my org and select the Create Role button in the top right-hand side.

On the Select Trusted Entity screen, select the Trusted Entity Type of SAML 2.0 Federation. Below that, select the SAML 2.0-based provider that we just created in the previous step. Select the radio button to “Allow programmatic and AWS Management Console access.” This grays out the Attribute and Value options. Select Next.

On the Add Permissions screen, filter for the permissions that you want to apply to this specific role. As the first role to be federated, I’m going to choose AdministrativeAccess which will provide access to all AWS resources in my account. Filter the policies, select the checkbox next to your policy of choice, and click Next at the bottom of the page.

On the following screen, provide a role name and a description. Click Create Role when finished. I recommend creating a syntax to your role names as this syntax will be used to map Okta group data to the role during federation. I like to use the syntax of <Provider Name>-<Account Alias>-<Role> which can be seen in the screenshot below: Okta-Mueller-Tech-Admin where Okta is the Provider Name, Mueller-Tech is the Account Alias, and Admin is the Role assigned. Once created, this will bring you back to the Roles screen where you’ll be able to see my newly-created third role!

[In AWS] (Optional) Add Okta as a trusted source for existing AWS roles

If you have existing roles that you want to be able to access via federation, you’ll need to edit those roles to allow the Okta Identity Provider to access the role. To do this, click on the role name for one of your existing roles, select the Trust Relationships tab, and click the Edit Trust Policy button.

Note: This is only applicable to those roles associated with logins – not with Service-Linked roles. You’ll notice that I created a new role for my AWS org for the purposes of showing this.

In the Edit Trust Policy screen, you will need to modify the JSON by appending a new statement. The statement effectively says that the federated principal is allowed to assume this role if the SAML audience is from AWS. Alternatively, you can enter the following code starting with the comma on the first line immediately after the last statement in your trust policy. Perform these steps for all other roles that you may have.

,
		{
			"Sid": "Statement1",
			"Effect": "Allow",
			"Principal": {
			    "Federated":"<PASTE YOUR PROVIDER ARN VALUE HERE>"
			},
			"Action": "sts:AssumeRole",
			"Condition": {
			    "StringEquals": {
			        "SAML:aud": "https://signin.aws.amazon.com/saml"
			    }
			}
		}

Note: In the code referenced above, I’ve indicated that you need to paste that trusty Provider ARN that I told you to keep handy in a notepad. In the screenshot, I’ve pasted my own ARN to show you what it should look like.

[In Okta] Create AWS Role Groups

Note: These next few steps are being done in Okta, but they can also be performed in an external directory that is synced to Okta (e.g. Active Directory). Okta recommends performing this specific layout in Active Directory, but my needs for this request only allowed me to work with Okta Universal Directory (which doesn’t support nested groups).

Let’s flip back to Okta Administrator to create some AWS-specific groups. We’ll first create the Role Groups. The idea of Role Groups is that they are associated with the role policies created in AWS. Ideally, you’ll be creating a group for each role policy that exists in AWS for each of your different accounts. There are ways to automate this via scripting, but, as I have so few roles, I’ll be doing this manually.

Okta recommends a specific syntax for the group names to help make identification easier. This is also important for how role mapping functions between directory group and AWS role assignment. The Okta-suggested syntax for group names is: aws#<account_alias>#<role-name>#<account#> which leads to the following example from the work we’ve done so far: aws#Mueller-Tech#Okta-Mueller-Tech-Admin#3###########0

In Okta Administrator, navigate to the Directory drop down and select Groups. On the Groups page, select Add Group.

Enter a group name, give it a description, and click Save. Repeat for all necessary Role Groups.

[In Okta] Create AWS Management Groups

In the last step, we created all of our Role Groups. These will effectively act as different mappings from Okta to the AWS roles for a given user. Management Groups are where user administration for access to the AWS accounts takes place. The idea behind the Management Groups is that each group is for a higher-level role within the company. For example, a member of Mueller-Tech technical support might need multiple different roles assigned to them with various roles per AWS account. For this example, we’ll create another role following the steps from above (Directory > Groups > Add Group > Enter Name/Description > Save) and name the group Support.

Okta doesn’t support nested groups. Instead, we’ll need to use Group Rules to orchestrate how the Management Groups function. We’ll create a Group Rule that effectively says: “If you’re a member of this Management Group, you’ll be assigned to these Role Groups.” In Active Directory, the Management Group would show a list of associated Role Groups in the memberOf tab and the Users themselves would be added to the Management Group.

In the first screenshot below, you’ll see that I’ve already created my two Role Groups and my one Management Group (you will surely have more). More importantly, you’ll see no one in those groups. Click the Rules tab. On the Rules tab, click on Add Rule.

Give the rule a descriptive name, change the Basic Condition drop-down to Group Membership, and then craft the remainder of the rule so that when a user is added to the Management Group, they’re then assigned to however many Role Groups are necessary and click Save.

Once the rule is created, you’ll need to Activate the rule from the Actions drop-down at the right-hand side of the screen.

[In Okta] Configure the AWS application

Enough with the groups for now. Let’s head back to the application and finish the configuration. In Okta Administrator, select Applications > Applications and then click on the AWS application we created in the first step.

In the Application Settings, click on the Sign On tab and select Edit on the right-hand side.

Under the Advanced Sign-on Settings, we’ll want to set the AWS Environment drop-down to Regular AWS, leave ACS URL blank, copy and paste the Identity Provider ARN that I told you to put in notepad earlier, select the box for Join All Roles, and Use Group Mapping. On checking the box for Use Group Mapping, three new fields appear above the Join All Roles checkbox with all fields populated. The only item that needs modification is the Group Filter RegEx. If you followed the Okta-suggested naming convention, the RegEx should be as follows:

^aws\#\S+\#(?{{role}}[\w\-]+)\#(?{{accountid}}\d+)$

If you have changed your syntax, you’ll need to modify the RegEx accordingly. After that’s completed, click Save.

[In Okta] Assign Okta Groups to AWS application

Now that we’ve finished with the App settings, we can assign groups to the application. In the AWS Account Federation application, navigate to the Assignments tab, select Assignments, and select Assign to Groups.

In the Assign windows, click the Assign button next to all groups associated with AWS and then click Done.

[In AWS] Generate AWS API Access Key

We’re nearing the end. Let’s head back over to the AWS Management Console. We need to create an access key to be used in Okta in order to generate a list of roles and accounts a given user is assigned to. Head back into IAM, click Users on the left-hand side, and then click Add Users on the right-hand side.

Give the user an easy to identify username and select the credential type of Access key – Programmatic Access. This user will not be logging into the Management Console. Click Next: Permissions when finished.

On the Set Permissions screen, select Attach existing policies directly, and then select Create policy. This will open a new tab where you can create a new policy.

In the new tab that opens, select the JSON tab. Erase the template JSON and copy/paste the following code block. Click Next: Tags and then click Next: Review.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:ListRoles",
                "iam:ListAccountAliases"
            ],
            "Resource": "*"
        }
    ]
}

On the Review Policy screen, give the policy a descriptive name, enter a description, and press Create Policy. With the policy created, close the tab and move back to the Set Permissions screen for the to-be-created user.

On the Set Permissions screen, click the refresh button to pull in the newly-created policy. Filter the policy by name, select the checkbox next to the policy, click Next: Tags, and click Next: Review. Review the information for accuracy and click Create User. Be prepared to store access key and secret key in notepad.

On the following screen, copy and paste the Access Key ID and Secret Access Key in Notepad for use in the next step.

[In Okta] Enable API Integration

Now that we have some API access keys, let’s head back to Okta Administrator and put them to use. In Okta Administrator, navigate to the AWS Account Federation App to the Provisioning tab. Under the notice “Provisioning is not enabled” click the button Configure API Integration. Afterward, click the checkbox Enable API Integration. This displays four fields to be completed. Enter your Access Key and Secret Key into the proper field and test the API credentials.

[In Okta] Add user to Management Group

We’re nearly ready to test. Let’s add a user to the Management Group. In Okta Administrator, click on the Directory drop down, select Groups, and select one of the Management Groups created earlier in this post. In the Group Summary page, click Assign People, assign someone to the group, and click Save.

Back at the Groups page, we can see that adding a user to the Management Group has populated my other AWS Role Groups with someone as well. Removing the user from the Management Group also removes them from the AWS Role Group. This process can now be tied to other onboarding/offboarding processes and ensure proper account access to AWS.

Testing

With all that work out of the way, it’s time to test! All of my work in AWS so far has been with my root user account. I should now be able to test federated access to my AWS account by clicking the Okta chicklet on my Okta Apps dashboard (where we first started this post!). Let’s see what happens. First, I’ll click on the AWS Account Federation chicklet in my Okta Dashboard.

If you remember earlier, I added both the Role Groups to my Management group. After adding my user account to the Management Group, I’m now presented with a Role Picker directly from Okta! One is the role we created in this post directly as a SAML 2.0 Federated role (Okta-Mueller-Tech-Admin) and the other is the “existing role” that I shadow created for the purposes of editing Trust Relationships in the policy.

After selecting a role and clicking Sign In, I was brought directly to the AWS Management Console where I can begin manipulating AWS however I see fit based on permissions given to me by the Role Groups. You can tell that this is a federated role by checking the top right-hand corner of the screen where AWS typically shows logged-in user information. You can now see it in the form of Federated Role / Federated User (Okta Username) @ (AWS) Account Alias. In the below screenshot, this is Okta-Mueller-Tech-Admin/james@mueller-tech.com @ mueller-tech.

Conclusion

This was a long post, but I hope that it provided some value for you. There’s a lot of information out there about configuring Okta with AWS SSO. That just wasn’t what I needed as none of my accounts use AWS SSO. I spent many hours searching through Okta and AWS documentation as well as others’ blog posts. I decided to write this post because I couldn’t find a post that had everything that I needed and showed every step – I hope this does justice. That said, I recognize that I’m standing on the shoulders of giants!

Reference posts:
Integrating Okta to allow Federated Users to access multi-account AWS environment – Vinod Kumar Nair
The Un-documented Way to Setup AWS SSO with Okta – Tom King
How to Configure SAML 2.0 for AWS Account Federation – Usama Azad
Connect Okta to a Single AWS Instance – Vasanth Selvaraj

Thanks for reading!