Single sign-on

How it works

DFIRe speaks OpenID Connect and works with any standards-compliant provider. Testing covers Google Workspace, Microsoft Entra ID and Auth0. Other standards-compliant providers should work, but DFIRe does not test every vendor.

Templates for Google Workspace, Microsoft Entra ID and Okta prefill the discovery URL and the button styling. A template says nothing about testing. Okta has a template and no test coverage. Auth0 has test coverage and no template, so it uses the custom option, which is not a lesser path.

A sign-in runs like this. The user picks the provider button on the login page and authenticates at the identity provider. The provider sends them back to DFIRe with a signed token. DFIRe validates that token, matches it to an existing account or creates one, and signs the user in.

Configuration lives at Settings → Single Sign-On and needs superuser access.

Adding a provider

1. Set the application base URL

   Enter the public URL of your DFIRe instance, such as https://dfire.example.com. DFIRe builds each provider's redirect URI from it. Leave it empty to derive the URL from incoming request headers, which works for most deployments behind one reverse proxy.

2. Choose a template or a custom provider

   Select Add Provider, then pick Google Workspace, Microsoft Entra ID, Okta, or Custom OIDC Provider.

3. Enter the discovery URL and validate it

   This is the provider's .well-known/openid-configuration endpoint. Select Validate to confirm DFIRe can reach it and read usable OIDC metadata before you go further.

4. Enter the client ID and secret

   Both come from the application you register at the identity provider. Most providers show the secret once, so paste it now. DFIRe encrypts it when you save.

5. Pick a default role

   Required. New accounts from this provider land in this role. Without one they would arrive with no permissions at all.

6. Add the redirect URI at your provider

   The provider card shows the exact URI. Copy it and add it to your application's allowed redirect URIs.

7. Save

   Add & Save Provider stores the provider, its secret and its access-control settings straight away. Later edits in the provider card are saved with the page's Save Settings button.

Replacing the client secret

A saved provider shows its secret as Configured, stored encrypted rather than as an editable field, so a stray click cannot wipe it. Select Replace secret to enter a new value, or Cancel to keep the old one. DFIRe never displays a stored secret again, on the page or through the API.

Redirect URI

Every provider card shows the URI your identity provider must allow:

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

Use the Copy link rather than typing it.

Access control

By default DFIRe admits anyone the identity provider authenticates, and creates an account for them on first sign-in. Three optional gates narrow that, and a fourth is mandatory for one specific configuration.

These gates sit on top of whatever restrictions you set at the identity provider. Use them when DFIRe should admit fewer people than the provider authenticates, or as a safety net against a future mistake on the provider side.

Allow new user creation

On by default. The first sign-in from an unknown person creates a DFIRe account. Turn it off and only people who already have an account can sign in through this provider.

Restrict by email domain

Give a comma-separated list of allowed domains, such as example.com, corp.example.com. DFIRe refuses a sign-in whose provider-issued email sits in any other domain. Matching is exact and ignores case. Subdomains are not implied, so corp.example.com needs its own entry.

Require an identity provider group claim

Name a claim and list the values that grant access.

• Claim name is the claim DFIRe inspects. Common choices are groups on Keycloak and Entra ID, roles for Entra app roles, and hd for a Google hosted domain.
• Allowed values is a comma-separated list. A sign-in passes when the claim holds any one of them. The claim may be a string or an array.

A missing claim fails, and so does a claim with no matching value. Naming a claim while leaving the allowed values empty denies everyone, on purpose, so a half-finished gate cannot quietly admit the world.

Allowed Entra tenant IDs

This one appears only when the discovery URL is a multi-tenant Microsoft endpoint, meaning one containing /common/ or /organizations/. Such an endpoint accepts tokens from every Microsoft tenant in the world, and the issuer differs for each one. DFIRe therefore cannot pin a single issuer the way it does for a single-tenant URL.

Instead it requires a list of tenant GUIDs, and refuses to enable the provider without one. At sign-in it checks the issuer's format. It then confirms the token's tenant matches the tenant named in its own issuer, and requires that tenant to be on your list.

What a refused user sees

DFIRe returns the person to the login page with a message saying why. A disallowed email domain, an administrator who has not granted them access, and a missing group membership each get their own wording. Every refusal reaches the audit log with the reason, the provider and the email the identity provider returned.

Provider setup

At the identity provider, register a web application and add DFIRe's redirect URI to its allowed callback URLs. Copy the client ID and secret back into DFIRe. Your provider's own documentation says where those screens live. The discovery URLs are:

