SAML configuration reference

When configuring a SAML-based authentication system for SaltStack Config, you need to fill out various information fields. It is also possible to use the API to set up a SAML-based system, but it is not recommended.

SAML information fields

All of the SAML authentication information fields are required. Enter information for your SAML authentication configuration as follows.

Note:

If you need assistance setting up your connection, contact your administrator.

Basic


Field	Description
Name	The name of the authentication connection used by SSE. This name will appear in the sidebar when you are logged into the Authentication workspace and should be unique if you are setting up multiple configurations. This name cannot be changed after initial creation. Example: Acme SSO
Base URI	The base URL used by your organization in SaltStack Config, also known as the host server address. This is formatted as either a FQDN or IP address, such as `https://example.com`. This must not end with a slash. Example: `https://sse.example.com`
Entity ID	A unique ID for this SaltStack Config service provider. While SAML tradition is for this to be a URL-like string, any type of string is allowed. It must be unique compared to the other SAML applications used by your organization. Ensure that you use this same ID when registering SaltStack Config as an application. Example: `https://sse.example.com/saml`

Org Information


Field	Description
Company Name	The name of your organization.
Display Name	The name to display as your organization’s name.
Website	The URL for your organization’s website. This URL can be anything and has no bearing on SSO functionality.
Private Key	The private key you generated, also known as the cert.pem. This key should be in PEM format. For more information, see Creating a service provider certificate.
Public Key	The public keys and certificates you generated, also known as the cert.pub. This key should be in PEM format. For more information, see Creating a service provider certificate.

Technical Contact


Field	Description
Name	The name of the employee who is primarily responsible for the application at your organization. This information is required by the SAML protocol and will be passed on to the SAML provider. SaltStack Config does not use this information directly.
Email	The email address of the technical contact.

Support Contact


Field	Description
Name	The name of an employee who can be contacted if the primary technical contact for the application is unavailable. This information is required by the SAML protocol and will be passed on to the SAML provider. SaltStack Config does not use this information directly.
Email	The email address of the support contact.

Provider Information


Field	Description
Entity ID	The Entity ID of the identity provider (IdP). Example of an Azure AD Entity ID: `https://sts.windows.net/2f09bc14-a1f0-48ce-8280-0a09e775e40d/`
User ID	A reference to a mapped SAML attribute that will contain the permanent user ID.
Email	A reference to a mapped SAML attribute that will contain the email address.
Username	A reference to a mapped SAML attribute that will contain the username.
URL	The URL used to access your identity provider’s SAML endpoints.
x509 Certificate	The X.509-formatted certificate with an embedded public key generated through your identity provider’s system. This key must be in PEM format.

Security Checks


Field	Description
Attribute Statement Check	Check this box if you want SaltStack Config to check the SAML Attribute Statements for user profiles.

Configuring SAML from the Command Line (CLI)

This guide strongly recommends configuring SAML using the SaltStack Config user interface rather than the command line. These instructions are included for reference.

To set up most configuration standards using the CLI:

Login as a RaaS user:
```
sudo su raas
```
OPTIONAL: This step is only necessary if you manually installed SaltStack Config. On the RaaS server, install the OpenSSL .xml file that is included in the installer files. Use the following command:
```
yum install xmlsec1-openssl
```
Note:
RedHat doesn’t have xmlsec1 readily available in any default repositories. One possible workaround is to download the RPMs from a CentOS machine and transfer them to RedHat.
Navigate to the directory where you intend to save the configuration file. Any directory path is acceptable.
Create a YAML file with the necessary configuration information that is required by your identity service provider. For examples of how to format these configuration files, see the Sample configuration files.
Note:
For descriptions of the various fields, see SAML information fields.
Execute the configuration file using the following commands:
```
raas save_sso_config <filepath>
```

Sample configuration files

Sample SAML configuration file for Google

Replace the placeholder text in the following sample with the information provided by your IdP:

