Single Sign-On (SSO)

Overview

DFIRe supports OpenID Connect (OIDC) for Single Sign-On. The following providers have been tested:

• Google Workspace
• Microsoft Entra ID (formerly Azure AD)
• Auth0

Any OIDC-compliant identity provider should work, though compatibility cannot be guaranteed for untested providers.

How it works

1. The user clicks the SSO provider button on the login page.
2. The user is redirected to the identity provider and authenticates there.
3. The identity provider redirects back to DFIRe with a signed token.
4. DFIRe matches the token to an existing user or, if access controls permit, creates a new account from the token's claims.
5. The user is signed in with the role configured for that provider.

Adding a provider

1. Navigate to Settings → Single Sign-On

   Superuser access is required to configure SSO.

2. Set the Application Base URL

   Enter your DFIRe instance's public URL (for example https://dfire.example.com). This URL is used to build the redirect URI shown on each provider card. Leave it empty to auto-detect from incoming request headers, which is fine for most deployments behind a single reverse proxy.

3. Click "Add Provider"

   Choose a template (Google Workspace, Microsoft Entra ID, Okta) or pick "Custom OIDC Provider" for anything else.

4. Fill in the provider details
   • Provider name: Display name shown on the login button.
   • Discovery URL: The OIDC discovery endpoint (.well-known/openid-configuration). Click Validate to confirm DFIRe can reach the URL and read valid OIDC metadata before continuing.
   • Client ID and Client secret: From your identity provider's app registration. The client secret is shown only once by most providers; the value you paste is stored encrypted as soon as you save the dialog.
   • Default role: Required. The role new users are placed in when they sign in through this provider for the first time. Without one, a new user would land with no permissions.
   • Access control: Optional gates that restrict who is allowed to sign in through this provider. See the next section.
   • Icon and colour: Customize the login button.
5. Click "Add & Save Provider"

   The provider, its secret, and any access-control settings are persisted immediately. You can leave the page right after, or continue editing in the per-provider card below — those subsequent edits are saved with the page-level Save Settings button.

Updating the client secret later

When a saved provider is opened in the per-provider card, the client secret appears as "Configured · stored encrypted" rather than as an editable field, so an accidental click cannot overwrite it. Click Replace secret to swap it for a new value, or Cancel to keep the existing one. The encrypted secret is never displayed back, on the page or in API responses.

Access control

By default, anyone the identity provider authenticates is allowed to sign in to DFIRe (and a new DFIRe account is created on first login). Three optional gates can be enabled per provider to narrow that down.

Allow new user creation

When this toggle is on (the default), the first SSO login from a new person automatically provisions a DFIRe account. When it is off, only users who already exist in DFIRe can sign in through this provider — new accounts are not created.

Restrict by email domain

Enable this toggle and provide a comma-separated list of allowed email domains (for example example.com, corp.example.com). Logins whose IdP-issued email is in a different domain are rejected with a clear message. Matching is exact and case-insensitive; subdomains are not implicit (corp.example.com is a separate entry from example.com).

Require IdP group claim

Enable this toggle to require a named claim with one of an allowed list of values. Fill in:

• Claim name: The JWT claim DFIRe should inspect, for example groups (Keycloak, Entra ID), roles (Entra app roles), or hd (Google hosted domain).
• Allowed values: A comma-separated list. A login is accepted if the token's claim contains any of these values. The claim may be a string or an array.

If the claim is missing from the token, or none of its values match, the login is rejected. If the claim name is set but the allowed-values list is empty, all logins are denied — a deliberate fail-closed default so a half-configured gate doesn't silently let everyone through.

What rejected users see

When a sign-in is refused by any of the gates above, the user is sent back to the DFIRe login page with a message explaining why — "your email domain is not allowed", "your administrator has not granted you access to this application", "your identity provider did not return the required group membership", and so on. The audit log records every refused SSO login with the reason, the provider, and the email value the IdP returned.

Provider Setup Examples

Google Workspace

1. Go to Google Cloud Console
2. Create or select a project
3. Go to "APIs & Services" > "Credentials"
4. Click "Create Credentials" > "OAuth client ID"
5. Select "Web application"
6. Add the authorized redirect URI shown in DFIRe's provider configuration
7. Note the Client ID and Client Secret
8. In DFIRe, use:
   • Discovery URL: https://accounts.google.com/.well-known/openid-configuration

Microsoft Entra ID

1. Go to Azure Portal > Microsoft Entra ID > App registrations
2. Click "New registration"
3. Enter a name (e.g., "DFIRe")
4. Set "Supported account types" based on your needs
5. Add the redirect URI shown in DFIRe's provider configuration
6. After creation, note the Application (client) ID
7. Go to "Certificates & secrets" and create a new client secret
8. In DFIRe, use:
   • Client ID: The Application (client) ID
   • Client Secret: The secret value you created
   • Discovery URL: https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration

Auth0

1. Go to Auth0 Dashboard > Applications > Applications
2. Click "Create Application"
3. Select "Regular Web Applications"
4. In Settings, add the redirect URI shown in DFIRe's provider configuration to "Allowed Callback URLs"
5. Note the Client ID and Client Secret
6. In DFIRe, use:
   • Discovery URL: https://your-tenant.auth0.com/.well-known/openid-configuration

