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)
Roles for GitHub Actions
Substitutions
Last modified 6mo ago