Configure Amazon Web Services for SSO

By integrating Auth0 with AWS, you'll allow your users to log in to AWS using any supported identity provider.

Create an external identity provider in AWS
Configure the SAML2 Web App add-on for your Auth0 Application
Complete AWS identity provider configuration
Create an AWS IAM role
Map the AWS role to a user

Set up an external identity provider in AWS using AWS's Connect to your External Identity Provider guide--with one slight change. Rather than downloading the AWS metadata file, click Show Individual Metadata Values, and copy the AWS SSO issuer URL and AWS SSO ACS URL values. You will use these in the next section.

Leave this page open in your browser because you'll need to complete configuration in a future section.

Configure the SAML2 Web App add-on for your application using the Auth0 Dashboard.

Go to Auth0 Dashboard > Application, and create a new application (or click the name of an application to update).
Click the Addons tab, and enable the SAML2 Web App add-on using the toggle switch if it is not already enabled.

The Settings window appears.

Set the Application Callback URL to:
https://signin.aws.amazon.com/saml

Paste the following code into Settings, and click Enable. Be sure to replace the AWS_SSO_ISSUER_URL and AWS_SSO_ACS_URL placeholders with values you copied from AWS.

{
  "audience": "AWS_SSO_ISSUER_URL",
  "destination": "AWS_SSO_ACS_URL",
  "mappings": {
    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
  },
  "createUpnClaim": false,
  "passthroughClaimsWithNoMapping": false,
  "mapUnknownClaimsAsIs": false,
  "mapIdentities": false,
  "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "nameIdentifierProbes": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  ]
}

Was this helpful?/

Integrations - AWS SSO - Configure Auth0 SAML Add-on

Click the Usage tab, locate Identity Provider Metadata, and download the metadata file. You'll need this when you configure Auth0 as the identity provider (IdP) for AWS.

Return to the open AWS SSO identity provider page in your browser, and upload the metadata file you downloaded and saved in the previous section. Review and Confirm that you are changing the identity source.

To use the provider, you must create an IAM role using the provider in the role's trust policy.

In the sidebar, under Access Management, navigate to Roles. Click Create Role.
On the next page, you will be asked to select the type of trusted entity. Select SAML 2.0 Federation.
When prompted, set the provider you created above as the SAML provider. Select Allow programmatic and AWS Management Console access. Click Next to proceed.
On the Attach Permission Policies page, select the appropriate policies to attach to the role. These define the permissions that users granted this role will have with AWS. For example, to grant your users read-only access to IAM, filter for and select the IAMReadOnlyAccess policy. Once you are done, click Next Step.
The third Create Role screen is Add Tags. You can use tags to organize the roles you create if you will be creating a significant number of them.
On the Review page, set the Role Name and review your settings. Provide values for the following parameters:

Parameter Definition

Role name Descriptive name for your role.

Role description Description of what your role is used for.
Review the Trusted entities and Policies information, then click Create Role.

Parameter	Definition
Role name	Descriptive name for your role.
Role description	Description of what your role is used for.

To see an example of defining a server-side rule that assigns a role in an advanced use case, see the Amazon API Gateway tutorial.

The AWS roles specified will be associated with an IAM policy that enforces the type of access allowed to a resource, including the AWS Consoles. To learn more about roles and policies, see Creating IAM Roles.

To map an AWS role to a user, you'll need to create a rule:

function (user, context, callback) {

  user.awsRole = 'arn:aws:iam::951887872838:role/TestSAML,arn:aws:iam::951887872838:saml-provider/MyAuth0';
  user.awsRoleSession = user.name;

  context.samlConfiguration.mappings = {
    'https://aws.amazon.com/SAML/Attributes/Role': 'awsRole',
    'https://aws.amazon.com/SAML/Attributes/RoleSessionName': 'awsRoleSession'
  };

  callback(null, user, context);

}

Was this helpful?/

In the code snippet above, user.awsRole identifies the AWS role and the IdP. The AWS role identifier comes before the comma, and the IdP identifier comes after the comma.

