Add an OIDC Provider

Use the Add Provider action to connect an OpenID Connect identity provider such as Microsoft Entra ID, Okta, Google Workspace, or Keycloak, so users can sign in to Qualytics with their corporate identity.

Permissions

Only users with the Admin role can manage sign-in providers. See the Permissions page for details.

Field reference

The Add Provider form shows the sections below when OpenID Connect is selected. Providing a Discovery URL fills in the endpoint fields for you, so most providers need only the General and Connection sections plus that one URL.

General

Identifies the provider to the people who sign in with it.

Field	Required	Type	Description
Display Name		Text	The name shown to users on the sign-in page.

Connection

How Qualytics authenticates to your identity provider, and how long the resulting sessions last.

Field	Type	Description
Client ID	Text	The client identifier from your identity provider's application registration.
Client Secret	Text	The client secret from your identity provider. Required for both client secret authentication methods, which are the only ones the platform supports. Stored securely and never displayed again; enter it again only to replace it.
Scopes	List	The OAuth scopes requested from the provider (e.g., `openid`, `email`, `profile`). Type a scope and press Enter to add each one. Add `offline_access` so Qualytics keeps confirming accounts with the provider during a session; see the tip below.
Token Auth Method	Option	How Qualytics authenticates to the token endpoint: Client Secret (POST) or Client Secret (Basic). The field starts empty, and left that way Qualytics uses Client Secret (POST). The list also shows Private Key JWT and None (Public Client), greyed out because the platform does not support them.
Token Lifetime	Number	In minutes. Defaults to `30`, and any whole number greater than `0` is accepted, with no maximum. It applies only as a fallback for the session length, when Session Duration is left empty, so Session Duration is what governs how long sessions last in practice.
Back-channel logout	Checkbox	Lets the identity provider sign users out of Qualytics through back-channel logout requests. The Back-channel Logout URI you register at the identity provider belongs to the saved provider, so it appears when you reopen the provider to edit it, not while you are creating it.
Session Duration	Number	How long a Qualytics session stays valid after sign-in, in minutes. Defaults to `480`, which is 8 hours. Any whole number greater than `0` is accepted, but the deployment caps every session at its maximum session lifetime, 24 hours by default, so a longer value has no further effect. See Sessions.

Catch disabled accounts sooner with the offline_access scope

Sessions last their configured Session Duration, up to the deployment's maximum session lifetime, whether or not this scope is set. What the scope changes is how quickly Qualytics notices that an account has been disabled at your identity provider.

The access the identity provider grants at sign-in typically expires after about an hour. While it is valid, Qualytics reconfirms the account with the provider as the session is extended. Adding offline_access lets Qualytics renew that access silently, so the reconfirmation continues for the whole session: an account you disable at the identity provider is signed out at the next session extension, rather than lasting until the maximum session lifetime or until that person next signs in. Revoking access in Qualytics itself (deactivating the user, disabling the provider, revoking the link) always takes effect immediately.

For the scope to take effect, your identity provider's application registration must permit it, and the provider's UserInfo Endpoint must be filled in. The scope is set once on the provider and applies to every user of it, starting at each user's next sign-in.

Google Workspace grants offline access through its own mechanism instead of the standard scope, so the Test flags offline_access with a warning on Google providers. Add the scope anyway: Qualytics converts the request to the form Google expects, and the warning does not block saving. Google reports a suspended or deleted Workspace account by refusing the renewal, so the scope is what lets Qualytics act on it during a session. See Staying Signed In.

Endpoints

Where Qualytics sends users to authenticate and where it verifies the result. Fill in the Discovery URL and the rest are filled in for you; the section is titled Discovered Endpoints once that happens.

Field	Type	Description
Discovery URL	Text	Your identity provider's OpenID Connect discovery endpoint (e.g., `https://example.com/.well-known/openid-configuration`). Providing it fills in the fields below automatically, including the required JWKS URI and Issuer, so those two only need your attention when you enter the endpoints by hand.
Authorization Endpoint	Text	URL where users are redirected to authenticate.
Token Endpoint	Text	URL used to exchange the authorization code for tokens.
UserInfo Endpoint	Text	URL used to fetch the authenticated user profile. Fill it in on any provider people sign in with every day. Qualytics reconfirms an active session against this endpoint, so without it sessions run their full duration without ever being checked back with the provider. An empty value still lets people sign in, using the verified claims in the ID token, and the Test reports this check as Skipped.
JWKS URI	Text	URL used to fetch the signing keys for token verification.
Issuer	Text	The expected issuer value in ID tokens. It must match the issuer in the discovery document character for character.

