Create and manage SSO IdP services
This article covers the Single Sign-On Configuration page. If you are not familiar with SAML or OIDC, start with SAML SSO or OpenID Connect; this article assumes you know which protocol you are using and have access to your identity provider (IdP). For a description of every field on the page, see Single Sign-On Configuration page reference.
Prerequisites
Admin access to your site
Gather the following from your IdP before you start:
For SAML:
- Entity ID (required): the unique identifier for your IdP
- Single Sign-On URL (required): the endpoint Expert sends authentication requests to
- Single Logout URL (recommended)
- Public X.509 certificate (required): verifies SAML assertions from your IdP
For OIDC:
- Client ID and Client Secret (required)
- IdP Issuer (required)
- Authorize endpoint URL and Token endpoint URL (required)
- JWKS endpoint URL or a JWKS document (at least one is required)
- UserInfo endpoint URL and Logout endpoint URL (recommended)
SAML SSO and OpenID Connect have a full description of each field.
Create a new service
- Navigate to Dashboard > Integrations > Single Sign-On Configuration.
- Click Create New Service.
- In Service type, choose SAML 2.0 or OpenID Connect. Switching types after you have started filling in fields clears the form, so pick the right one before you enter the IdP details.
- Enter a Description. This is required. It identifies the service to your admins on this page and to end users on the sign-in screen.
- Leave Status set to Enabled.
- Fill in the required fields listed above. Required fields are marked with an asterisk (*).
- Click Save.
The page reloads and the new service appears in the list with a confirmation message.
OIDC: auto-fill from a discovery document
Most IdPs publish an OpenID discovery document, typically at a .well-known/openid-configuration URL. If yours does, you can skip entering each endpoint by hand:
- Paste the discovery document URL into the Discovery URL field.
- Click Fetch configuration.
- Expert reads the document and fills in the issuer, authorize, token, user info, keys (JWKS), and logout endpoint fields that the document provides. A message tells you how many fields were filled in.
This also works with providers that use non-standard discovery paths, including AWS Cognito user pools. You will still need to enter Client ID and Client Secret by hand, since neither is part of the discovery document.
Edit an existing service
- Navigate to Dashboard > Integrations > Single Sign-On Configuration.
- Find the service you want to change.
- Click Edit at the top of the service's card.
- Update the fields you need to change.
- Click Save.
A confirmation message appears once your changes are saved. If you click Cancel after making changes, you are asked to confirm before your changes are discarded.
Secret and certificate fields (Client Secret, X.509 certificates, private key, JWKS document) never show their stored value, and leaving one blank does not clear it.
The placeholder tells you which case you are in: "Enter a new value" means nothing is stored yet, and "Enter new value to replace existing" means a value is already configured and you can leave the field blank to keep it.
Field validation
Description is required for both SAML and OIDC services. SAML also requires an Entity ID, Single Sign-On URL, and X.509 certificate. OIDC requires Client ID, Client Secret (when creating the service), Issuer, Authorize URL, Token URL, and at least one of JWKS URL or JWKS document.
If a save fails, the error appears inline on the form so you can fix it and resubmit. Your other field values persist and the form does not reset.
Service status
A service's status is either Enabled or Disabled.
Setting a service to Disabled removes it from the sign-in page, from the Single Sign-On Configuration page, and from the default sign-in provider list. A disabled service can't be re-enabled from the Dashboard. To use it again, you must recreate the service. If the service you disable is the default sign-in provider, choose a new default afterward.