# Authenticate with Roles Anywhere

> IAM Roles Anywhere lets an AWS handler authenticate with a certificate instead of an access key and secret key

---

Site [llms.txt](/llms.txt)

---

Cloud Management Platform (CMP) presents a client certificate to the Roles Anywhere API and receives temporary credentials in return, valid for one hour. CMP requests new credentials each time it connects. Nothing long-lived is stored in CMP, which suits a multi-tenant deployment where you want to share the resources in an account without sharing its keys.

## What you set up first

Four things must exist in AWS before you add the handler, each of which produces a required value. Work through them in order.

1. A Roles Anywhere role, which gives you the **Roles Anywhere ARN**.
1. A profile that names the roles a client may assume and provides the **Profile ARN**.
1. A client certificate and its key, in PEM format.
1. A trust anchor holding the CA that signed that certificate, which gives you the **Trust Anchor ARN**. The profile and the trust anchor must be created in the same region.

## Create the role and profile with CloudFormation

A CloudFormation template creates the role, its policy, and the profile in a single pass and outputs both ARNs. This replaces the two sections that follow.

1. Download [CloudboltRolesAnywhereSetupStack.json](https://raw.githubusercontent.com/CloudBoltSoftware/cloudbolt-forge/master/internal/cloudformation_templates/CloudboltRolesAnywhereSetupStack.json) from CloudBolt Forge.
1. In the AWS console, go to **CloudFormation** > **Create stack** > **With new resources (standard)**.
1. Select **Upload a template file** and upload the file.
1. Enter a stack name and accept the defaults on the stack options page.
1. Acknowledge that CloudFormation may create IAM resources with custom names, then submit the stack.
1. On the **Outputs** tab, copy the profile ARN and the Roles Anywhere role ARN.

## Create the role by hand

The role trusts the Roles Anywhere service, which allows the service to assume it and issue temporary credentials.

1. In the AWS console, go to **IAM** > **Roles** > **Create role**.
1. Select **Custom trust policy** and paste this policy:

    ```json
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Principal": {
                    "Service": "rolesanywhere.amazonaws.com"
                },
                "Action": [
                    "sts:AssumeRole",
                    "sts:TagSession",
                    "sts:SetSourceIdentity"
                ]
            }
        ]
    }
    ```

1. Select **Next** and attach a policy that grants the required permissions under [AWS permissions](/docs/cmp/configure/infrastructure/resource-handlers/aws/#aws-permissions).
1. Name the role and create it, then open it and copy the **Role ARN**.

## Create the profile by hand

A profile names the roles a client may assume, and can narrow the permissions those roles carry. See [Getting started with IAM Roles Anywhere](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/getting-started.html) in the AWS documentation.

1. Go to the [Roles Anywhere](https://console.aws.amazon.com/rolesanywhere/home) console and select **Create a profile**.
1. Name the profile and, under Roles, select the role you created.
1. Create the profile and copy its **Profile ARN**.

## Generate self-signed certificates

If you do not have a CA, CMP can generate a root CA, a client certificate, and a client key, and package them as a certificate bundle. Run the command on the CMP appliance.

These arguments are required: `country_name`, `state_name`, `locality`, `org_name`, `root_ca_name` (for the root CA), and `client_ca_name` (for the client certificate). Quote any value containing spaces.

Two arguments are optional. Use `email` to send the bundle as an attachment, or use `output_dir` to write it to a directory on the appliance. Without either, the bundle is written to the default directory, /var/tmp.

To email the bundle:

```bash
sudo su -
/opt/cloudbolt/manage.py self_signed_certificate --country_name="US" --state_name="Maryland" --locality="Rockville" --org_name="Example-Company" --root_ca_name="Roles-Anywhere-Root-CA" --client_ca_name="Roles-Anywhere-Client-CA" --email="admin@example.com"
```

To save it on the appliance:

```bash
sudo su -
/opt/cloudbolt/manage.py self_signed_certificate --country_name="US" --state_name="Maryland" --locality="Rockville" --org_name="Example-Company" --root_ca_name="Roles-Anywhere-Root-CA" --client_ca_name="Roles-Anywhere-Client-CA" --output_dir="/var/tmp"
```

## Create a trust anchor

The trust anchor represents the CA that signed your client certificate, either an AWS Certificate Manager private CA or your own.

1. In the IAM console, go to **Roles** and select **Manage** under Roles Anywhere.
1. Select **Create a trust anchor** and name it.
1. For a CA of your own, select **External certificate bundle** and paste the contents of the root CA PEM file. Selecting an AWS Certificate Manager private CA may incur AWS charges.
1. Create the trust anchor and copy its **Trust Anchor ARN**.

## Create the handler

1. Go to **Admin** > **Resource Handlers** and select **Add**.
1. Select the **Amazon Web Services** tile.
1. Set **Credentials Type** to **Roles Anywhere**.
1. Enter the **Roles Anywhere ARN**, **Profile ARN**, and **Trust Anchor ARN** you collected.
1. Upload the **Client Certificate** and the **Client Certificate Key**. Both must be in PEM format.
1. Select **Continue**, then complete the handler's settings and select at least one region, as described under [Add an AWS resource handler](/docs/cmp/configure/infrastructure/resource-handlers/aws/#add-an-aws-resource-handler).

![Screenshot of the Create a Resource Handler for Amazon Web Services with Roles Anywhere selected.](/img/cmp/configure/infrastructure/resource-handlers/aws/roles-anywhere/create-aws-resource-handler-roles-anywhere.png)

The three ARNs appear on the handler's Overview tab. Use **Verify Connection** to confirm the certificate is accepted.

## Related

- [AWS](/docs/cmp/configure/infrastructure/resource-handlers/aws/): the other credentials types, and what an AWS handler needs permission to do.