Configure Amazon Web Services for Single Sign-On

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

To configure AWS for SSO, you need to complete the following steps:

  1. Create an external identity provider in AWS.

  2. Configure the SAML2 Web App addon for your Auth0 application.

  3. Complete AWS identity provider configuration.

  4. Create an AWS IAM role.

  5. Map the AWS role to a user.

Create an external identity provider in AWS

  1. Set up an external identity provider in AWS using AWS's Connect to your External Identity Provider guide with one change.

    1. Rather than downloading the AWS metadata file, click Show Individual Metadata Values.

    2. Copy the AWS SSO issuer URL and AWS SSO ACS URL values. You will use these in the next section.

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

Configure SAML SSO for Auth0

Configure the SAML2 Web App add-on for your application using the Auth0 Dashboard. To learn how, read Configure Auth0 as Identity Provider for Amazon Web Services.

Complete AWS identity provider configuration

  1. Return to the open AWS SSO identity provider page in your browser.

  2. Upload the metadata file you downloaded and saved in the previous section.

  3. Review and Confirm that you are changing the identity source.

Create AWS IAM role

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

  1. In the sidebar, under Access Management, navigate to Roles. Click Create Role.

  2. On the next page, you will be asked to select the type of trusted entity. Select SAML 2.0 Federation.

  3. When prompted, set the provider you created above as the SAML provider. Select Allow programmatic and AWS Management Console access. Click Next to proceed.

  4. 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.

  5. 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.

  6. On the Review page, set the Role Name and review your settings. Provide values for the following parameters:

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

  7. Review the Trusted entities and Policies information, then click Create Role.

Map AWS role to a user

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, read Creating IAM Roles.

  1. To map an AWS role to a user, 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);
    
    }
    
    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.

    1. 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.

    2. 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',
      };
      

Map multiple roles

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"
    }
  }
};

Your rule might therefore look 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);

}

Configure session expiration

To extend the amount of time allowed to elapse before the AWS session expires (3600 seconds), use a custom rule. Your rule sets the SessionDuration attribute that changes the duration of the session.

to configure this snippet with your account

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);
}

Test configuration

  1. Go to Dashboard > Applications > Applications and click the name of your application.

  2. On the Addons tab, select the SAML2 Web App add-on.

  3. On the Usage tab, locate the Identity Provider Login URL. You should be redirected to the Auth0 account login page. If you successfully log in, you'll be redirected to AWS.

Learn more