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.

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.

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

You can also use some light Substitution Syntax (<#= ... #>) for injection of variables when a SAML Assertion (i.e. Role Assumption) is requested by a user.

See Service Providers for a detail on supported Service Providers that can be configured in the configuration file.

For more information, see the 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 for a detail on how to configure various Service Providers, such as AWS.

For more information, see the 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

You do not need to be a member or Administrator of the other Organization to make this work!