SAML 2.0 Integration

Overview

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

Prerequisites

• A SAML 2.0-compliant identity provider (e.g., Active Directory Federation Services, Okta, OneLogin, Ping Identity)
• Tenant admin access to configure SSO settings
• SAML provider metadata URL or XML file

Configuration

Step 1: Obtain SAML Provider Information

From your SAML provider, collect the following information:

• Entity ID / Issuer: The unique identifier for your SAML identity provider
• Metadata URL: The URL where your SAML provider's metadata is published
• ACS Endpoint (optional): The Assertion Consumer Service endpoint URL (defaults to Lager Guru's callback URL)

Step 2: Configure in Lager Guru

1. Navigate to System Settings → SSO Integration
2. Click Provider hinzufügen (Add Provider)
3. Select SAML 2.0 as the type
4. Enter the following information:
   • Issuer / Entity ID: Your SAML identity provider's entity ID
   • Client ID / Service Provider Entity ID: Your Lager Guru service provider entity ID (unique identifier)
   • Metadata URL: Your SAML provider's metadata URL
   • ACS Endpoint (optional): Custom Assertion Consumer Service endpoint (defaults to automatic)
5. Toggle Active to enable the provider
6. Click Speichern (Save)

Step 3: Configure SAML Provider

In your SAML identity provider, configure the following:

Service Provider (Lager Guru) Settings:

• Entity ID: The Client ID / Service Provider Entity ID from step 2
• ACS URL: https://your-domain.com/auth/callback/saml?provider_id={provider_id}&tenant_id={tenant_id}
• Single Logout URL (optional): https://your-domain.com/auth/logout/saml
• Name ID Format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress (recommended)

Required SAML Attributes:

Your SAML provider should return the following attributes in the SAML assertion:

• email or mail: User's email address (required)
• name or displayName: User's full name (optional)
• givenName or firstName: User's first name (optional)
• surname or lastName: User's last name (optional)

Authentication Flow

1. User clicks "Mit Unternehmens-SSO anmelden" on the login page
2. Lager Guru generates a SAML authentication request (AuthnRequest)
3. User is redirected to the SAML identity provider
4. User authenticates with the SAML provider
5. SAML provider sends a SAML response (assertion) back to Lager Guru
6. Lager Guru validates the SAML response and extracts user information
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

• Request ID Validation: SAML requests include unique request IDs to prevent replay attacks
• Signature Validation: SAML responses are validated against the identity provider's certificate
• Assertion Encryption: Supported if configured in your SAML provider
• Tenant Isolation: Users can only be provisioned into the tenant that initiated the SSO flow

SAML Attribute Mapping

Lager Guru maps common SAML attributes to user information:

SAML Attribute	Lager Guru Field	Priority
email or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	Email	1
mail	Email	2
name or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name	Full Name	1
displayName or cn	Full Name	2
givenName or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	First Name	1
firstName	First Name	2
surname or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	Last Name	1
lastName	Last Name	2

Troubleshooting

Common Issues

1. "SAML response validation failed"

   • Verify that your SAML provider's certificate is valid
   • Check that the metadata URL is accessible and up-to-date
   • Ensure the entity ID matches exactly

2. "User email not found in SAML response"

   • Verify that your SAML provider returns the email attribute
   • Check the attribute name mapping (see SAML Attribute Mapping above)
   • Ensure the Name ID format includes the email address

3. "SAML request ID mismatch"

   • This may occur if the session expired or was cleared
   • User should retry the SSO login

4. "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.