Your rule can obtain these two values in multiple ways. You can get these values from the IAM Console by selecting the items you created in AWS in the previous steps from the left sidebar. Both the Identity Provider and the Role you created have an ARN available to copy if you select them in the Console.

In the example above, both of these values are hard-coded into the rule. Alternatively, you might also store these values in the user profile or derive them using other attributes. For example, if you're using Active Directory, you can map properties associated with users, such as group to the appropriate AWS role:

var awsRoles = {
  'DomainUser': 'arn:aws:iam::951887872838:role/TestSAML,arn:aws:iam::95123456838:saml-provider/MyAuth0',
  'DomainAdmins': 'arn:aws:iam::957483571234:role/SysAdmins,arn:aws:iam::95123456838:saml-provider/MyAuth0'
};
user.awsRole = awsRoles[user.group];
user.awsRoleSession = user.email;

context.samlConfiguration.mappings = {
  'https://aws.amazon.com/SAML/Attributes/Role': 'awsRole',
  'https://aws.amazon.com/SAML/Attributes/RoleSessionName': 'awsRoleSession',
};

Was this helpful?/

You can also assign an array to the role mapping (so you'd have awsRoles = [ role1, role2 ] instead of awsRoles: role1)

For example, let's say that you have Active Directory Groups with the following structure:

var user = {
  app_metadata: {
    ad_groups: {
      "admins": "some info not aws related",
      "aws_dev_Admin": "arn:aws:iam::123456789111:role/Admin,arn:aws:iam::123456789111:saml-provider / Auth0",
      "aws_prod_ReadOnly": "arn:aws:iam::123456789999:role/ReadOnly,arn:aws:iam::123456789999:saml-provider / Auth0"
    }
  }
};

Was this helpful?/

Your rule might therefore looking something like this:

function (user, context, callback) {

  var userGroups = user.app_metadata.ad_groups;

  function awsFilter(group) {
    return group.startsWith('aws_');
  }

  function mapGroupToRole(awsGroup) {
    return userGroups[awsGroup];
  }

  user.awsRole = Object.keys(userGroups).filter(awsFilter).map(mapGroupToRole);
  user.awsRoleSession = 'myawsuser'; // unique per user http://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html

  context.samlConfiguration.mappings = {
    'https://aws.amazon.com/SAML/Attributes/Role': 'awsRole',
    'https://aws.amazon.com/SAML/Attributes/RoleSessionName': 'awsRoleSession'
  };

  callback(null, user, context);

}

Was this helpful?/

If you want to extend the amount of time allowed to elapse before the AWS session expires (which is, by default, 3600 seconds), you can do so using a custom rule. Your rule sets the SessionDuration attribute that changes the duration of the session.

function (user, context, callback) {
    if(context.clientID !== 'YOUR_CLIENT_ID_HERE'){
      return callback(null, user, context);
    }

  user.awsRole = 'YOUR_ARN_HERE';
  user.awsRoleSession = 'YOUR_ROLE_SESSION_HERE';
  user.time = 1000; // time until expiration in seconds

  context.samlConfiguration.mappings = {
    'https://aws.amazon.com/SAML/Attributes/Role': 'YOUR-AWS-ROLE-NAME',
    'https://aws.amazon.com/SAML/Attributes/RoleSessionName': 'YOUR-AWS-ROLE-SESSION-NAME',
    'https://aws.amazon.com/SAML/Attributes/SessionDuration': 'time'   };

  callback(null, user, context);
}

Was this helpful?/

You are now set up for Single Sign-on (SSO) to AWS and can test your setup.

Go to Auth0 Dashboard > Application, and click the name of your application.
Click the Addons tab, and select the SAML2 Web App add-on.
Click the Usage tab.
Navigate to the Identity Provider Login URL. You should be redirected to the Auth0 sign in page. If you successfully sign in, you'll be redirected again--this time to AWS.

Docs

Configure Amazon Web Services for SSO

Configure Amazon Web Services for SSO

Steps

Create external identity provider in AWS

Configure Auth0 Application

Complete AWS identity provider configuration

Create AWS IAM role

Map AWS role to a user

Map multiple roles

Configure session expiration

Test setup

Was this article helpful?