Skip to content

SSO / Identity

DIBOP supports Single Sign-On (SSO) to integrate with your organisation's identity provider. This allows users to sign in with their corporate credentials and centralises authentication management.

Supported Providers

DIBOP supports any identity provider that implements the OpenID Connect (OIDC) protocol, including:

Provider Notes
Microsoft Entra ID (Azure AD) Fully supported, including group-based role mapping
Okta Fully supported
Auth0 Fully supported
Google Workspace Supported for Google-managed organisations
PingIdentity Supported via OIDC
OneLogin Supported via OIDC
Custom OIDC Provider Any OIDC-compliant provider

Setting Up SSO

Prerequisites

Before configuring SSO, you will need:

  • Administrative access to your identity provider
  • The following information from your identity provider:
    • Client ID: The application/client identifier
    • Client Secret: The application secret (keep this secure)
    • Discovery URL: The OIDC discovery endpoint (usually https://<provider>/.well-known/openid-configuration)
    • Scopes: Typically openid profile email

Step 1: Register DIBOP in Your Identity Provider

In your identity provider, create a new application registration:

Setting Value
Application Name DIBOP
Application Type Web Application
Redirect URI https://<your-instance>.dibop.ca/auth/callback
Logout URI https://<your-instance>.dibop.ca/auth/logout
Scopes openid, profile, email

Step 2: Configure SSO in DIBOP

  1. Navigate to SETTINGS > Enterprise Settings (Enterprise Admin) or Platform Config > Identity (Platform Admin)
  2. Click Configure SSO
  3. Enter the details from your identity provider:
Field Description
Discovery URL The OIDC discovery endpoint URL
Client ID Your application's client ID
Client Secret Your application's client secret
Scopes Space-separated list (default: openid profile email)
Claim Mappings How identity provider claims map to DIBOP user fields
  1. Click Save

Step 3: Test SSO

  1. Click Test SSO Connection
  2. You are redirected to your identity provider
  3. Sign in with a test account
  4. Verify you are redirected back to DIBOP with the correct user information

Test Before Enforcing

Always test SSO with a non-critical account before enabling "SSO Only" mode, which disables password-based login.

Step 4: Enable SSO

Choose an SSO mode:

Mode Description
Optional Users can sign in with SSO or username/password
Preferred The SSO button is prominent; password login is available but de-emphasised
Required Only SSO login is available; password login is disabled

User Provisioning

Just-In-Time (JIT) Provisioning

When a user signs in via SSO for the first time, DIBOP automatically creates an account:

  • Display Name is populated from the identity provider's name claim
  • Email is populated from the email claim
  • Role defaults to Viewer (unless role mapping is configured)

Role Mapping

Map identity provider groups or claims to DIBOP roles:

Identity Provider Group/Claim DIBOP Role
dibop-admins Enterprise Admin
dibop-users Viewer

Configure role mapping in the SSO settings:

Claim: groups
Mapping:
  "dibop-admins" → Enterprise Admin
  "dibop-users"  → Viewer
  default        → Viewer

When a user's group membership changes in the identity provider, their DIBOP role updates on their next login.

SCIM Provisioning

Coming Soon

SCIM (System for Cross-domain Identity Management) provisioning is planned for a future release. This will enable automatic user creation and deactivation based on your identity provider's directory.

Currently, user provisioning is handled by JIT (on first login) or manual creation by an Enterprise Admin.

Claim Mappings

DIBOP expects specific user attributes from the identity provider. Map your provider's claims to DIBOP's expected fields:

DIBOP Field Default OIDC Claim Description
Email email User's email address (used as login ID)
Display Name name User's full name
First Name given_name User's first name
Last Name family_name User's last name
Groups groups Group memberships (for role mapping)
Enterprise ID Custom claim Maps user to a specific enterprise (multi-enterprise setups)

If your identity provider uses different claim names, configure the mapping in the SSO settings.

Fallback Authentication

Password Fallback

When SSO is configured as Optional or Preferred, users can fall back to username/password login. This is useful when:

  • The identity provider is temporarily unavailable
  • External users (partners, vendors) do not have accounts in your identity provider
  • During initial SSO setup and testing

Emergency Access

If SSO is configured as Required and the identity provider is down:

  • Enterprise Admins with a previously set password can access an emergency login page at /auth/emergency
  • This page is only accessible when the identity provider is unreachable
  • Emergency access is logged in the audit trail

Set an Emergency Password

Even in SSO-required mode, at least one Enterprise Admin should have a password set for emergency access.

Multi-Enterprise SSO

If your organisation has multiple DIBOP enterprises (e.g., different divisions or regions), SSO can route users to the correct enterprise based on identity provider claims:

  1. Configure a custom claim (e.g., dibop_enterprise_id) in your identity provider
  2. Map this claim in DIBOP's SSO configuration
  3. When a user logs in, DIBOP reads the claim and assigns them to the appropriate enterprise

Security Considerations

Token Handling

  • DIBOP uses the Authorization Code Flow with PKCE for maximum security
  • Access tokens are stored in secure, HTTP-only cookies
  • Refresh tokens are used to maintain sessions without re-authentication
  • Tokens are validated on every request

Session Termination

When a user signs out of DIBOP:

  • The DIBOP session is terminated
  • If configured, a back-channel logout notification is sent to the identity provider
  • The user may still be signed in to the identity provider (SSO session)

Certificate Rotation

If your identity provider rotates its signing certificates:

  • DIBOP automatically discovers new certificates via the OIDC discovery endpoint
  • No manual intervention is required
  • Certificate rotation does not interrupt active sessions

Troubleshooting

Issue Solution
SSO redirect fails Verify the Redirect URI in your identity provider matches exactly
User not created on first login Check that the email claim is present in the token
Wrong role assigned Review the role mapping configuration and verify group claims
"Invalid state" error Clear browser cookies and try again
Token expired immediately Check for clock skew between DIBOP and the identity provider

Next Steps