Single Sign-On (SSO)

Configure OIDC-based Single Sign-On to allow users to authenticate with your organization's identity provider.

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. User clicks the SSO provider button on the login page
  2. User is redirected to the identity provider
  3. After authentication, user is redirected back to DFIRe
  4. DFIRe creates or updates the user account based on OIDC claims
  5. User is logged in with appropriate permissions

Adding an SSO Provider

SSO Configuration
  1. Navigate to Settings > Single Sign-On

    You need administrator permissions to configure SSO.

  2. Set the Application Base URL

    Enter your DFIRe instance's public URL (e.g., https://dfire.example.com). This is used for generating callback URLs. Leave empty to auto-detect from request headers.

  3. Click "Add Provider"

    Choose a provider template (Google Workspace, Microsoft Entra ID) or select "Custom OIDC Provider" for other identity providers.

  4. Configure the Provider
    • Provider Name: Display name shown on the login button
    • Discovery URL: The OIDC discovery endpoint (.well-known/openid-configuration)
    • Client ID: From your identity provider's app registration
    • Client Secret: From your identity provider's app registration
    • Icon and Color: Customize the appearance of the login button
  5. Validate the Discovery URL

    Click "Validate" to verify the discovery URL is accessible and returns valid OIDC metadata.

  6. Click "Add Provider" to Add Configuration
  7. Select a Default Role and Save

    After adding the provider, select a default role for new SSO users and click "Save Configuration".

Important: Adding a provider does NOT automatically save the configuration. You must select a default role and click "Save Configuration" to persist your changes. The default role determines what permissions new SSO users receive on first login.

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

Google Workspace: To restrict access to your organization's domain, configure user assignment in Google Cloud Console or use Google Workspace's app access controls.

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 in DFIRe displays the exact redirect URI that must be configured in your identity provider. The format is:

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

Copy the redirect URI shown in DFIRe's provider card and add it to your identity provider's authorized redirect URIs.

Note: The redirect URI must match exactly, including the trailing slash. Mismatched URIs are a common cause of SSO authentication failures.

User Provisioning

When a user authenticates via SSO for the first time, DFIRe automatically creates an account using information from the OIDC claims:

DFIRe Field OIDC Claim
Username preferred_username or email
Email email
First Name given_name
Last Name family_name

Default Role

New users created via SSO are assigned the default role configured for that provider. Administrators can later adjust user roles as needed.

Note: If no default role is selected, SSO users will be created without any role assignment and will have limited access until an administrator assigns them a role.

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. Keep this key secure and backed up.

Access Control

DFIRe does not control which users can authenticate via SSO. Configure access control (who can sign in) in your identity provider:

  • Google: Use app access settings in Google Workspace admin
  • Microsoft: Configure user assignment in the Enterprise Application settings
  • Auth0: Use Auth0 rules or application settings

Session Management

SSO users get the same session management as local users:

  • Sessions can be revoked by administrators
  • 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"

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

Invalid Client Secret

Error: "Client authentication failed"

Solution: Regenerate the client secret in your identity provider and update it in DFIRe. Remember to click "Save Configuration" after updating.

User Not Assigned to Application

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

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

Missing Email Claim

Error: "Email claim not found"

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

Discovery URL Validation Fails

Solution: Verify the discovery URL is accessible from your DFIRe server. For Microsoft, ensure you've replaced {tenant-id} with your actual tenant ID.