# 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)


---

# 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/reference.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.