Provider	Discovery URL
Google Workspace	https://accounts.google.com/.well-known/openid-configuration
Microsoft Entra ID	https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration
Okta	https://your-org.okta.com/.well-known/openid-configuration
Auth0	https://your-tenant.auth0.com/.well-known/openid-configuration

Replace {tenant-id} with your own Entra tenant GUID. Using common or organizations there makes the provider multi-tenant and brings in the tenant allowlist requirement.

Two provider-side settings catch people out. Microsoft Entra ID can require users to be assigned to the application before they may sign in. Google Workspace restricts access through its own app access controls rather than through claims.

How accounts are provisioned

On a first sign-in DFIRe builds the account from the token's claims, unless you turned off new user creation for that provider.

DFIRe field	Comes from
Username	preferred_username, otherwise the local part of email, otherwise the sub claim. DFIRe adds a number when the name is taken.
Email	email
First name	given_name
Last name	family_name
Profile picture	picture
Phone number	phone_number

The new account gets the provider's default role. Change it afterwards in Settings → User Accounts.

The first sign-in

A brand-new SSO account lands on a Complete Your Profile screen before reaching the application. It offers the username DFIRe derived from the claims, a full name, and an optional profile picture. The email sits there read-only, because the identity provider owns it.

This is the one moment a user picks their own username. The screen accepts one once and then closes, so afterwards only an account administrator can rename them, and that change is audited. Skipping the screen is safe: the account keeps its generated username until someone changes it.

People who already have a DFIRe account never see this screen, because their account was not created by the sign-in.

The provider owns the profile

Every later sign-in refreshes the email, first name, last name and profile picture from the identity provider. A provider that sends a phone number refreshes that too. Editing those fields in DFIRe therefore lasts only until the person signs in again. Change them at the provider instead. A picture the user uploaded themselves is never overwritten.

Roles, account status and Slack ID belong to DFIRe and survive a sign-in untouched.

Linking an existing password account

Someone who already has a DFIRe password account can sign in through SSO. DFIRe links the two accounts, but only when the identity provider asserts the email as verified through the email_verified claim.

After linking, that account loses password sign-in permanently, and DFIRe removes its multi-factor authentication, including the registered authenticator and the recovery codes. The identity provider handles authentication from then on.

If the provider does not assert email verification, DFIRe refuses the sign-in instead of linking. A provider that does not prove email ownership would otherwise be a route to taking over an existing account.

Security

HTTPS

Serve DFIRe over HTTPS in production. The redirect URI has to use https://.

Client secrets

DFIRe encrypts client secrets in the database with CREDENTIAL_ENCRYPTION_KEY. Keep that key backed up, and never set it to the same value as SECRET_KEY.

Refusals are audited

Every refused SSO sign-in reaches the audit log as a LOGIN_FAIL event, carrying the reason and the email the identity provider returned. The reasons cover an unverified email, a disallowed email domain, an unsatisfied group claim, and new user creation being switched off.

Sessions

SSO accounts get the same sessions as everyone else. A session idles out after 12 hours, and activity pushes that window forward. Closing the browser ends it immediately. Users can revoke their own sessions from My Profile, and an administrator can end all of them. See Users and roles.

Troubleshooting

The redirect URI does not match

Copy the URI from the provider card again and compare it character by character with the one registered at the identity provider. The trailing slash counts.

Client authentication failed

Generate a new client secret at the identity provider, then use Replace secret on the provider card.

The discovery URL will not validate

Check that the DFIRe server itself can reach the URL. For Microsoft Entra ID, confirm you replaced {tenant-id} with a real GUID.

The email claim is missing

DFIRe needs an email to provision an account. Add the email scope and claim at the identity provider.

The user is not assigned to the application

Common with Microsoft Entra ID. Assign the user or their group to the application, or turn off the assignment requirement in the application's properties.

Refused: email not verified

The sign-in matched an existing DFIRe account by email, but the identity provider did not mark that email as verified. Turn on email verification at the provider. Keycloak has a setting for it, and Authentik binds a verification stage to the enrolment flow. If the old account should be retired instead, deactivate it and unlink its SSO identity so the next sign-in creates a fresh one. See Users and roles.

Refused: email domain not allowed

The domain gate rejected the person's email domain. Add the domain to the list if they belong, or leave it alone if they do not.

Refused: user creation disabled

New user creation is off for this provider and the person has no DFIRe account. Create one in Settings → User Accounts and ask them to try again. That first sign-in links to the new account, provided the identity provider asserts a verified email matching the address you set.

Refused: required group claim not satisfied

The token either lacked the claim you configured or carried none of the allowed values. Confirm the provider emits that claim. For Microsoft Entra ID, the app registration's token configuration decides whether groups or roles is issued. Then either add the person to the right group, or add their group's value to the allowed list.