You can use the Authentication workspace to configure SSO in SaltStack Config to work with an authentication system compatible with the OAuth and OIDC protocols.

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 two SAML providers or two LDAP providers at the same time.

About OAuth and OIDC SSO

OAuth single sign-on (SSO) is a functionality that many organizations configure during the implementation of SaltStack Config. SSO provides many benefits, including:

  • Reducing 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.
  • Reducing password fatigue. The user is only required to remember one set of credentials rather than several.

Many services provide implementations of the OAuth protocol with support for OIDC including OKTA, Google, Microsoft, GitLab, Zendesk, Apple, Keycloak, Salesforce, and more.

Note: SaltStack Config currently only supports OAuth and OIDC authentication through OKTA and Google.

How OAuth and OIDC works with SaltStack Config

When a user attempts to login to SaltStack Config using an OAuth identity:

  1. SaltStack Config requests authorization to access service resources from the user.
  2. If the user authorizes the request, SaltStack Config receives an authorization grant.
  3. SaltStack Config requests an access token from the authorization server (API) by presenting authentication of its own identity.
  4. If the application identity is authenticated and the authorization grant is valid, the authorization server (API) issues an access token to the SaltStack Config.
  5. SaltStack Config requests the resource from the resource server (API) and presents the access token for authentication.
  6. If the access token is valid, the resource server (API) serves the resource to the application and the user is allowed to login to SaltStack Config.

OAuth and OIDC authentication terminology

Term Definition
OAuth

OAuth 2.0 is an open protocol (also sometimes referred to as a standard) for access delegation in which the user can perform actions on a website after the user’s identity has been authenticated with a security token. It is commonly used as a way for users to give applications access to their information on other third-party applications without giving them their access credentials (passwords).

OAuth is browser-based single sign-on (SSO). OAuth allows access tokens to be issued to third-party clients by an authorization server, with the approval of the resource owner. The third party then uses the access token to access the protected resources hosted by the resource server.
OIDC

Open ID Connect

Open ID Connect (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol. OIDC enables clients to verify the user’s identities based on the authentication performed by an authorization server. It can also obtain basic profile information about the user across applications.
Resource owner The resource owner is the user who authorizes an application to access their account. The application’s access to the user’s account is limited to the scope of the authorization granted, such as read or write access.
Client The client is the third-party application that needs access to the user’s account, which, in this case is SaltStack Config.
Authorization server The authorization server hosts the protected user accounts and credentials. It verifies the identity of the user and then issues access tokens to the client. It is frequently accessed through the service’s API.
Resource server

The resource server is the API server that is used to access the user’s information. It handles authenticated requests after the client has obtained an access token. Smaller deployments typically have only one resource server, and is often built as part of the same code base or same deployment as the authorization server.

Large scale deployments may have more than one resource server. Each resource server is distinctly separate, but they all share the same authorization server.

Pre-configuration steps

Before configuring OAuth and OIDC in SaltStack Config, ensure that you have the necessary access to your OAuth 2.0 service for your organization (either OKTA or Google) and that you are relatively familiar with their process for registering applications.

Note: SaltStack Config currently only supports OAuth and OIDC authentication through OKTA and Google.

Register SaltStack Config as an application with OKTA or Google

On your OAuth service’s website, enter basic information about SaltStack Config such as the name, website, etc. After registering the application, you’ll be given a client secret that you’ll need to provide to SaltStack Config.

One of the most important things when creating the application is to register one or more redirect URLs the application will use. The redirect URLs are where the OAuth 2.0 service will return the user to after they have authorized the application.

Configure an identity provider

To set up SSO using your organization’s preferred OAuth and OIDC service:

  1. Click Administration > Authentication on the side menu.
  2. Click Create.
  3. From the Configuration Type menu, select OIDC.
  4. In the Name field, assign this configuration a descriptive name.
  5. From the OIDC Provider menu, select either OKTA or Google.
  6. Complete the following fields with the information about your SaltStack Config installation:
    • Base URI
    • API URL (for OKTA configurations only)
    • Key
    • Secret
    Note: For descriptions of these fields, see OIDC information fields.
  7. Click Save.

The OIDC configuration for SaltStack Config is now complete.

Configure RBAC for OIDC

For OIDC, the user will first need to login to SaltStack Config in order to be added as a user in the local user database. After the users have logged in initially, the user’s roles and permissions will be managed the same way you would manage users whose credentials are stored locally in SaltStack Config on the RaaS server.

After the user has signed in initially, you can use the Roles workspace to assign appropriate roles and permissions to that user. For more on the Roles workspace, see Roles and Permissions.

OIDC information fields

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

Note: If you need assistance setting up your connection, contact your administrator.
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.
OIDC Provider Select your OIDC identity provider from this menu to display settings specific to your provider.
Base URI The base URL used by your organization in SaltStack Config, also known as the host server address. This URL is formatted as either a FQDN or IP address, such as https://example.com.
API URL The API URL supplied by your identity provider. This field is only displayed if your identity provider is OKTA.
Key The key supplied by your identity provider. In OKTA, the key is referred to as the Client ID.
Secret The secret supplied by your identity provider. In OKTA, the key is referred to as the Client Secret.