Note

Identity provider URLs must use HTTPS.

The Issuer must match exactly

The Issuer is compared with the discovery document's issuer character for character, so even a trailing slash difference fails the Test. A mismatched issuer rejects every ID token at sign-in, locking users out of the provider.

Claim Mapping

Only needed when your identity provider names its claims differently from the defaults.

Field	Required	Type	Description
OIDC Claim Mapping		Mapping	Maps Qualytics user fields to the claim names your identity provider emits. The supported fields are `id`, `email`, `name`, and `picture`. Leave the mapping empty to use the provider defaults.

Access Restriction

Who is allowed to sign in through this provider, and what their group membership grants them.

Field	Type	Description
Groups Claim	Text	The identity provider claim containing group memberships. Without it no groups are read, and the groups that are read appear in the Identity Provider Groups field of the Edit User dialog. Hidden on Google Workspace providers, which get group membership from the Directory instead (see Google Workspace Groups below).
Allowed Groups	List	Only users in these groups can sign in. Leave empty to allow all users.
Allowed Email Domains	List	Only users with an email in these domains can sign in. Leave empty to allow all domains.
Require verified email	Checkbox	Refuses to link an identity to an existing account, or to create a new account for it, unless the provider reports the email as verified. Sign-ins by already-linked users are not affected. Off by default, because many providers do not report it.
Sync groups to Teams	Checkbox	Adds users to Teams whose name matches a group this provider presents. Add-only: membership is never revoked. Off by default, and unavailable until Groups Claim holds a value. See Just-in-Time Provisioning and Group Sync.

Provisioning and Linking

What happens when someone signs in with an identity Qualytics has not seen before.

Field	Type	Description
Automatic user provisioning	Checkbox	Creates a Qualytics user after a successful sign-in when the identity is not linked to an account yet. On by default.
Cross-provider account linking	Checkbox	Allows an identity from this provider to request linking to an existing account with the same email. On by default.
Require administrator approval	Checkbox	Keeps newly proposed cross-provider links pending until an administrator approves them in Link approvals. Off by default, so links are created without review unless you turn it on.

Info

For how provisioning, linking, and restrictions behave at sign-in, see How It Works.

Steps

Step 1: Open Settings from the left sidebar, click the Access tab, and open the Providers tab.

Step 2: Click the Add Provider button, or select Provider from the Add menu in the top right corner.

Step 3: The Add Provider modal appears.

Step 4: Select OpenID Connect as the provider type.

Step 5: Fill in the provider fields (see Field reference above).

Step 6: Click the Test button and review the results.

Step 7: Click the Create button.

Step 8: A dialog displays the Redirect URI for the new provider. Copy it and register it in your identity provider's application configuration.

Step 9: Click the Done button. A success message appears and the provider is listed in the Providers tab.

Google Workspace Groups

When the provider's Issuer is Google (accounts.google.com), the form shows a Google Workspace Directory section, because Google's sign-in does not include group membership. On these providers the Groups Claim field is replaced by the toggle below, and Allowed Groups appears once the toggle is on:

Step 1: Enable Fetch Google Workspace groups to retrieve each user's groups from the Google Workspace Directory at sign-in.

Step 2: Create the provider. It stays disabled until the Directory access is authorized.

Step 3: Enable the Admin SDK API in Google Cloud, then click Authorize on the provider and complete the consent as a Google Workspace administrator. The grant gives Qualytics read-only access to Users and Groups; individual users are never asked for Directory access.

Step 4: The provider shows Administrator connected with the authorizing administrator's email. You can now enable the provider.

Tip

Use the Verify button on the provider to confirm the authorization is still valid, and Reauthorize if it needs to be renewed.

With the grant in place, the fetched groups drive the Allowed Groups restriction and, when Sync groups to Teams is on for this provider, Team mapping. See How It Works.