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)

---
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 and permissions keys and values.

For more information, see Substitutions.

providers

(Required)

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

• The provider key is referenced 1-1 in the permissions 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.

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 above.

repos

(Optional)

Properties: github (which is a list of repositories)