Redirect URI configuration

Each SSO provider card in DFIRe displays the exact redirect URI that must be added to your identity provider's allowed redirect URIs. The format is:

https://your-dfire-domain.com/oidc/callback/{provider-id}/

Click the Copy link on the provider card and paste the URI into your identity provider's app registration.

User provisioning

When a user signs in via SSO for the first time, DFIRe creates an account from the token's claims (unless the "Allow new user creation" toggle has been turned off for that provider):

DFIRe field	OIDC claim
Username	preferred_username, falling back to the local part of email, then a generated value
Email	email
First name	given_name
Last name	family_name
Profile picture	picture (downloaded once on first login, refreshed on each subsequent login unless the user has uploaded a local picture)

Default role

New users created via SSO are placed in the default role configured for that provider. Administrators can later promote, demote, or move users to a different role. The provider cannot be saved without a default role set.

Profile updates on every sign-in

Each subsequent SSO sign-in refreshes the user's email, name, and profile picture from the identity provider — the IdP is treated as the source of truth for profile fields. Editing these fields directly on the DFIRe user record is therefore temporary; the values are overwritten on the next SSO sign-in. To change a user's email or name permanently, change it at the identity provider.

Linking an existing local account

If a person has an existing DFIRe account with username/password access and then signs in via SSO for the first time, DFIRe will link the SSO identity to that local account — but only if the identity provider asserts the email as verified (the email_verified claim is true). After linking, password-based login is permanently disabled on that account. If the identity provider does not assert email verification, the sign-in is refused with a clear message; no silent linking is performed.

Security considerations

HTTPS required

SSO requires HTTPS in production. The redirect URI must use https://.

Client secret storage

Client secrets are stored encrypted in the database using the CREDENTIAL_ENCRYPTION_KEY environment variable. Keep this key secure and backed up, and never reuse the value of SECRET_KEY.

Defense in depth

The three access-control gates (allow new user creation, restrict by email domain, require IdP group claim) layer on top of whatever access controls you configure at the identity provider. Use them whenever DFIRe should admit a narrower population than the IdP authenticates, or as a safety net against a future IdP-side misconfiguration. All three default to off / permissive, so existing deployments are unaffected on upgrade.

Refused sign-ins are audited

Every refused SSO sign-in is recorded in the audit log as a LOGIN_FAIL event, with the reason (email not verified, domain not allowed, JIT disabled, required group claim not satisfied, deactivated account) and the email value the identity provider returned.

Session management

SSO users get the same session management as local users:

• Sessions can be revoked by administrators (see Force Logout).
• All sessions are logged with IP and user agent.
• Session timeout is configurable.

Troubleshooting

Common issues

Redirect URI mismatch

Error: "The redirect URI in the request does not match"

Resolution: Ensure the redirect URI in your identity provider exactly matches the one shown in DFIRe's provider card, including the trailing slash.

Invalid client secret

Error: "Client authentication failed"

Resolution: Regenerate the client secret in your identity provider, then click Replace secret on the provider card in DFIRe and paste the new value.

User not assigned to application

Error: "User is not assigned to this application" (common with Microsoft Entra ID)

Resolution: In Microsoft Entra ID, go to the app's "Users and groups" and assign users or groups, or disable user assignment requirement in the app's properties.

Missing email claim

Error: "Email claim not found"

Resolution: Ensure your identity provider is configured to include the email scope and claim. Email is required for user provisioning.

Discovery URL validation fails

Resolution: Verify the discovery URL is reachable from the DFIRe server. For Microsoft Entra ID, make sure you've replaced {tenant-id} in the URL with your actual tenant ID.

Login refused with "email not verified"

Shown when an SSO sign-in resolves to an existing DFIRe account by email, but the identity provider did not mark the email as verified.

Resolution: Enable email verification at the identity provider (for example, in Keycloak: realm settings → require verified email; in Authentik: bind a verification stage to the enrollment flow). Or, if the local account should be retired, deactivate it and then unlink its SSO identity from Settings → User Accounts so that the next SSO sign-in creates a fresh account.

Login refused with "email domain not allowed"

Shown when the email-domain gate is enabled and the user's email is in a domain that is not on the allow-list.

Resolution: If the user should be admitted, add their domain to the allow-list in the provider configuration. If they should not, no action is needed — the gate is doing its job.

Login refused with "user creation disabled"

Shown when "Allow new user creation" is off for the provider and a person without a pre-existing DFIRe account tries to sign in.

Resolution: Provision the user manually in Settings → User Accounts, then ask them to retry SSO sign-in. The first SSO sign-in will link to the new local account if the identity provider asserts a verified email matching the manually-set address.

Login refused with "required group claim not satisfied"

Shown when the group-claim gate is enabled and the user's token either does not include the configured claim or includes it without any of the allowed values.

Resolution: Confirm that the identity provider emits the claim you configured. For Microsoft Entra ID, make sure the app registration's token configuration is set to issue groups or roles. If the user genuinely should have access, add them to the appropriate group on the IdP side, or add their group's value to the provider's allowed-values list.