Skip to main content
Generic OIDC works with any OpenID Connect 1.0–compliant Identity Provider — Okta, Microsoft Entra ID, Google, Auth0, Keycloak, JumpCloud, OneLogin, and others. This guide covers what you fill in on the firmly Connect side. For provider-specific application setup steps (creating the OIDC application, granting scopes, mapping claims), refer to your IdP’s own integration documentation.

​
Prerequisites

Before you start, make sure you have:
  • At least one verified domain in firmly Connect — see Verify a Domain.
  • An OIDC application registered in your IdP that issues an ID token containing the user’s email. You will need its Client ID, Client Secret, and Issuer URL.
  • Permission to configure the redirect (callback) URI on your IdP application. firmly will give you the exact URL to register.

​
Get the firmly Callback URL

When you open the OIDC configuration form in firmly Connect, the page displays a read-only Callback URL with a copy button. This URL is the OAuth2 / OIDC redirect URI that your IdP will send the user back to after authentication. You must register this exact URL as a permitted redirect URI in your IdP’s OIDC application before the integration will work.
The Callback URL is deployment-specific — copy it directly from the firmly Connect Dashboard rather than guessing or hand-typing it. A single character mismatch will cause your IdP to reject the redirect with a redirect_uri error.
Callback URL panel with copy button

​
Add an OIDC Identity Provider

1

Open Settings → Single Sign-On

Navigate to the Single Sign-On page in your firmly Connect Dashboard settings.
2

Click Add Identity Provider

The IdP picker dialog opens with all available protocols.
3

Select OpenID Connect

Click the OpenID Connect tile to open the configuration form.
4

Fill in the form fields

See the Field reference below for every field.
5

Click Save

The IdP is created in disabled state. You can now test it, bind it to verified domains, and enable it.
IdP picker with OpenID Connect tile

​
Field reference

FieldRequiredWhat to enter
Issuer URLYesThe OIDC issuer URL of your IdP — must use https:// (for example, https://accounts.google.com). The form accepts either the bare issuer URL or the full …/.well-known/openid-configuration discovery URL; firmly canonicalizes it on save.
Client IDYesThe Client ID for the OIDC application you registered in your IdP.
Client SecretYesThe Client Secret for that application. Stored encrypted; the field is masked with a show / hide toggle.
Email ClaimNoThe JWT claim name that contains the user’s email address. Leave empty to use the standard email claim — change only if your IdP exposes the email under a non-standard claim name.
OpenID Fields
firmly automatically requests the openid profile email scopes when initiating the OIDC flow — you do not configure scopes on the form. Make sure your IdP application allows these scopes.

​
Bind the IdP to verified domains

The IdP configuration form includes an Authorized Domains section listing every domain you have verified. Each verified domain appears as a toggle.
  • Turn on the toggle for each domain you want this IdP to handle.
  • A single IdP can be bound to multiple domains.
  • A single domain can be bound to multiple IdPs (users will be presented with a choice at sign-in).
  • At least one domain must be bound before the IdP can be enabled.
Unverified domains do not appear in this list. To bind a new domain to this IdP, verify the domain first — it will then show up here automatically.

​
Enable the IdP

The Enabled toggle at the top of the form becomes available once:
  • All required fields are filled and pass validation, and
  • At least one verified domain is bound under Authorized Domains.
Toggle Enabled on to make the IdP usable for sign-in. A disabled IdP keeps all its configuration but cannot complete authentication for any user.

​
Test the connection

The Test Connection button appears on the IdP form in edit mode (after the initial save), provided there are no unsaved changes and all required fields are filled. Clicking Test Connection performs a real OIDC round trip against your IdP:
  1. firmly redirects you to your IdP’s authorization endpoint.
  2. You authenticate with a real account at your IdP.
  3. Your IdP redirects back to firmly with an authorization code.
  4. firmly exchanges the code for an ID token, validates the signature against your IdP’s JWKS, and extracts the configured claims.
On success, the form displays the extracted claims (email, name, sub). On failure, it displays a formatted error explaining where the round trip broke down (for example, invalid_client, redirect_uri_mismatch, signature verification failure, missing email claim).
Always run Test Connection successfully before enabling the IdP for a domain that you plan to enforce SSO on. A misconfigured IdP combined with enforcement will lock users out of the dashboard until the configuration is fixed.
Test Connection button and success result

​
Rotate the Client Secret

If you rotate the Client Secret in your IdP (or it leaks and you need to invalidate it):
  1. Generate a new Client Secret in your IdP application.
  2. Open the IdP configuration in firmly Connect, paste the new value into Client Secret, and click Save.
  3. Run Test Connection to confirm the new secret works.
There is no separate “rotate” workflow — updating the field and saving is the rotation.

​
Disable or delete the IdP

  • Disable — turn the Enabled toggle off on the form. The configuration is preserved, the IdP is removed from sign-in, and any domain enforcement that depended solely on this IdP becomes unavailable.
  • Delete — from the IdP row’s actions menu on the SSO page, choose Delete. This is a hard delete, recorded in the audit log, and will unbind the IdP from any domains that referenced it.

​
Troubleshooting

The discovery document at <issuer-url>/.well-known/openid-configuration must be reachable from firmly, and its issuer field must match the configured Issuer URL exactly (per OIDC §4.3). If you used a discovery URL in the form, firmly stores the bare issuer URL after canonicalization — reopen the form to see the stored value.

​
Next steps

Verify a Domain

Add and verify the domains you want this IdP to handle, and enable enforcement when you’re ready.

SSO Overview

Recap the full setup flow and per-domain enforcement model.