You can use the Authentication workspace to configure SSO in SaltStack Config to work with an authentication system compatible with the Security Assertion Markup Language (SAML) protocol.

SAML Single Sign-On (SSO) is functionality that many organizations configure during the implementation of SaltStack Config in order to:

  • Reduce the time users spend signing into services for the same identity. After users sign in to one of the services at an institution, they are then automatically authenticated into any other service that uses SSO.
  • Reduce password fatigue. The user is only required to remember one set of credentials rather than several.
Note: You can use more than one system at a time to authenticate users in SaltStack Config if needed. For example, you could use both a SAML-based IdP or LDAP-based IdP while simultaneously storing some user credentials natively on the RaaS server. However, SaltStack Config does not allow configuring more than two SAML providers or two LDAP providers at the same time.

How SAML SSO works with SaltStack Config

When SaltStack Config receives a successful identity assertion from any of its supported authentication integrations, it searches for a user login that matches the value of the asserted identity. If it finds a matching login, it logs in the associated user account.

For example, if SaltStack Config receives an ADFS assertion for a user and the value for the configured identity attribute is “fred,” SSE will search for a login with a username of “fred.” If one is found, the associated user is logged in. Otherwise, the login is unsuccessful.

SAML authentication terminology

Acronym Definition
SAML

Security Assertion Markup Language (SAML, pronounced SAM-el)

SAML is an open protocol (also sometimes referred to as a standard) for exchanging authentication and authorization data between parties. In particular, it is used to exchange data between an identity provider and a service provider.

SAML is browser-based single sign-on (SSO). All communications happen through the user agent (the browser). There is no communication between a service provider (such as SaltStack Config) and an identity provider (such as Okta). This separation allows authentication to occur across security domains where a service provider can be in one (possibly public) domain and the identity provider in a separate, secured network segment.
IdP

Identity provider

The job of the IdP is to identify users based on credentials. An identity provider is software that provides a service that complies with the identity provider part of the SAML Specification. The IdP typically provides the login screen interface and presents information about the authenticated user to service providers after successful authentication.

Supported identity providers for SaltStack Config include:

  • Google SAML
  • Okta*

* See additional details after this table.
SP

Service provider or relying party

An SP (service provider) is usually a website providing information, tools, reports, etc. to the end user. A service provider is software that provides a service that complies with the service provider part of the SAML Specification SaltStack Config. Microsoft products (such as Azure AD and ADFS) call the SP a relying party.

In this scenario, SaltStack Config is the service provider. SaltStack Config accepts authentication assertions from the IdP and allows users to log in.

An SP cannot authenticate with an IdP unless it is listed in the list of approved services. Configuring an SP with a list of approved IdPs is part of the configuration process.
SSO

Single sign-on

Single sign-on is an authentication system in which a user isn’t required to log in to a second service because information about the authenticated user is passed to the service.
SLO

Single logout

When a user logs out of a service, some IdPs can subsequently log the user out of all other services the user has authenticated to.

SaltStack Config does not currently support SLO.
RBAC

Role-based access control

Role-based access control, also known as role-based security, is an advanced access control measure that restricts network access based on a person’s role within an organization. The roles in RBAC refer to the levels of access that employees have to the network.

Employees are only allowed to access the network resources or perform tasks that are necessary to effectively perform their job duties. For example, lower-level employees usually do not have access to sensitive data or network resources if they do not need it to fulfill their responsibilities.

SaltStack Config can support RBAC with SAML configurations using the Roles workspace. However, the user will first need to log in to SaltStack Config in order to be added as a user in the local user database and managed by the Roles workspace.

Okta requirements

Some caveats and things to know when configuring Okta for SSO:
  • The Single Sign on URL field during setup requires the SAML Assertion Customer Service URL (ACS). This is the url for SSC with /autho/complete/saml at the end. For example, http://xxx.x.x.x:8080/auth/complete/saml.
  • SAML integration requires the UI to be serviced by SSC. The integration fails is the UI is being served by a CDN or any other website besides SSC.
  • All SAML responses must be signed. In Okta, you can enable this setting under Advanced Settings.
  • Every SAML attribute configured in SSC must exist and be passed in the SAML response.

Prerequisites

Before configuring SAML in SaltStack Config:

  • Install the SAML identity provider (IdP) and ensure it is running.
  • Ensure that you have access to the credentials and configuration data provided by the IdP.
  • 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. For more information, see self-signing certificates with the TLS Salt module.
    To create the certificate, generate a private key, called cert.perm, using the openssl genrsa -out cert.pem 2048. Then create the public key associated with the private key using the openssl req -new -x509 -key cert.pem -out cert.pub -days 1825 command and following the prompts. Record these public and private key pairs for easy access when working through the rest of the configuration process.

Setting up a SAML configuration

  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, configure these fields with the information about your SaltStack Config installation:
    • Name
    • Base URI
    • Entity ID
    • Company Name
    • Display Name
    • Website
  5. In the Private Key field, copy the private key you generated when you created the service provider certificate for SaltStack Config.
  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, configure these fields with the metadata about your identity provider (IdP):
    • Entity ID
    • User ID - the name of the attribute that the SAML receives from the IDP that represents the user identification used in SSC.
    • Email -the name of the attribute that the SAML receives from the IDP that represents the user's email address. SSC requires a valid email address for the user.
    • Username - the name of the attribute that the SAML receives from the IDP that represents the user's username. This should be different from the user ID so you can easily and readily recognize the user it represents.
    • URL
    • x509 certificate
    Note: This information is provided by your IdP.
  9. (Optional) Check the Attribute Statement Check box to enable SaltStack Config to check the SAML Attribute Statements for user profiles. This option is checked by default.
  10. Click Save.

What to do next

After configuring SAML single sign-on, you can:
  • Provide the AssertionCustomerService URL (for example: https://<your-sse-hostname>/auth/complete/saml), and the public (x509) certificate and key you generated for SaltStack Config to your IdP.
  • Create attribute mappings for users, specifically for the User ID, Email, and Username. Many organizations will map all three of these values to the user's email address as a single attribute because it is typically unique across an organization. The process for mapping these attributes is specific to each SAML identity provider. For assistance creating these attribute mappings, refer to your IdP's documentation or contact your administrator.
  • Add users to SaltStack Config. 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 from the Authentication workspace, select your SAML configuration from the list of the Authentication Configs and click the User tab from configuration settings. Click Create, enter the user credentials and select Roles.
    Note: Ensure that this username is accurate. Once a user has been created, their username cannot be changed or renamed. 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.
  • Validate your SAML configuration by logging in as a typical user to ensure that the login process works as expected and that roles and permissions are correct. Troubleshoot potential errors by using the SAML tracer tool, which is available for Firefox and Chrome web browsers, and 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.