Secure Access Tokens with AWS and Single Sign-On

At Earnest, we’re big fans of single sign-on (SSO). SSO is great because it provides a single set of authentication credentials to access multiple services. Administrators can easily assign (and take away) access to services and enhance security by requiring multi factor authentication challenges for services that don’t have such. If it’s a service someone at Earnest uses, we want it covered via SSO.

We’re also avid users of Amazon Web Services. AWS provides a SAML 2.0 identity system that ties in nicely with our SSO needs. It works as expected for the web console — allowing our team to log in directly from their SSO dashboard without a second set of credentials.

However, folks on our team often find themselves needing to do more than just access AWS via the web console. Tools like the AWS CLI, Terraform or our own applications need to authenticate as well. Traditional IAM Users have the ability to generate access tokens for these purposes. Unfortunately, SAML-based SSO logins are done via Roles — and you can’t generate access tokens for a Role.

We found ourselves with a question. How can we combine the benefits of SAML-based SSO with the need for access tokens? Amazon’s answer is the AWS Security Token Service.

The Security Token Service allows you to authenticate via a SAML provider and request a short-lived access token that can be used wherever you might typically use an IAM access token. The security benefits here are great.

  • STS tokens are only valid for a maximum of one hour. This reduces surface area in cases where a key is compromised.
  • Authentication and authorization are performed using your SAML identity provider and provisioned roles. You get all the same provisioning/de-provisioning benefits.
  • Support for multi-factor authentication challenges.

All we needed to do was integrate our SAML-based SSO provider (Okta) with the AWS API. Amazon provides a few examples of this online, but do to technical challenges neither worked properly with Okta. So, we expanded the general idea to support Okta (with multi-factor authentication via TOTP).

The result is a user-friendly CLI for authenticating, generating an STS access token, and updating your local environment within seconds. It’s a big security enabler

Generating AWS STS tokens via Okta SSO

How it Works

The process of authenticating with Okta (and many SAML SSO providers) is only possible via form-based authentication. We’re using headless browser automation (via the excellent Nightmare) to emulate a form-based sign-on.

  1. Prompt user for SSO-provider username and password
  2. Use a headless browser to navigate to the login page and submit the credentials
  3. Prompt for a TOTP token
  4. Use the headless browser to submit the TOTP token
  5. Parse the response from Amazon to extract the SAML assertion
  6. Present accessible roles to the user (if more than one) and allow them to select the role to assume
  7. Use the STS API to assume the role
  8. Save the token information to the AWS credentials file

We’ve open sourced our token generator. It supports assuming an AWS role and will automatically update your AWS credentials file with the new credentials. If even assumes roles across multiple AWS accounts if this is something your organization does.

At the moment, authentication is only implemented for Okta. But, adding support for other SSO providers should be straightforward. Please submit a pull request if you add support for your own.


Do you like enabling security via friendly command line utilities? We’re hiring and would love to meet you!