aws-runas
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.
Browser New Experience Provider
The browsene provider allows for aws-runas to open a new tab for the default browser connected to aws-runas through a local webserver that will recieved the SAMLResponse from the IDP. This is accomplished by having aws-runas act as a SP and making the SAMLRequest with the Assertion Consummer Service of http://localhost:
To use the browser provider update the $HOME/.aws/config file to include the following configurations.
saml_auth_url = https://saml.provider.com/<saml endpoint>
saml_entity_id = https://signin.aws.amazon.com/saml
saml_provider=browserne
saml_auth_url is the URL where you would make a SAMLRequest. This provider was built and tested with MS EntraID so this would appear as below. This should work with other SAML IDP’s but, has not been tested.
saml_auth_url = https://login.microsoftonline.com/<Tenant ID>/saml2
saml_entity_id is used to identity the application used to return the SAMLResponse from the request. This will often be the same as the AWS SAML end-point for sign-in but, could include and html anchor marker and a numeric component.
saml_entity_id = http://signin.aws.amazon.com/saml
saml_provider is set to be browserne for the new experience. The legacy ChromeDP provider is still available for backward compatibility.
The new experience creates a localhost listener on a random port that acts as the ACS URL waiting for the SAMLResponse payload. One this payload is recieved the user is notified via the browser of successfully retreiving the SAMLResponse. After the response is recieved the SAMLResponse is used to authenticate to AWS and the local web listener is stopped.
Important Role Trust Policy Changes Required.
Due to the way that the SAMLResponse is delivered to the browser via a localhost listener there is a required update to the roles trust policy to allow for the delivery of the SAMLResponse.
A typical trust policy for a role with SSO integration will have a policy statement that looks similar to below with a conditional statement for the saml:aud which allows a specific Recipient in the response. This is almost always :
Typical Role Trust Policy.
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::<Account ID>:saml-provider/<Provider Name>
},
"Action": "sts:AssumeRoleWithSAML",
"Condition": {
"StringEquals": {
"SAML:aud": "https://signin.aws.amazon.com/saml"
}
}
},
Required Trust for the Browser New Experience.
The browserne provider creates the SAMLRequest with the ACS URL set to be a random port on http://localhost to recieve the SAMLResponse. Due to this the Recipient in the response will match the ACS URL and this is what the saml:uad field is set to for policy evaluation.
```
{
“Effect”: “Allow”,
“Principal”: {
“Federated”: “arn:aws:iam::
** Note: The browserne provider has only be tested with MS EntraID but, will likely work with other IDP’s.