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 you 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 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 click on “Connect” or “Connect another” for OIDC Single Sign-On.

Select the domain name(s) you wish to use for SSO (e.g. yourcompany.com), remembering to click the “+” sign after selecting each domain.

 

3. Add an application to your OIDC provider

Add a new application to your OIDC provider.  The 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 in the previous step.

The redirect URL used by Zefort is https://<YOUR INSTANCE>.zefort.com/oidc/auth_callback/, so if you are using my.zefort.com then the URL would be https://my.zefort.com/oidc/auth_callback/.

Here are specific instructions for some common OIDC providers:

Azure AD

  • Register a new application in the “App registrations” section in your Azure AD
    • Give the integration a name, such as “Zefort”
    • In the Redirect URI section, select “Web”, and enter the Redirect URL as stated above.
    • Then press “Register”
  • On the “Overview” page, copy the “Application (client) ID” in the “Client ID” field in Zefort”
  • On the “Overview” page, click “Endpoints” and copy the “OpenId Connect metadata document” URL to Zefort into the “Issuer URL” field.
  • On the “Overview” page, click the “Add a certificate or secret” next to “Client credentials”, and on that page click “New client secret”.
    • Give the secret a description and select an appropriate expiration time according to your company policies.
    • (You can also access this page by clicking “Certificates and Secrets” in the menu on the left-hand side.)
  • Copy the “Value” to Zefort into the “Client Secret” field.
  • On the “Token configuration” page, click “Add optional claim” and add a new “Access” claim for verified_primary_email .

Google

  • In Google Cloud Console, APIs & Services, create a new project for Zefort.
  • Configure the application and configure the consent screen to your liking.
  • Create Oauth client ID credentials, and 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 will first need to press “Save” on the integration (keeping it disabled) and then activate the integration by changing its status to “Active” and pressing “Save” again.  Now try to sign in from another browser, machine, or incognito window.  If signing in is successful, great!  If there is an issue, disable the OIDC integration in Zefort to ensure you can continue signing in.

5. FAQ

Which OIDC providers does Zefort support?

As OIDC is an open standard, there are no limitations to which providers Zefort can support. With that said, by default and for security reasons, we have only pre-approved certain providers. If you have your own OIDC setup or want to use a provider not in the pre-approved list, please contact our customer support and we will handle it for you. The pre-approved providers are Auth0, Azure, and Google.

I get an error after logging in to Zefort through my OIDC provider, why?

If there is an error after entering your OIDC provider’s credentials and there is no error description of the exact issue then your OIDC provider might not be sending enough info to Zefort. Zefort expects the OIDC provider to return the user’s email as part of the authentication flow. Some providers, such as Azure, do not always supply the email by default. This why it is important to make sure that an email is sent as part of the authentication flow, and in the case of Azure, to make sure that the verified_primary_email Access claim is added.

Even if the verified_primary_email claim is added, the user that is synced also needs to have their email set in their details. In Azure for instance, it might look like the email is set due to it being visible in a user’s profile, but it also needs to be set in the contact information of the user to be seen as the user’s actual email and not just as an identifier.

I’m getting an HTTP 405 error when accessing the redirect URL, why?

The redirect URL as part of the OIDC flow when going from the OIDC provider back to Zefort. This URL only supports HTTP POSTrequests and will result in an HTTP 405 Method Not Allowed if accessed by any other means. For instance, accessing the redirect URL in your browser will only make a GET request to the URL, which in turn will lead to an HTTP 405 error.