AWS SSO, Okta Universal Directory, and OpenLDAP by Example

A walk-through of setting up AWS SSO backed by Okta Universal Directory (and OpenLDAP).

In this article, we walk through the steps involved in using AWS Single Sign-On (AWS SSO).

AWS Single Sign-On (AWS SSO) is where you create, or connect, your workforce identities in AWS once and manage access centrally across your AWS organization. You can choose to manage access just to your AWS accounts or cloud applications. You can create user identities directly in AWS SSO, or you can bring them from your Microsoft Active Directory or a standards-based identity provider, such as Okta Universal Directory or Azure AD. With AWS SSO, you get a unified administration experience to define, customize, and assign fine-grained access. Your workforce users get a user portal to access all of their assigned AWS accounts, Amazon EC2 Windows instances, or cloud applications. AWS SSO can be flexibly configured to run alongside or replace AWS account access management via AWS IAM.

— AWS Single Sign-On

Where AWS SSO identities are brought in from Okta Universal Directory.

One directory for all your users, groups, and devices

Okta Universal Directory provides a single view across all these groups with AD and LDAP directory integrations and out-of-the-box connections with HR systems like Workday, SaaS apps like G Suite, CSV files, and third-party identity providers.

— Universal Directory

With Okta Universal Directory integrated with OpenLDAP.

The OpenLDAP Project is a collaborative effort to develop a robust, commercial-grade, fully featured, and open source LDAP suite of applications and development tools.

— The OpenLDAP Project Overview

The Lightweight Directory Access Protocol (LDAP /ˈɛldæp/) is an open, vendor-neutral, industry standard application protocol for accessing and maintaining distributed directory information services over an Internet Protocol (IP) network.[1] Directory services play an important role in developing intranet and Internet applications by allowing the sharing of information about users, systems, networks, services, and applications throughout the network.

— Lightweight Directory Access Protocol

Please note: For simplicity here, we are using OpenLDAP in lieu of more common directory solutions; however, the same concepts apply.

If one is looking to follow along, one will need a DNS domain, or sub-domain, and five distinct email addresses in it:

• AWS bootstrap, e.g., example-aws@larkintuckerllc.com
• Okta admin, e.g., john@larkintuckerllc.com (wanted to use example-okta@larkintuckerllc.com but already used john@larkintuckerllc.com)
• AWS log archive: e.g., example-aws-log-archive@larkintuckerllc.com
• AWS audit, .e.g., example-aws-audit@larkintuckerllc.com
• Developer, e.g., example-developer@larkintuckerllc.com

OpenLDAP

We begin by installing the OpenLDAP server on an Internet connected (only outbound connectivity is required) compatible platform machine; in this article, we use a Google Compute Engine (GCE) Instance running Ubuntu 20.04 LTS.

Once connected to the Instance, we install the OpenLDAP server by executing:

$ sudo -i
# apt update
# apt install slapd ldap-utils

We next configure the OpenLDAP server by executing:

# dpkg-reconfigure slapd

We accept the defaults other than providing:

• Base DNS name; in my case larkintuckerllc.com
• Organization name: in my case Larkin & Tucker, LLC
• (LDAP) Administrator password

Next we use the following commands, once per file, to populate the OpenLDAP server; replacing larkintuckerllc as appropriate, ADMINISTRATOR_PASSWORD with the LDAP administrator password, and FILE with the file.

$ ldapadd \
-x \
-D "cn=admin,dc=larkintuckerllc,dc=com" \
-w "ADMINISTRATOR_PASSWORD" \
-f FILE

We first create the people and groups organizational units, to hold people and groups of people respectively; replacing larkintuckerllc as appropriate:

We create our first person; the administrator that we will use to bootstrap AWS; here we need to use a valid email address and replacing larkintuckerllc as appropriate:

We provide this user with a password , e.g., replacing larkintuckerllc as appropriate, ADMINISTRATOR_PASSWORD with the LDAP administrator password, and the -S option with the person’s dn. The command will prompt us to provide the user a password.

$ ldappasswd \
-x \
-D "cn=admin,dc=larkintuckerllc,dc=com" \
-w "ADMINISTRATOR_PASSWORD" \
-S "uid=example-aws,ou=people,dc=larkintuckerllc,dc=com"

Okta Universal Directory

We next create an Okta Workforce Identify account using a different email, in my case jtucker@larkintuckerllc.com (wanted to use example-okta@larkintuckerllc.com but already used john@larkintuckerllc.com).

We now integrate Okta Universal Directory with our OpenLDAP server by using the Okta Admin Console and navigating to the Directory > Directory Integrations screen; we press the Add LDAP Directory button.

Following the setup wizard, the first step is to download the Okta LDAP Agent to the OpenLDAP server using the URL provided, e.g., in my case:

#  wget https://larkintuckerllc-admin.okta.com/static/ldap-agent/OktaLDAPAgent-05.10.00_amd64.deb

The Okta LDAP Agent acts a pass-through between Okta and the OpenLDAP server.

We install and configure the Okta LDAP Agent:

# dpkg -i OktaLDAPAgent-05.10.00_amd64.deb
# /opt/Okta/OktaLDAPAgent/scripts/configure_agent.sh

We provide configuration values to the script:

• Okta Base URL , in my case https://larkintuckerllc.okta.com
• LDAP server hostname: localhost
• LDAP admin DN: cn=admin,dc=larkintuckerllc,dc=com
• LDAP admin password: The LDAP administrator password
• Base DN, in my case, dc=larkintuckerllc,dc=com
• Use SSL: n
• LDAP server port: 389
• Enable proxy: n

The script provides a URL that we navigate to; continuing the configuration.

