> For the complete documentation index, see [llms.txt](https://docs.saml.to/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.saml.to/configuration/reference.md).

# Configuration Reference

The `saml-to.yml` configuration has a relatively simple Configuration Syntax and can easily be modified by hand.

**Generalized Structure** (and [JSON Schema](https://sso.saml.to/github/config.schema.json))

```
---
version: '20220101'
variables:
  variable1: 'VariableValue1'
  variable2: 'VariableValue2'
providers:
  provider1:
    entityId: https://provider1.com/saml
    acsUrl: https://provider1.com/saml/acs
    attributes:
      CustomAttribute1: '<#= user.github.login #>`
      CustomAttribute2: '12345'
      CustomAttribute3: 'hello my name is <#= user.github.fullName #> for <$= variable1 $>' # you can intermix subsitutions
  provider2:
    entityId: https://subdomain.provider2.com/sso
    loginUrl: https://subdomain.provider2.com
    acsUrl: https://subdomain.provider2.com/sso/acs
    nameIdFormat: 'emailV2'
    attributes:
      Email: '<#= user.github.email #>'
      FirstMame: '<#= user.github.firstName #>'
  samltest:
    entityId: https://samltest.id/saml/sp
    loginUrl: 'https://samltest.id/Shibboleth.sso/Login?entityID=<#= system.entityIdUriEncoded #>'
    nameId: '<#= user.github.firstName #>.<#= user.github.lastName #>.'@mycompany.com
    nameIdFormat: email
    acsUrl: https://samltest.id/Shibboleth.sso/SAML2/POST
    attributes: {}
permissions:
  provider1:
    roles:
      - name: Role1
        users:
          github:
            - GitHubUserName1
      - name: Role2
        users:
          github:
            - GitHubUserName1
            - JohnSmith
        repos:
          github:
            - my-repo # A repo in the same org as the `saml-to.yml`
            - some-other-org/some-other-repo # A repo in a different org
  provider2:
    users:
      github:
        - GitHubUserName1
        - JohnSmith
        - SallySue
  samltest:
    users:
      github:
        - GithubUser1
        - GithubUser2
```

## version

(Required)

Must be `20220101`.

## variables

*(Optional)*

A map of Key/Value Pairs that can be used in [`providers`](#undefined) and `permissions` keys and values.

For more information, see [Substitutions](/configuration/reference/substitutions.md).

## providers

(Required)

A map of Service Providers, keyed by a unique name.

* The provider key is referenced 1-1 in the [`permissions`](#undefined) object.

For each provider, the following attributes apply:

### entityId

(Required)

A URL of the Provider's Entity ID (aka Audience, Login URL)

### acsUrl

(Required)

The URL of the Providers Assertion Consumer Service URL (ACS URL)

### loginUrl

(Optional)

If SP-Initiated Logins, this is the Login URL of the Service Provider.

For IdP-Initiated Logins, leave this blank.

### nameId

(Optional)

If a custom `nameId` is required by the Service Provider, you can specify it here.

Example - Setting the email address to be first and last name at a specific domain:

```
nameId: <#= user.github.firstName #>.<#= user.github.lastName #>@mydomain.com
nameIdFormat: email
```

### nameIdFormat

(Optional)

Allowed Values: 'id', 'login', 'email', 'emailV2'

If the Provider requires a specific NameId Format, it can be defined here.

If `id`, the NameIdFormat in the SAML Response will be: `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` and be set to `user.github.id` (or the value of `nameId`, if set)

If `login`, the NameIdFormat in the SAML Response will be: `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` and be set to `user.github.login` (or the value of `nameId`, if set)

If `email`, the NameIdFormat in the SAML Response will be: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` and be set to `user.github.email` (or the value of `nameId`, if set)

If `emailV2`, the NameIdFormat in the SAML Response will be: `urn:oasis:names:tc:SAML:2.0:nameid-format:email` and be set to `user.github.email` (or the value of `nameId`, if set)

### attributes

(Optional)

A Key/Value Map or strings as attributes to send in the SAML Request.

**Note: Ensure all values are wrapped in Quotes to ensure that they are sent to the Service Provider as strings,** unless otherwise desired by the Service Provider.

## permissions

(Required)

A map of Service Providers, keyed by provider keys defined in [`providers`](#providers).

For each provider, the following attributes apply:

### users

(Optional)

Allowed properties: `github` (which is a list of strings of GitHub Logins)

### roles

(Optional)

A list of role objects with the following properties:

#### name

(Required)

The role name at the Service Provider

#### users

(Optional)

The list of users, same structure as [`users`](#users) above.

#### repos

(Optional)

Properties: `github` (which is a list of repositories)