SAML.to
Search
⌃K

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)