Before creating a new SAML configuration for SaltStack Config, read through these steps to ensure you are familiar with the configuration process.

Pre-configuration steps

Before configuring SAML in SaltStack Config:

  • Install the SAML identity provider (IdP) and ensure it is running. This topic will not provide instructions for the installation of any IdP. Contact your IdP administrator for support.
  • Ensure that you have access to the credentials and configuration data provided by the IdP. In addition, see the following section about Creating a service provider certificate.

Creating a service provider certificate

You need to generate a certificate to add SaltStack Config as an approved service provider with your IdP. Your SaltStack Config service provider needs an RSA key pair. You enter the private and public key values in several places when you configure SAML for SaltStack Config.

Note: This key pair can be generated on any system. It doesn’t need to be created on the SSE server. These commands run on any system with openssl utilities installed.Alternatively, you could use Salt to generate the self-signed certificate. See the documentation for self-signing certificates with the TLS Salt module.

To create the certificate:

  1. Generate a private key, called cert.pem, using the command:
    openssl genrsa -out cert.pem 2048
  2. Create the public key associated with the private key you just created in the previous step. The following command walks you through the process:
    openssl req -new -x509 -key cert.pem -out cert.pub -days 1825
  3. As this command runs, answer the prompts as needed, such as your:
    • Country name
    • State or province name
    • Locality or city name
    • Organization or company name
    • Organizational unit name
    • Server hostname
    • Email address

You now have the public and private key pair that will be used in your SAML configuration. Record these public and private key pairs for easy access when working through the rest of the configuration process. Proceed to the next section for instructions about Setting up a SAML configuration.

Setting up a SAML configuration

Before completing the steps in this section, ensure you have generated the public and private keys for SaltStack Config as your service provider. For more instructions, see Creating a service provider certificate.

To set up SAML SSO using your organization’s preferred IdP in SaltStack Config:

  1. Click Administration > Authentication on the side menu.
  2. Click Create.
  3. From the Configuration Type menu, select SAML.

    The workspace displays the supported settings for the SAML configuration type.

  4. In the Settings tab, complete the following fields with the information about your SaltStack Config installation:
    • Name
    • Base URI
    • Entity ID
    • Company Name
    • Display Name
    • Website
    Note: For descriptions of these fields, see SAML information fields.
  5. In the Private Key field, copy the private key you generated when you created the service provider certificate for SaltStack Config. For more information, see Creating a service provider certificate.
  6. In the Public Key field, copy the public key you generated when you created the service provider certificate for SaltStack Config.
  7. Complete the fields with the relevant contact information for your:
    • Technical contact
    • Support contact
  8. In the Provider Information section, complete the following fields with the metadata about your identity provider (IdP):
    • Entity ID
    • User ID
    • Email
    • Username
    • URL
    • x509 certificate
    Note: ADFS, Azure AD, and Google SAML are examples of common identity providers. You’ll fill in these fields with information provided by your IdP. For more information about these fields, see SAML information fields.
  9. OPTIONAL: Check the Attribute Statement Check box if you want SaltStack Config to check the SAML Attribute Statements for user profiles. This option is checked by default.
  10. Click Save.

The SAML configuration for SaltStack Config is now complete. Proceed to the next section for instructions about Configuring the IdP with service provider information.

Configuring the IdP with service provider information

Before completing the steps in this section, ensure you have configured SAML in SaltStack Config first. For more information, see the instructions about Setting up a SAML configuration.

To complete your SAML configuration, the identity provider needs two important pieces of data:

  • The AssertionCustomerService URL
  • The public (x509) certificate (public key) you generated when you created the service provider certificate for SaltStack Config. For more information, see Creating a service provider certificate.

The AssertionCustomerService URL is the web address your service provider uses to accept SAML messages and artifacts when establishing an identity assertion. In this case, SaltStack Config is the service provider.

The following is an example of the typical format for the AssertionCustomerService URL: https://<your-sse-hostname>/auth/complete/saml

After you’ve provided this data to your IdP, proceed to the next section for instructions about Creating attribute mappings.

Creating attribute mappings

SaltStack Config pulls information about the user from the inbound SAML assertion. For that reason, the IdP must ensure that the required values are sent as additional attributes. The process for mapping these attributes is specific to each SAML identity provider. For assistance creating attribute mappings, refer to your IdP’s documentation or contact your administrator.

SaltStack Config needs to define the user’s following attributes:

  • User ID
  • Email
  • Username

Many organizations will map all three of these values to a single attribute: the user’s email address. The user’s email address is often used because it is typically unique across an organization.

Configuring RBAC for SAML

SaltStack Config supports creating roles and permissions for users in various roles. RBAC for SAML is managed the same way you would manage users whose credentials are stored natively in SaltStack Config on the API (RaaS) server. For more on the Roles workspace, see Roles and permissions.

After creating roles, you can then add SAML users and assign them to roles. For more information, see the following section about Adding users.

Adding users

By default, new users are registered in SaltStack Config only after a user’s first successful login with SAML. Alternatively, you can add users manually to pre-register these users in SaltStack Config.

To manually add users:

  1. In the Authentication workspace, select your SAML configuration from the list of Authentication Configs to open your configuration settings.
  2. In the configuration settings, click the User tab.
  3. Click the Create button.
  4. In the Username field, enter the credentials for the user you want to add. This username must be identical to their assigned SAML username.
    Note: Ensure that this username is accurate. Once a user has been created, their username cannot be changed or renamed.
  5. In the Roles field, select any roles you want to add the user to. All new users are added to the User role by default. For more information, see Configuring RBAC for SAML.
  6. Click Save.
    Note: After a user has been manually created, they can only be deleted before their first login. After the user has logged in initially, the delete button is still available in this workspace, but it no longer works.

Troubleshooting and validating the configuration

After you’ve configured SSO in SaltStack Config, try logging in as a typical user to ensure that the login process works as expected and that roles and permissions are correct.

To troubleshoot potential errors, try:

  • Using the SAML tracer tool, which is available for Firefox and Chrome web browsers.
  • Viewing the /var/log/raas/raas log messages.
Note: Users cannot be deleted through the SaltStack Config user interface or using the API after initial provisioning with a successful SAML authentication.