Setting up single sign-on (SSO) with OpenID Connect (OIDC)


Zefort supports SSO with OpenID Connect (OIDC). Supported providers include Azure AD, Google, Duo, Auth0, Okta, Keycloak, Shibboleth, and others.

With these instructions, you can set up domain-wide single sign-on, where users for a particular domain name (e.g. yourcompany.com) are delegated to your OpenID provider for authentication, instead of using Zefort’s built-in authentication.

Prerequisites

You need:

  • A Zefort user with the Administrator license and the ”can manage account settings” permission
  • Access to configure the DNS records for your domain
  • An admin account on your OIDC provider

Sidenote: as a best practice, you should reserve some administrator accounts for IT personnel on your Zefort account.  Such IT admin users should only have access to configure your Zefort account settings, but no access to documents or other content.

OIDC vs. SAML

You may be aware that Zefort also support SAML for SSO, and may be wondering if you should use OIDC or SAML for this.

For a new deployment, it’s best to go with OIDC unless you are sure you need to use SAML.  OIDC is a modern protocol, and has gained widespread use also in enterprise scenarios.  Zefort will continue to support SAML for the foreseeable future, so there is no urgent need to migrate existing deployments to OIDC.

1. Add and verify domain name(s)

In order to use OIDC, you must first add and validate the domain name(s) for which authentication is delegated.

Sign in to Zefort with your administrator account, navigate to Account settings → Domains, and add your domains. Follow the instructions to configure your DNS and verify the domains.

Once the domain is verified, you will see a green indicator in the Domain name section, and you can move to the next step.

For security reasons, Zefort periodically re-checks the presence of the TXT record. Do not remove the TXT record to ensure the domain stays validated in Zefort and SSO continues to work.

2. Create an OIDC integration in Zefort

Browse to Account settings → Integrations, and select “Add another” or “Install” for OIDC Single Sign-On.

Select the domain name(s) you wish to use for SSO (e.g. yourcompany.com) and click Save.

Take note of the Redirect URI for the next step.

3. Add an application on your OIDC provider

Add a new application on your OIDC provider.  Exact steps depend on which OIDC Provider software you are using.

In general, you will need to create an application configuration for Zefort on your OIDC provider.  You will need to enter the Redirect URL the previous step.

From the OIDC provider, you will get the Issuer URL (or OIDC metadata document URL), Client ID, and Client Secret values to fill in to Zefort.

Here are specific instructions for some common OIDC providers:

Azure AD

  • Register a new application in the “App registrations” section in your Azure AD
  • In the Redirect URI section, select “Web”, and enter the Redirect URI from the previous step.
  • In “Client credentials”, create a new client secret.
  • Copy the “Secret ID” to Zefort into the “Client ID” field.
  • Copy the “Value” to Zefort into the “Client Secret” field.
  • Copy the “OpenId Connect metadata document” URL (from Overview / Endpoints) to Zefort into the “Issuer URL” field.
  • Under “Token configuration”, add a new “Access” claim for verified_primary_email .

Google

  • In Google Cloud Console, APIs & Services, create a new project for Zefort.
  • Configure application and configure the consent screen to your liking.
  • Create Oauth client ID credentials, choose “Web application” as the type.
  • In the Authorized redirect URIs section, enter the Redirect URI from the previous step.
  • Copy the “Client ID” and “Client secret” into Zefort.
  • Set https://accounts.google.com/ for the “Issuer URL” in Zefort.

4. Finish configuration and test signing in

Once both sides are configured, you may try signing in.  Enable the OIDC integration in Zefort, and try to sign in from another browser, machine, or an incognito window.  If signing in is successful, great!  If there was an issue, disable the OIDC integration in Zefort to ensure you can continue signing in.