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.
OAuth single sign-on (SSO) is a 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.
Many services provide implementations of the OAuth protocol with support for OIDC including OKTA, Google, Microsoft, GitLab, Zendesk, Apple, Keycloak, Salesforce, and more.
| 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. |
| Open ID Connect (OIDC) |
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. |
For OIDC, the user will first need to log in 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.
How OAuth and OIDC works with SaltStack Config
When you attempt to login to SaltStack Config using an OAuth identity:
- SaltStack Config requests authorization to access service resources from the user.
- If the user authorizes the request, SaltStack Config receives an authorization grant.
- SaltStack Config requests an access token from the authorization server (API) by presenting authentication of its own identity.
- If the application identity is authenticated and the authorization grant is valid, the authorization server (API) issues an access token to the SaltStack Config.
- SaltStack Config requests the resource from the resource server (API) and presents the access token for authentication.
- 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.
Prerequisites
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.
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:
- Click Administration > Authentication on the side menu.
- Click Create.
- From the Configuration Type menu, select OIDC.
- In the Name field, assign this configuration a descriptive name.
- From the OIDC Provider menu, select either OKTA or Google.
- Complete the following required fields with the information about your SaltStack Config installation:
Field Description 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. - Click Save.
The OIDC configuration for SaltStack Config is now complete.
