Single Sign-On Integration Guide¶

Table of Contents¶

1. Introduction and Overview
2. Configuration Steps
3. Dashboard Configuration
4. Backend Configuration
5. Testing Login
6. Troubleshooting
7. Supported Providers

Introduction and Overview¶

This guide provides step-by-step instructions for integrating Single Sign-On (SSO) with the digna platform using OpenID Connect (OIDC).

What is SSO?¶

Single Sign-On allows users to log in to digna securely using their enterprise credentials through external identity providers. Users can authenticate with their corporate credentials instead of managing separate digna passwords.

How It Works¶

SSO in digna is implemented using the OIDC protocol. Multiple identity providers can be configured in parallel by adjusting two key configuration files:

• dashboard_config.toml — Controls the frontend login interface
• config.toml — Configures the backend OIDC connections

Supported Providers¶

Examples in this guide use Microsoft and Google, but any OIDC-compliant provider can be integrated following the same structure.

Common OIDC providers include: - Microsoft Entra ID (Azure AD) - Google Workspace - Okta - Auth0 - Keycloak - Other OIDC-compliant identity providers

Configuration Steps¶

SSO configuration requires updates to two files. This section explains how to configure each one.

Overview of Configuration Files¶

Both files must be configured for SSO to work properly.

Dashboard Configuration¶

File Location¶

dashboard/dashboard_config.toml

Step 1: Add OIDC Providers¶

Add entries under the [[login.oidc]] array for each identity provider you want to support.

Example with Microsoft and Google:

[[login.oidc]]
key = "microsoft"
label = "Login with Microsoft"

[[login.oidc]]
key = "google"
label = "Login with Google"

Step 2: Configure Login Options¶

Specify whether password-based login should be allowed:

[login]
usePassword = true

Configuration Parameters¶

[[login.oidc]] Section¶

[login] Section¶

Understanding usePassword¶

If usePassword = true: - Login screen shows SSO buttons (e.g., "Login with Microsoft") - Login screen also shows username and password fields - Users can authenticate with either method - Allows hybrid setups where some users use SSO and others use passwords

If usePassword = false (or omitted): - Login screen shows only SSO buttons - No username/password fields - Only OIDC authentication is available

💡 Tip

Password-based login is only available for users who were created with passwords using the digna user add command or via the dashboard.

Complete Example¶

[login]
usePassword = true

[[login.oidc]]
key = "microsoft"
label = "Login with Microsoft"

[[login.oidc]]
key = "google"
label = "Login with Google"

[[login.oidc]]
key = "okta"
label = "Login with Okta"

Backend Configuration¶

File Location¶

/config.toml

(Root digna installation directory)

Step 1: Add OIDC Provider Sections¶

Each provider must have a dedicated [oidc.<key>] section. The key must match the key defined in dashboard_config.toml.

Microsoft Configuration¶

[oidc.microsoft]
DIGNA_OIDC_CLIENT_ID = "<client_id>"
DIGNA_OIDC_CLIENT_SECRET = "<client_secret>"
DIGNA_OIDC_REDIRECT_URI = "http://localhost:5173/oidc/callback"
DIGNA_OIDC_CONFIGURATION_URL = "https://login.microsoftonline.com/<tenant_id>/v2.0/.well-known/openid-configuration"

Google Configuration¶

[oidc.google]
DIGNA_OIDC_CLIENT_ID = "<client_id>"
DIGNA_OIDC_CLIENT_SECRET = "<client_secret>"
DIGNA_OIDC_REDIRECT_URI = "http://localhost:5173/oidc/callback"
DIGNA_OIDC_CONFIGURATION_URL = "https://accounts.google.com/.well-known/openid-configuration"

Configuration Parameters¶

⚠️ Important

Replace placeholder values (<client_id>, <client_secret>, <tenant_id>) with actual credentials from your identity provider's developer portal.

Redirect URI¶

The redirect URI must be the same in your identity provider configuration:

http://localhost:5173/oidc/callback

If digna is hosted at a different domain, update accordingly: - Local: http://localhost:5173/oidc/callback - Production: https://digna.yourdomain.com/oidc/callback

Complete Example¶

[oidc.microsoft]
DIGNA_OIDC_CLIENT_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
DIGNA_OIDC_CLIENT_SECRET = "abc123xyz789def456ghi"
DIGNA_OIDC_REDIRECT_URI = "https://digna.yourdomain.com/oidc/callback"
DIGNA_OIDC_CONFIGURATION_URL = "https://login.microsoftonline.com/12345678-1234-1234-1234-123456789012/v2.0/.well-known/openid-configuration"

[oidc.google]
DIGNA_OIDC_CLIENT_ID = "123456789-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com"
DIGNA_OIDC_CLIENT_SECRET = "google_secret_xyz789"
DIGNA_OIDC_REDIRECT_URI = "https://digna.yourdomain.com/oidc/callback"
DIGNA_OIDC_CONFIGURATION_URL = "https://accounts.google.com/.well-known/openid-configuration"

Testing Login¶

After completing the configuration, verify that SSO is working correctly.

Pre-Testing Checklist¶