name: Google
backend: social_core.backends.saml.SAMLAuth
settings:
  base_uri: https://example.com
  saml_sp_entity_id: raas
  saml_org_info:
    en-US:
    name: Name of Your Organization
    displayname: Display Name for Your Organization
    url: https://example.com
  saml_technical_contact:
    givenName: Name of Your Technical Contact
    emailAddress: email@my_technical_contact.com
  saml_support_contact:
    givenName: Name of Your Support Contact
    emailAddress: email@my_support_contact.com
  saml_enabled_idps:
    saml:
      entity_id: https://accounts.google.com/o/your_organization_id
      attr_user_permanent_id: Your organization's permanent ID
      attr_email: email@my_email_with_identity_provider.com
      attr_username: Your organization's username for the IdP
      url: https://accounts.google.com/o/saml2/your_organization_id
      x509cert: |
        -----BEGIN CERTIFICATE-----
        Insert certificate block of text here
        -----END CERTIFICATE-----
      saml_sp_private_key: |
        -----BEGIN PRIVATE KEY-----
        Insert private key block of text here
        -----END PRIVATE KEY-----
      saml_sp_public_cert: |
        -----BEGIN CERTIFICATE-----
        Insert certificate block of text here
        -----END CERTIFICATE-----

Sample SAML configuration file for Okta

Replace the placeholder text in the following sample with the information provided by your IdP:

name: Okta
backend: social_core.backends.saml.SAMLAuth
settings:
  base_uri: https://example.com
  saml_sp_entity_id: https://example.com/auth/complete/saml
  saml_org_info:
    en-US:
    name: Name of Your Organization
    displayname: Display Name for Your Organization
    url: https://example.com
 saml_technical_contact:
   givenName: Name of Your Technical Contact
   emailAddress: email@my_technical_contact.com
saml_support_contact:
  givenName: Name of Your Support Contact
  emailAddress: email@my_support_contact.com
saml_security_config:
  wantAttributeStatement: False
saml_enabled_idps:
  okta:
    entity_id: https://www.okta.com/your_organization_id
    attr_user_permanent_id: Your organization's permanent ID
    attr_email: email@my_email_with_identity_provider.com
    attr_username: Your organization's username for the IdP
    url: https://example.okta.com/app/your_organization_id
    x509cert: |
      -----BEGIN CERTIFICATE-----
      Insert certificate block of text here
      -----END CERTIFICATE-----
    saml_sp_private_key: |
      -----BEGIN PRIVATE KEY-----
      Insert private key block of text here
      -----END PRIVATE KEY-----
    saml_sp_public_cert: |
      -----BEGIN CERTIFICATE-----
      Insert certificate block of text here
      -----END CERTIFICATE-----

Sample OIDC configuration file for Google

Replace the placeholder text in the following sample with the information provided by your IdP:

name: Name of Your Organization
backend: social_core.backends.google_openidconnect.GoogleOpenIdConnect
settings:
  base_uri: example.com
  google_openidconnect_key: your_id.apps.googleusercontent.com
  google_openidconnect_secret: your_secret

Updating an SSO configuration from the Command Line (CLI)

To update a configuration standard from the CLI:

Login as a RaaS user:
```
sudo su raas
```
Navigate to the directory in which you have stored the configuration file. Update the configuration file as necessary.
Save the configuration file using the following command:
```
raas save_sso_config <filepath>
```

Deleting an SSO configuration from the Command Line (CLI)

If access to the SaltStack Config user interface is available, it is recommended that you delete an SSO configuration using the UI. However, you can delete an SSO configuration using the API (RaaS) if needed.

To delete an SSO configuration, you need to find the slug that is assigned to the configuration that you would like to delete. The slug is a representation of the configuration’s name separated by a dash - mark with all lowercase letters. For example, the slug might be name-of-your-organization. For SAML with Google, the slug is google.

In the API (RaaS), generate a list of your SSO backends using the following command:
```
client.api.settings.get_sso_backends()
```
From the list of SSO backends, find the slug for the configuration you want to delete. Then enter the following command, replacing the placeholder text with your configuration slug:
```
client.api.settings.delete_sso_config('slug-for-your-configuration')
```