> ## Documentation Index
> Fetch the complete documentation index at: https://docs-staging.auth0-mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

> Learn how to configure single sign-on (SSO) for Auth0 with Amazon Web Services (AWS).

# Configure Amazon Web Services for Single Sign-On

export const AuthCodeBlock = ({filename, icon, language, highlight, children}) => {
  const [displayText, setDisplayText] = useState(children);
  const [copyText, setCopyText] = useState(children);
  const wrapperRef = React.useRef(null);
  useEffect(() => {
    let unsubscribe = null;
    function init() {
      if (!window.autorun || !window.rootStore) {
        return;
      }
      unsubscribe = window.autorun(() => {
        let processedChildrenForDisplay = children;
        let processedChildrenForCopy = children;
        for (const [key, value] of window.rootStore.variableStore.values.entries()) {
          const escapedKey = key.replaceAll(/[.*+?^${}()|[\]\\]/g, (String.raw)`\$&`);
          let displayValue = value;
          if (key === "{yourClientSecret}" && value !== "{yourClientSecret}") {
            displayValue = value.substring(0, 3) + "*****MASKED*****";
          }
          processedChildrenForDisplay = processedChildrenForDisplay.replaceAll(new RegExp(escapedKey, "g"), displayValue);
          processedChildrenForCopy = processedChildrenForCopy.replaceAll(new RegExp(escapedKey, "g"), value);
        }
        setDisplayText(processedChildrenForDisplay);
        setCopyText(processedChildrenForCopy);
      });
    }
    if (window.rootStore) {
      init();
    } else {
      window.addEventListener("adu:storeReady", init);
    }
    return () => {
      window.removeEventListener("adu:storeReady", init);
      unsubscribe?.();
    };
  }, [children]);
  useEffect(() => {
    if (!wrapperRef.current) return;
    const originalWriteText = navigator.clipboard.writeText.bind(navigator.clipboard);
    let isOverriding = false;
    const handleClick = e => {
      const button = e.target.closest('[data-testid="copy-code-button"]');
      if (!button || !wrapperRef.current.contains(button)) return;
      isOverriding = true;
      navigator.clipboard.writeText = text => {
        if (isOverriding) {
          isOverriding = false;
          navigator.clipboard.writeText = originalWriteText;
          return originalWriteText(copyText);
        }
        return originalWriteText(text);
      };
      setTimeout(() => {
        if (isOverriding) {
          isOverriding = false;
          navigator.clipboard.writeText = originalWriteText;
        }
      }, 100);
    };
    const wrapper = wrapperRef.current;
    wrapper.addEventListener('click', handleClick, true);
    return () => {
      wrapper.removeEventListener('click', handleClick, true);
      if (navigator.clipboard.writeText !== originalWriteText) {
        navigator.clipboard.writeText = originalWriteText;
      }
    };
  }, [copyText]);
  return <div ref={wrapperRef}>
      <CodeBlock filename={filename} icon={icon} language={language} lines highlight={highlight}>
        {displayText}
      </CodeBlock>
    </div>;
};

By integrating Auth0 with AWS, you'll allow your users to log in to AWS using any supported <Tooltip tip="Identity Provider (IdP): Service that stores and manages digital identities." cta="View Glossary" href="/docs/glossary?term=identity+provider">identity provider</Tooltip>.

To configure AWS for <Tooltip tip="Single Sign-On (SSO): Service that, after a user logs into one applicaton, automatically logs that user in to other applications." cta="View Glossary" href="/docs/glossary?term=SSO">SSO</Tooltip>, 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](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html) 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 <Tooltip tip="Auth0 Dashboard: Auth0's main product to configure your services." cta="View Glossary" href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. To learn how, read [Configure Auth0 as Identity Provider for Amazon Web Services](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-aws).

## 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**](https://console.aws.amazon.com/iam/home#/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

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  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](/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-5).
</Callout>

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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html).

1. To map an AWS role to a user, create a [rule](/docs/customize/rules):

   ```javascript lines theme={null}
   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:

      ```text lines theme={null}
      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:

```javascript lines theme={null}
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:

```javascript lines theme={null}
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](/docs/customize/rules). Your rule sets the [**SessionDuration** attribute](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html) that changes the duration of the session.

export const codeExample = `function (user, context, callback) {
    if(context.clientID !== '{yourClientId}'){
      return callback(null, user, context);
    }

  user.awsRole = '{yourArn}';
  user.awsRoleSession = '{yourRoleSession}';
  user.time = 1000; // time until expiration in seconds

  context.samlConfiguration.mappings = {
    'https://aws.amazon.com/SAML/Attributes/Role': '{yourAwsRoleName}',
    'https://aws.amazon.com/SAML/Attributes/RoleSessionName': '{yourAwsRoleSessionName}',
    'https://aws.amazon.com/SAML/Attributes/SessionDuration': 'time'   };

  callback(null, user, context);
}`;

<AuthCodeBlock children={codeExample} language="javascript" />

## Test configuration

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/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

* [Configure Amazon Web Services as SAML Service Provider](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-aws)