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.
Steps
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
Create external identity provider in AWS
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 Auth0 Application
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
andAWS_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?/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.
Complete AWS identity provider configuration
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.
Create AWS IAM role
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.
Map AWS role to a user
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);
}
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',
};
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 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);
}
Configure session expiration
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.
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 setup
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.