The next step in the wizard is to configure the directory mappings:

• LDAP Version: OpenLDAP (sets many default values for us)
• User Search Base: in my case, ou=people,dc=larkintuckerllc,dc=com
• Group Search Base: in my case, ou=groups,dc=larkintuckerllc,dc=com
• Okta username format: User Id (UID)@Domain
• Example username: in my case, example-aws@larkintuckerllc.com

Press the Test Configuration button; we should see a successful validation. We now complete the configuration.

We now navigate to the Directory > Directory Integrations screen; select LDAP button and Import tab. We then press the Import Now button. We check the checkbox next to the single user and press the Confirm Assignments button.

Finally, we navigate to Directory > People and press the Activate button on the AWS Admin person.

Please note: Undoubtedly, this import process can be automated.

Create AWS Account

We now create a new AWS account using the AWS bootstrap email, in my case example-aws@larkintuckerllc.com.

Setup AWS SSO

The easiest way of setting up AWS SSO (includes AWS Organizations) is to use AWS Control Tower.

If you have multiple AWS accounts and teams, cloud setup and governance can be complex and time consuming, slowing down the very innovation you’re trying to speed up. AWS Control Tower provides the easiest way to set up and govern a secure, multi-account AWS environment, called a landing zone. It creates your landing zone using AWS Organizations, bringing ongoing account management and governance as well as implementation best practices based on AWS’s experience working with thousands of customers as they move to the cloud. Builders can provision new AWS accounts in a few clicks, while you have peace of mind knowing that your accounts conform to company policies.

— AWS Control Tower

From the AWS Management Console, we search for Control Tower and then press the Set up Landing Zone button. We can leave the default values except for:

• Log archive email: e.g., example-aws-log-archive@larkintuckerllc.com
• Audit email, .e.g., example-aws-audit@larkintuckerllc.com

As a part of the setup, we need to act on the AWS Organizations email verification request and the email invitation to join AWS SSO.

At this point, we can login into the AWS SSO User Portal using the AWS bootstrap email address and a newly created AWS SSO password, in my case example-aws@larkintuckerllc.com.

Single Sign-On Between Okta Universal Directory and AWS

While we have gotten AWS SSO working, our goal is to use our Okta identity (imported from OpenLDAP) to login to AWS. Luckily AWS has an appropriately named article, Single Sign-On between Okta Universal Directory and AWS, that walks one through the process to accomplish this.

Please note: While the screens are somewhat different than the article and the process is fairly lengthy, the process does indeed work.

If all goes well, we can now login to our Okta homepage, in my case https://larkintuckerllc.okta.com, using the AWS bootstrap email, in my case example-aws@larkintuckerllc.com; the password is what we set in the OpenLDAP section.

Clicking on the AWS Single Sign-on button passes us through to the AWS SSO User Portal as before.

Please note: At this point, there is one thing that does not make sense; the Groups in AWS SSO, e.g., AWSAccountFactory, are not editable as they are configured as External identity provider. At the same time, the same Groups were automatically created in Okta but are not editable as they are managed automatically by Okta. Seem to be stuck in some sort of loop here. Will revisit later.

Creating a Developer and Developers Group

Now that we have everything in place, let us go through the exercise of creating a developer and a developers group; giving them read only access to all accounts.

As we did earlier, we first create the person and group resources in OpenLDAP.

$ ldapadd \
-x \
-D "cn=admin,dc=larkintuckerllc,dc=com" \
-w "ADMINISTRATOR_PASSWORD" \
-f FILE

We also set a password for the person.

$ ldappasswd \
-x \
-D "cn=admin,dc=larkintuckerllc,dc=com" \
-w "ADMINISTRATOR_PASSWORD" \
-S "uid=example-developer,ou=people,dc=larkintuckerllc,dc=com"

From the Okta Admin Console, we import the person and group using the menu Directory > Directory Integrations > LDAP > Import > Import Now. We Confirm the Assignment and Activate the person.

Next, as we want all developers to have access to the Okta AWS Single Sign-on application, we assign it to the developers group; menu Directory > Groups > developers > Applications. At this point, the developer appears in the AWS SSO configuration.

At this point, however, the developer has no access to any AWS accounts; let us remedy this.

From the Okta Admin Console, we use the following menu to push the developers group to AWS SSO; Applications > AWS Single Sign-on > Push Groups > Push Groups > Find groups by name.

At this point the developer group is visible in AWS SSO.

The last step is to then to grant the AWSReadyOnlyAccess Permission Set to the developers group using the menu; AWS SSO > AWS accounts > Assign users > Groups.

At this point we can login to our Okta homepage, in my case https://larkintuckerllc.okta.com, using the developer email, in my case example-developer@larkintuckerllc.com; the password is what we set in the OpenLDAP step above. Clicking on the AWS Single Sign-on button passes us through to the AWS SSO User Portal with the proper authorization.

Revisiting the AWSAccountFactory (and Others) Group

It turns out that one can fix the automatically created groups in Okta Admin Console by repeated the process we used to create the developers group, i.e., create and populate group in OpenLDAP, import it into Okta Admin Console, and then push it to AWS SSO. Here we have fixed the two groups that had members: AWSAccountFactory and AWSControlTowerAdmins.

The one sidebar here is that if you need to modify an OpenLDAP group; do not delete and recreate the group but rather modify it. For example, here is how to add the developer to the AWSControlTowerAdmins group:

$ ldapmodify -x -D "cn=admin,dc=larkintuckerllc,dc=com" -w "ADMINISTRATOR_PASSWORD" -f modify.ldif

with this file.

Wrap Up

Wow; this was a lot more complex that I imagined it would be.