# Adding Roles

## Prerequisites

[Ensure SAML.to is installed](/installation.md) to your GitHub Organization or User Account

## Add or Update an IAM Role

<details>

<summary>Create a new role</summary>

1. Navigate to [AWS IAM Roles](https://console.aws.amazon.com/iamv2/home#/roles)
2. Click **Create Role**
   1. **Trusted entity type:** SAML 2.0 federation
   2. **SAML 2.0-based provider:** Choose the provider.
      1. If SAML.to isn't in the list, [add SAML.to to the AWS account first](/configuration/service-providers/aws-federated-roles/adding-aws-accounts.md).
   3. **Allow programmatic and AWS Management Console access**
   4. **Attribute:** `SAML:aud`
   5. **Value:** `https://signin.aws.amazon.com/saml`&#x20;
3. Continue the remaining steps to create the role
4. Copy the **Role ARN**<br>

</details>

<details>

<summary>Use an existing role</summary>

1. Copy the **Provider ARN** of SAML.to from [AWS IAM Providers](https://console.aws.amazon.com/iamv2/home#/identity_providers)
   1. If SAML.to isn't in the list, [add SAML.to to the AWS account first](/configuration/service-providers/aws-federated-roles/adding-aws-accounts.md).
2. Choose a role in [AWS IAM Roles](https://console.aws.amazon.com/iamv2/home#/roles)
3. Click the **Trust Relationships** tab
4. Click **Edit trust policy**&#x20;
5. Add a **Statement**, update the policy, and make note of the **Provider ARN**

```
{
  "Effect": "Allow",
  "Principal": {
      "Federated": "THE_PROVIDER_ARN"
  },
  "Action": "sts:AssumeRoleWithSAML",
  "Condition": {
      "StringEquals": {
          "SAML:aud": "https://signin.aws.amazon.com/saml"
      }
  }
}
```

</details>

## Update saml-to.yml

Add the following the following block to `permissions.aws.roles` to `saml-to.yml`:

```
      - name: THE-ROLE-ARN
        provider:
          variables:
            providerArn: THE-PROVIDER-ARN
        users:
          github:
            - some-github-user
            - another-github-user
        repos:
          github:
            - some-repo
            - another-org/some-other-repo
```

<figure><img src="/files/tZeB0pzubmABJI15X3cU" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.saml.to/configuration/service-providers/aws-federated-roles/adding-roles.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.