> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-docs-event-stream-action-templates.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Learn how to use Amazon Web Services (AWS) Session Tags to implement role-based access control (RBAC) for AWS APIs and Resources.

# Use Amazon Web Services Session Tags for Role-Based Access Control

With Amazon Web Services (AWS) Session Tags, you can tag resources and assign users key/value pairs, which allows you to implement role-based access control (RBAC) for AWS APIs and resources.

In the example included in this guide, we will tag our AWS resources with AWS Session Tags, then create a policy for an AWS IAM role that will allow users with this role and the appropriate tags to perform specific actions on our AWS resources. We will then create a rule in Auth0 that will attach our AWS IAM role and appropriate AWS Session Tags to an Auth0 user and pass them through <Tooltip tip="Security Assertion Markup Language (SAML): Standardized protocol allowing two parties to exchange authentication information without a password." cta="View Glossary" href="/docs/glossary?term=SAML">SAML</Tooltip> assertions in the token. This example builds on the example provided in [Configure Amazon Web Services for Single Sign-On](/docs/customize/integrations/aws/configure-amazon-web-services-for-sso).

To use AWS Session Tags with AWS APIs and Resources, you must:

1. Tag AWS instances.
2. Create a specialized AWS IAM role.
3. Create an Auth0 rule.
4. Test your configuration.

## Prerequisites

* You'll need an [Amazon Web Services (AWS) account](https://portal.aws.amazon.com/billing/signup#/start) for which you are an administrator.
* [Configure AWS for SSO](/docs/customize/integrations/aws/configure-amazon-web-services-for-sso)
* [Set up some AWS VM Instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html). For the example in this guide, we use three separate instances.

### Tag AWS instances

Add tags to your AWS resources. Follow instructions in [Amazon Elastic Compute Cloud: Tag your Amazon EC2 resources](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html).

You should have created three instances. Add the following tags:

| Instance | Tags                                                                                         |
| -------- | -------------------------------------------------------------------------------------------- |
| 1        | Key: `CostCenter`, Value: `marketing`.<br />Key: `Project`, Value: `website`.                |
| 2        | Key: `CostCenter`, Value: `engineering`.<br />Key: `Project`, Value: `management_dashboard`. |
| 3        | Key: `CostCenter`, Value: `marketing`.<br />Key: `Project`, Value: `community_site`.         |

### Create a specialized AWS IAM role

Create an IAM role using the AWS SAML <Tooltip tip="Identity Provider (IdP): Service that stores and manages digital identities." cta="View Glossary" href="/docs/glossary?term=identity+provider">identity provider</Tooltip> you set up during the prerequisites. Follow the instructions in [AWS Identity and Access Management User Guide: Creating a Role for SAML 2.0 Federation (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html).

While setting up your role, make sure you use the following parameters:

| Parameter     | Description and Sample Value                                                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SAML Provider | Name of the identity provider you created in the prerequisites, such as `auth0SamlProvider`. Select **Allow programmatic and AWS Management Console access**. |

When asked to **Attach permissions policies**, create a policy with the following JSON and name it `VirtualMachineAccessByCostCenter`.

```json lines theme={null}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeInstances"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ec2:StartInstances",
                "ec2:StopInstances"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "ec2:ResourceTag/CostCenter": "<%= "${aws:PrincipalTag/CostCenter}" %>"
                }
            }
        }
    ]
}
```

Once the policy has been created, refresh the policy list for the role, then filter and select the new policy.

When reviewing your settings, make sure you use the following parameters:

| Parameter        | Description                                                   |
| ---------------- | ------------------------------------------------------------- |
| Role name        | Descriptive name for your role, such as `AccessByCostCenter`. |
| Role description | Description of the purpose for which your role is used.       |

### Create an Auth0 rule

To map the AWS role and tags to a user, you'll need to [create a rule](/docs/customize/rules/create-rules) in Auth0. These values will then be passed through the SAML assertions in the token. For the example:

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Replace the `awsAccount` variable value with your own account number.
</Callout>

```javascript lines theme={null}
function(user, context, callback) {
  var awsAccount = '013823792818';
  var rolePrefix = `arn:aws:iam::` + awsAccount; 
  var samlIdP = rolePrefix + `:saml-provider/auth0SamlProvider`;

  user.awsRole = rolePrefix + `:role/AccessByCostCenter,` + samlIdP;
  user.awsRoleSession = user.email;
  user.awsTagKeys = ['CostCenter', 'Project'];
  user.CostCenter = 'marketing';
  user.Project = 'website';

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

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

### Test configuration

You should now be able to log in to the AWS Console using an Auth0 user and test your implementation.

To log in, you will need the <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> login for the AWS Console. To find it:

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select the name of the Application to view.
2. On the **Addons** tab, enable the **SAML2 Web App** add-on.
3. On the **Usage** tab, locate **Identity Provider Login URL**.
4. Go to the indicated URL.
5. Once you have signed in, from **EC2**, select **Instances**. Click one of the instances tagged with a `CostCenter` of `marketing`, and click **Actions** > **Instance State** > **Stop**. Notice that the action completes successfully.
6. Click the instance tagged with a `CostCenter` of `engineering`, and click **Actions** > **Instance State** > **Stop**. Notice that the action fails with an error.

## Learn more

* [Configure Amazon Web Services for Single Sign-On](/docs/customize/integrations/aws/configure-amazon-web-services-for-sso)
* [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)