aws-runas A friendly way to assume roles in AWS View on Github View on Github

SAML Client Configuration Guide

aws-runas works with many identity providers which offer SSO integration with AWS via SAML 2.0. The sections below will describe the specific configuration needed to work with each supported provider. Many details specific to your instance of the identity provider (like the URL) must be shared with you by your identity platform administrators.

If a particular SAML identity provider is not listed here, and you would like to see it added to aws-runas, create a new github issue and let us know.

In all the examples below, the saml_provider configuration attribute is optional, and can be used to bypass the client auto-detection logic.

Forgerock

Forgerock is a self-hosted identity management platform, so the details may vary based on the configuration of your specific implementation of the Forgerock product. The aws-runas SAML client auto-discovery logic performs an HTTP HEAD against the URL and looks for either X-OpenAM- or MFA-FR-Token in the Access-Control-Allow-Headers response header.

Example Forgerock info in the .aws/config file:

saml_auth_url = https://my-forgerock-hostname.com/auth/json/realms/__the-realm__/authenticate
saml_provider = forgerock

Keycloak

Keycloak is a self-hosted identity management platform, so the details may vary based on the configuration of your specific implementation of the Keycloak product. The aws-runas SAML client auto-discovery logic performs an HTTP HEAD against the URL and looks for a cookie called KC_RESTART in the response.

Example Keycloak info in the .aws/config file:

saml_auth_url = https://my-keycloak-hostname.com/auth/realms/__the-realm__/protocol/saml/clients/__client_name__
saml_provider = keycloak

Microsoft Azure AD

Microsoft Azure AD (AAD) is a commercial identity management service which provides the necessary infrastructure and services to integrate with numerous 3rd party applications. The ‘User Access URL’ found in the Properties screen of the Azure Enterprise Application used for granting access to the AWS role is used for the value of the saml_auth_url. The aws-runas SAML client auto-discovery logic looks for .microsoft.com in the hostname portion of the URL.

Example Azure AD info in the .aws/config file:

saml_auth_url = https://myapps.microsoft.com/signin/__app-name__/__app-id__?tenantId=__tenant-id__
saml_provider = azuread

The Azure AD client is also configured to allow “guest” account access (which federates the authentication of an Azure AD principal with an external identity provider). The big caveat being that the external identity provider must be supported by aws-runas. If the AAD username of the guest user matches the username configured in the federated identity provider, no additional configuration is required. If the username is different between AAD and the external identity provider, you can set the federated_username attribute in the profile to the value of the username in the external identity provider. The following example shows how this might be configured:

saml_auth_url = https://myapps.microsoft.com/signin/__app-name__/__app-id__?tenantId=__tenant-id__
saml_provider = azuread
saml_username = azure-username
federated_username = external-idp-username

Okta

Okta is a commercial identity management service which provides the necessary infrastructure and services to integrate with numerous 3rd party applications. The ‘App Embed Link’ for the AWS Okta application is used for the URL in the configuration. The aws-runas SAML client auto-discovery logic looks for .okta.com in the hostname portion of the URL.

Example Okta info in the .aws/config file:

saml_auth_url = https://my-okta-hostname.okta.com/home/amazon_aws/__okta_app_id__/__other_part__
saml_provider = okta

Additionally, as of the 3.1.3 release, the Okta provider supports integration with Duo MFA using push or code based verification. No special configuration of aws-runas is required, and you select the MFA method used with Duo using the same mfa_type attribute set in the profile section of the config file as you would with other identity providers. The only caveat is that aws-runas assumes Duo MFA is the only MFA factor configured for the user, so if an Okta user enrolls a Duo MFA factor it will be used regardless of any other MFA factors configured.

OneLogin

OneLogin is a commercial identity management service which provides the necessary infrastructure and services to integrate with numerous 3rd party applications. The aws-runas SAML client auto-discovery logic looks for .onelogin.com in the hostname portion of the URL.

The OneLogin platform requires the use of application-level authentication for interacting with any portion of their API (even for authenticating public/untrusted apps). This requires your OneLogin admins to create a set of API credentials which can be shared as they see fit to allow aws-runas the ability to communicate with the OneLogin API. The OneLogin API credentials will be a Client ID and Client Secret, which are added as the query string parameter token to the OneLogin URL in the .aws/config file. This is an aws-runas specific configuration, and not supported as part of interacting with the OneLogin API. The format of the token parameter is the base64 encoding of the Client ID and Client Secret values joined with a : between them. If you have access to a MacOS or Linux system, the following command can be used to generate the necessary value:

echo -n 'client_id:client_secret' | base64

Substituting client_id and client_secret with your actual values, of course. On some Linux systems you may need to add the -w0 flag to the base64 command to disable text wrapping.

Example OneLogin info in the .aws/config file:

saml_auth_url = https://my-onelogin-hostname.com/trust/saml2/launch/__app_id__?token=Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
saml_provider = onelogin

The app-id value can be found on the user’s application landing page, hovering over the OneLogin AWS Application, and getting the last element in the URL path.

Browser Provider

The browser provider allows for aws-runas to spawn an external browser connected to aws-runas using the Chrome Developer Protocol CDP. This allows the user to authenticate through a browser in situations where there isn’t a well defined API or where the authentication flow is fluid. AzureAD using policies that leverage tools like inTune, the use of client certificates or other security measures that have these characteristics.

To use the browser provider update the $HOME/.aws/config file to include the following configurations.

saml_auth_url = https://myapps.microsoft.com/signin/__app-id__/?tenantId=__tenant-id__
saml_provider=browser
auth_browser=[chrome|msedge] (optional defaults to chrome)

This will cause the browser to create a new hidden directory in the $HOME/.aws/.browser/ that will store the browsers configuration and profile. Inside of this browser data-directory a profile directory aws-runas will be created to store the specific session information for the browser.

Once the browser is started, the user is in control of the authentication session that through the browser. aws-runas will examine the browser events looking for the return of a SAMLResponse=xxxx. Once this is found aws-runas will capture the SAMLResponse, close the browser session and use it in the same way that other providers do.

There is no way to use the existing browser SSO information since a normal browser session isn’t started with a CDP enabled browser so aws-runas will not be able to monitor events and retrieve the SAML response.

This provider has only been tested with AzureAD but, should work for any other provider.