How It Works
This page explains how sign-in providers behave: how accounts are matched and created at sign-in, how identities are linked across providers, which restrictions apply, how sessions behave, and what happens on deployments that have not switched to the new authentication mode yet.
What Happens at Sign-In
When a person authenticates through a provider, Qualytics resolves their identity in this order:
- Known identity. If the identity is already linked to a Qualytics account, the person signs in to that account.
- Matching email. If the identity is new but its email matches exactly one existing active account, Qualytics treats it as a request to link a new sign-in identity to that account. Whether the link happens automatically or waits for an administrator depends on the provider's linking settings (see Identity Linking below).
- New user. If no account matches and Automatic user provisioning is enabled on the provider, a new account is created with the Member role and membership in the Public team. With provisioning off, sign-in is refused and the person is told that new account creation is not enabled for the provider.
Note
On a brand new deployment with no users, the first person to sign in receives the Admin role so someone can administer the platform.
Sign-in is also refused, before any of those steps, when the identity provider sends no email address for the person, or when the email matches more than one active account. Both cases ask the person to contact an administrator and are recorded in the sign-in log with the reason.
User Provisioning
Each OIDC and SAML provider has its own Automatic user provisioning setting (on by default). It lets eligible identities create Qualytics accounts on their first sign-in. Confirm the provider's email verification, domain restrictions, and group restrictions are appropriate for every user who could authenticate, or turn the setting off to admit only accounts that already exist.
On an OIDC provider with Require verified email turned on, an identity whose email the provider does not report as verified cannot create an account, in addition to being unable to link to an existing one.
Accounts can also be created independently of provisioning:
- By an administrator, through an email invitation (requires an enabled Email & Password provider).
- Ahead of time, through Directory Sync.
Identity Linking and Approvals
Three settings on each provider control whether an identity from that provider can be attached to an existing account with the same email:
| Setting | Default | Effect |
|---|---|---|
| Cross-provider account linking | On | Allows an identity from this provider to request linking to an existing account with the same email. When off, such sign-ins are refused. |
| Require administrator approval | Off | Keeps newly proposed links pending until an administrator approves them in the Link approvals tab. |
| Require verified email (OIDC only) | Off | 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. |
While a link is pending, sign-in attempts through that provider are refused with a message that the link is awaiting administrator approval. After approval, the person simply signs in again. Rejected requests stay blocked, and because the Link approvals tab lists only pending requests, reversing a rejection is done through the API. See Review Link Approvals for the review flow.
A link is created automatically, without review, when linking is enabled and approval is not required. Require administrator approval is the setting that holds a link back for review, so leave it on for any provider you do not trust to be authoritative for each user's email address. Require verified email refuses the link outright instead of proposing it: nothing appears in the Link approvals tab, and the refusal is recorded in the sign-in log.
Access Restrictions
Each provider carries its own restrictions, evaluated at every sign-in:
| Restriction | Behavior |
|---|---|
| Allowed Email Domains | Only users with an email in the listed domains can sign in through the provider. Leave the list empty to allow all domains. |
| Allowed Groups | Only users in at least one of the listed groups can sign in. Leave empty to allow all users. Requires a Groups Claim so Qualytics knows where the provider reports group membership. |
To keep administrators from locking themselves out, Qualytics refuses restriction changes that would exclude the administrator making them: you cannot remove your own email domain from the allowed domains, remove all of your own groups from the allowed groups, disable the provider your current session signed in with, or require verified email when your own identity does not report one.
Group membership and Teams
The groups a provider reports are recorded on each account at sign-in. Group-based Team membership is a separate deployment-level capability, disabled by default, that matches reported group names to existing Team names. See Just-in-Time Provisioning and Group Sync.
Google Workspace Groups
Google's sign-in does not include group membership, so Google Workspace providers fetch it from the Google Workspace Directory instead:
- On an OIDC provider whose issuer is Google, enable Fetch Google Workspace groups. The provider then needs a one-time authorization by a Google Workspace administrator, granting read-only access to Users and Groups. Users are never asked for Directory access themselves.
- The provider cannot be enabled until the authorization is completed. The provider form shows the authorization status, who authorized it, and lets you verify, reauthorize, or disconnect the grant.
- At sign-in, the person's Workspace groups are retrieved and used like any other provider groups: for the Allowed Groups restriction and, when group-based Team membership is enabled for the deployment, for Team mapping.
Sessions
- Session Duration is set per provider (480 minutes by default). Activity extends a session, up to a deployment-wide maximum lifetime (24 hours by default), after which the person signs in again.
- Sessions end early when trust changes: disabling a provider, editing its security-sensitive settings (credentials, certificates, tightened restrictions), resetting a password, deactivating a user, or rejecting a pending link all end the affected sessions. The platform warns you with a confirmation dialog before a change that signs users out.
- For OIDC providers, Qualytics also revalidates the session against the identity provider periodically, so a user disabled at the identity provider loses access without waiting for the session to expire.
Staging and Switching Over
Administrators can create, edit, and test providers at any time, but on deployments still using their previous sign-in method the configured providers are not yet used for sign-in: the sign-in page keeps its current behavior until the new authentication mode is enabled for the deployment.
- Providers can be fully configured and tested in advance, so the switch is a verified, planned change. At least one provider must be enabled before the switch; the platform does not start in the new authentication mode while every provider is disabled.
- Deployments migrating from an environment-configured OIDC setup receive a pre-filled provider named OIDC (migrated from env vars) the first time the platform starts with no OIDC providers configured. Review it before the switch; it keeps sign-in behavior consistent with the previous configuration.
- Switching invalidates existing sessions, so it is done in a maintenance window and users sign in again afterward. For self-hosted deployments, see the self-hosted deployment guide; managed deployments coordinate the switch with Qualytics.
Audit Trail
Provider configuration changes (creation, edits with before-and-after values, deletion), sign-in successes and failures, lockouts, invitations, link approvals and rejections, and denied sign-ins (for example, an unauthorized email domain or a deactivated account) are all recorded and reviewable in the Log tab. See View the Sign-In Log.