# GitHub

## Example Configuration File

The configuration file is broken into 2 separate sections for basic functionality: `providers` and `permissions`.

```
---
# Config Reference:
# https://docs.saml.to/configuration/reference
version: '20220101'
providers:
  aws:
    entityId: https://signin.aws.amazon.com/saml
    acsUrl: https://signin.aws.amazon.com/saml
    attributes:
      https://aws.amazon.com/SAML/Attributes/RoleSessionName: '<#= user.github.login #>'
      https://aws.amazon.com/SAML/Attributes/SessionDuration: '3600'
      https://aws.amazon.com/SAML/Attributes/Role: '<#= user.selectedRole #>,<#= provider.variables.providerArn #>'
permissions:
  aws:
    roles:
      - name: arn:aws:iam::123456789012:role/cnuss-admin
        provider:
          variables:
            providerArn: arn:aws:iam::123456789012:saml-provider/saml-to
        users:
          github:
            - github-user-id-1
            - github-user-id-2
            - octokat
        repos:
          github:
            - some-repo
            - other-org/some-other-repo
```

### Providers

The `providers` section details **Service Providers** (e.g. what services can a GitHub Token be used to log in with), for example using [AWS Federated Roles](https://docs.saml.to/configuration/service-providers/aws-federated-roles).

{% hint style="info" %}
The `key` in the aforementioned configuration (e.g. `aws`) **must match** between the `providers` and `permissions` sections. This is how a `permission` relates back to a particular `provider`.
{% endhint %}

It contains information like the Assertion URLs, Entity ID and other SAML attributes.

You can also use some light [Substitution Syntax](https://docs.saml.to/configuration/reference/substitutions) (`<#= ... #>`) for injection of variables when a SAML Assertion (i.e. Role Assumption) is requested by a user.

See [Service Providers](https://docs.saml.to/configuration/service-providers) for a detail on supported Service Providers that can be configured in the configuration file.

For more information, see the [Configuration Reference](https://docs.saml.to/configuration/reference).

### Permissions

The `permissions` section details the **Access Control Lists** to various **Service Providers** and **Roles**.

The `key` of the Permission (e.g. `aws`) must be identical to the `key` of a `provider`.

For each role, you can define `github` `users:` and `repos:` in their respective sections. Defining users and repositories is optional, you can define both, or one or the other.

See [Service Providers](https://docs.saml.to/configuration/service-providers) for a detail on how to configure various Service Providers, such as AWS.

For more information, see the [Configuration Reference](https://docs.saml.to/configuration/reference).

#### Granting Access to Repos in Another Organization

If you use multiple organizations in GitHub that might need to use the same provider in GitHub Actions, you can simply add the specify the Organization Name.

Assuming your GitHub organization is `my-org` and you have a repository `my-repo` that needs access to the `admin` role, and you have another organization `my-other-org` with another repository `my-other-repo` that needs access to the `admin` role, the configuration would look like this:

```
permissions:
  aws:
    roles:
      - name: arn:aws:iam::123456789012:role/admin
        ...
        repos:
          github:
            - my-repo
            - my-other-org/my-other-repo
```

{% hint style="success" %}
You **do not need** to be a member or Administrator of the other Organization to make this work!
{% endhint %}