Before testing, ensure:

• [ ] dashboard_config.toml has been updated with OIDC providers
• [ ] config.toml has been updated with OIDC credentials
• [ ] Both files have been saved
• [ ] Credentials are correct (client ID, client secret)
• [ ] Redirect URI matches your deployment URL
• [ ] Identity provider application is configured with the redirect URI

Testing Steps¶

Step 1: Restart Services¶

Restart the digna backend and web server to apply changes.

If running as Windows service:

cd C:\path\to\digna\bin
stop_service.bat
start_service.bat

If running manually:

cd C:\path\to\digna
digna serve --address localhost --port 8082

If using IIS or Tomcat: Restart your web server service.

Step 2: Open Dashboard¶

Open the digna dashboard in your browser:

http://localhost:5173

(or your configured dashboard URL)

Step 3: Verify Login Buttons¶

Check that login buttons appear for each configured provider:

• ✅ Should see "Login with Microsoft" button
• ✅ Should see "Login with Google" button
• ✅ (If usePassword = true) Should see username/password fields

If buttons don't appear: - Check that dashboard_config.toml was saved - Check that dashboard service was restarted - Check browser console (F12) for errors

Step 4: Test SSO Login¶

Click one of the SSO buttons (e.g., "Login with Microsoft"):

1. You should be redirected to the identity provider's login page
2. Log in with your enterprise credentials
3. You should be redirected back to digna
4. You should be logged in to digna

Step 5: Verify User Creation¶

After successful SSO login:

• ✅ User should be automatically created in digna
• ✅ User should be logged in
• ✅ User profile should display your identity provider credentials
• ✅ You should see the digna dashboard

Step 6: Test Password Login (If Enabled)¶

If usePassword = true:

1. Log out of digna
2. On the login page, enter a username and password
3. You should be able to log in with password credentials

Troubleshooting¶

Login Buttons Don't Appear¶

Symptoms: - OIDC login buttons not visible on login page - Only see password fields (if usePassword = true)

Causes & Solutions: 1. Check dashboard_config.toml is in dashboard/ directory 2. Verify [[login.oidc]] sections are present with correct syntax 3. Restart dashboard service 4. Clear browser cache (Ctrl+Shift+Delete or Cmd+Shift+Delete) 5. Check browser console (F12 → Console tab) for errors

Redirect URI Mismatch Error¶

Symptoms: - After clicking SSO button, error about "redirect_uri mismatch" - "The redirect URI is not registered" error

Causes & Solutions: 1. Verify DIGNA_OIDC_REDIRECT_URI in config.toml is correct 2. Verify redirect URI is registered in identity provider settings 3. Ensure both use identical URLs (including protocol, domain, path) 4. Check for typos in the redirect URI 5. If using HTTPS, ensure certificate is valid

Invalid Client Credentials Error¶

Symptoms: - "Invalid client ID or secret" error - Authentication fails with credentials error

Causes & Solutions: 1. Verify DIGNA_OIDC_CLIENT_ID and DIGNA_OIDC_CLIENT_SECRET are correct 2. Ensure no extra spaces or special characters 3. Check credentials haven't expired or been revoked 4. Restart backend service after updating config 5. Check identity provider console to confirm credentials are active

Login Hangs or Times Out¶

Symptoms: - Clicking SSO button does nothing - Timeout after several seconds - Browser shows "Failed to connect" or similar

Causes & Solutions: 1. Verify digna backend is running: digna repo check 2. Check network connectivity to identity provider 3. Verify DIGNA_OIDC_CONFIGURATION_URL is accessible 4. Check firewall rules allow outbound HTTPS connections 5. Verify backend and dashboard can reach each other

Users Not Automatically Created¶

Symptoms: - SSO login succeeds but user not created in digna - Get permission error after SSO login

Causes & Solutions: 1. Verify OIDC configuration is correct 2. Check user permissions are set up 3. Review digna logs for error messages 4. Restart backend service 5. Contact support@digna.ai if issue persists

Supported Providers¶

Tested & Supported¶

The following OIDC providers have been tested and are known to work:

Other OIDC Providers¶

Any provider that supports OpenID Connect can be integrated. Required information:

• Client ID
• Client secret
• OpenID configuration URL (usually at /.well-known/openid-configuration)
• Supported scopes (typically openid profile email)

Contact support@digna.ai if you need help integrating a specific provider.

Best Practices¶

✅ DO: - Use HTTPS in production (not HTTP) - Store client secrets securely (use environment variables if possible) - Rotate secrets periodically - Test in a non-production environment first - Document which providers are configured - Monitor login logs for unusual activity - Keep identity provider configuration in sync with digna config

❌ DON'T: - Store client secrets in version control - Use HTTP redirect URIs in production - Configure multiple providers with the same key - Leave default/test credentials in production - Expose config files containing secrets - Mix development and production credentials

Support¶

Need help with SSO configuration?

• 📧 Email: support@digna.ai
• 📚 Documentation: https://docs.digna.ai
• 🌐 Website: https://www.digna.ai

Last Updated: August 30, 2026
Release: 2026.04
© 2026 digna GmbH — www.digna.ai