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).
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.
- Choose SAML or OIDC. Switching types after you have started filling in fields clears the form, so pick the right one before you enter the IdP details.
- Fill in the required fields listed above.
- 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.
- Save.
The new service appears in the list immediately, whether it is set to Active or Inactive.
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 authorize, token, issuer, and keys endpoint fields.
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.
- Save.
A confirmation message appears once your changes are saved.
Secret and certificate fields (Client Secret, X.509 certificate, 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, 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
Setting a service to Inactive removes it from the sign-in page. Users will not see it as a sign-in option, but the configuration is preserved and you can reactivate it later.
Both Active and Inactive services stay listed on the Single Sign-On Configuration page.