OpenID Connect (OIDC) Integration

Overview

This document describes how to configure and use OpenID Connect (OIDC) for Single Sign-On (SSO) authentication in Lager Guru.

Prerequisites

• An OIDC-compliant identity provider (e.g., Azure AD, Okta, Auth0, Keycloak)
• Tenant admin access to configure SSO settings
• OIDC provider credentials (Client ID, Client Secret, Issuer URL)

Configuration

Step 1: Obtain OIDC Provider Information

From your OIDC provider, collect the following information:

• Issuer URL: The base URL of your OIDC provider (e.g., https://login.microsoftonline.com/{tenant-id}/v2.0)
• Client ID: Your application's client identifier
• Client Secret: Your application's client secret (keep this secure)
• Metadata URL (optional): The OpenID Connect discovery endpoint (e.g., https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration)
• Scopes: Required OIDC scopes (default: openid profile email)

Step 2: Configure in Lager Guru

1. Navigate to System Settings → SSO Integration
2. Click Provider hinzufügen (Add Provider)
3. Select OpenID Connect (OIDC) as the type
4. Enter the following information:
   • Issuer / Entity ID: Your OIDC issuer URL
   • Client ID: Your OIDC client ID
   • Client Secret: Your OIDC client secret
   • Metadata URL: Your OIDC discovery endpoint (optional, but recommended)
   • Scopes: OIDC scopes (default: openid profile email)
5. Toggle Active to enable the provider
6. Click Speichern (Save)

Step 3: Configure Redirect URI in OIDC Provider

In your OIDC provider's configuration, add the following redirect URI:

https://your-domain.com/auth/callback/oidc?provider_id={provider_id}&tenant_id={tenant_id}

Replace:

• your-domain.com with your Lager Guru domain
• {provider_id} with the ID of the SSO provider (shown after creation)
• {tenant_id} with your tenant ID

Authentication Flow

1. User clicks "Mit Unternehmens-SSO anmelden" on the login page
2. User is redirected to the OIDC provider's authorization endpoint
3. User authenticates with the OIDC provider
4. OIDC provider redirects back to Lager Guru with an authorization code
5. Lager Guru exchanges the authorization code for tokens
6. User information is extracted from the ID token
7. User is automatically provisioned into the tenant (if new)
8. User is signed in and redirected to their dashboard

User Provisioning

When a user logs in via SSO for the first time:

• A user account is automatically created in Lager Guru
• The user is assigned to the tenant that initiated the SSO flow
• Default role: tenant_user (can be changed by tenant admin)

Security Considerations

• State Parameter: OIDC flow uses state parameter to prevent CSRF attacks
• PKCE: Authorization Code flow with PKCE is used for enhanced security
• Token Validation: All tokens are validated against the OIDC provider
• Tenant Isolation: Users can only be provisioned into the tenant that initiated the SSO flow

Troubleshooting

Common Issues

1. "Invalid redirect URI"

   • Ensure the redirect URI in your OIDC provider matches exactly with the callback URL
   • Check that provider_id and tenant_id parameters are included

2. "User email not found"

   • Ensure your OIDC provider returns the email claim in the ID token
   • Verify that the email scope is included in the scopes configuration

3. "SSO provider not found or inactive"

   • Check that the SSO provider is marked as active in System Settings
   • Verify that the provider belongs to the correct tenant

Support

For additional support, contact your system administrator or refer to the Troubleshooting Guide.