Lucca

Dieser Leitfaden erklärt, wie man die Einmalanmeldung (SSO) zwischen SmartLink und Lucca mithilfe von SAML 2.0 oder OpenID Connect konfiguriert.

Voraussetzungen

Lucca-Konto mit aktiviertem SSO-Modul
Administratorzugriff auf Lucca
Anwendung in SmartLink mit SAML2 oder OpenID Connect konfiguriert
Überprüfte E-Mail-Domain

Hinweis: Die SSO erfordert die Aktivierung des SSO-Moduls in Ihrem Lucca-Vertrag.

Konfiguration mit OpenID Connect (Empfohlen)

Konfiguration in SmartLink

1. Anwendung erstellen

Melden Sie sich als Administrator bei SmartLink an
Gehen Sie zu Anwendungen → Hinzufügen
Erstellen Sie eine neue Anwendung:
- Name: Lucca
- URL: https://[your-instance].ilucca.net
- Beschreibung: Vollständiges HRIS-Paket (Figgo, Pagga, Timmi usw.)
- Symbol: Wählen Sie das Lucca-Symbol aus

2. OpenID Connect konfigurieren

Im Tab Authentifizierung
Wählen Sie OpenID Connect
Notieren Sie die Informationen:
- Client-ID: lucca-xxxxxx
- Client-Geheimnis: secret-xxxxxx
- App-ID: [appid] (automatisch generierte eindeutige Kennung)

3. Erlaubte Umleitungs-URLs

Fügen Sie in Erlaubte Umleitungs-URLs hinzu:

https://[your-instance].ilucca.net/identity/oidc/callback
https://[your-instance].ilucca.net/auth/oidc/callback

Konfiguration in Lucca

1. Zugriff auf SSO-Einstellungen

Melden Sie sich als Administrator bei Lucca an
Gehen Sie zu Konfiguration → Einstellungen → Authentifizierung
Klicken Sie auf Single Sign-On (SSO)
Wählen Sie OpenID Connect

2. Konfiguration des Identitätsanbieters

Konfigurieren Sie die folgenden Einstellungen:

Discovery-URL: https://[your-smartlink].link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration
Client-ID: lucca-xxxxxx (aus SmartLink)
Client-Geheimnis: secret-xxxxxx (aus SmartLink)
Bereiche: openid Profil E-Mail Gruppen

3. Attributzuordnung

Lucca-Attribut	OpenID-Claim	Obligatorisch
E-Mail	`E-Mail`	✅
Vorname	`given_name`	✅
Nachname	`family_name`	✅
Personalnummer	`employee_number`	❌
Abteilung	`department`	❌
Manager	`manager_email`	❌

Konfiguration mit SAML 2.0

Konfiguration in SmartLink

1. SAML2 konfigurieren

In der Anwendung Lucca
Tab Authentifizierung → SAML2
Konfigurieren Sie:
- Entitäts-ID: https://[your-smartlink].link.vaultys.org/[appid]
- ACS-URL: https://[your-instance].ilucca.net/identity/saml2/acs
- Format NameID: emailAddress

2. Metadaten abrufen

Notieren Sie die URLs:

IdP-Metadaten: https://[your-smartlink].link.vaultys.org/api/saml2/[appid]/metadata
SSO-URL: https://[your-smartlink].link.vaultys.org/api/saml2/sso/[appid]
SLO-URL: https://[your-smartlink].link.vaultys.org/api/saml2/slo/[appid]
Entitäts-ID: https://[your-smartlink].link.vaultys.org/[appid]

Konfiguration in Lucca

In Konfiguration → Authentifizierung → SAML 2.0
Importieren Sie die Metadaten oder konfigurieren Sie manuell:
- IdP-Entitäts-ID: [appid]
- SSO-URL: https://[your-smartlink].link.vaultys.org/api/saml2/sso/[appid]
- X.509-Zertifikat: Importieren Sie es aus SmartLink

Konfiguration der Lucca-Module

Figgo (Urlaubsverwaltung)

{
  "figgo_settings": {
    "auto_provision": true,
    "sync_managers": true,
    "default_leave_policy": "standard",
    "sso_groups_mapping": {
      "smartlink-managers": "validateur_n1",
      "smartlink-hr": "administrateur_rh",
      "smartlink-employees": "collaborateur"
    }
  }
}

Pagga (Lohnabrechnung)

{
  "pagga_settings": {
    "restricted_access": true,
    "allowed_groups": ["smartlink-hr", "smartlink-payroll"],
    "permissions": {
      "smartlink-payroll": ["edit_bulletins", "export_dsn"],
      "smartlink-hr": ["view_bulletins", "manage_employees"],
      "smartlink-managers": ["view_team_bulletins"]
    }
  }
}

Timmi (Zeiterfassung)

timmi_configuration:
  projects:
    sync_with_sso_groups: true
    default_access: "member"
  
  time_tracking:
    mandatory: true
    validation_workflow: "manager"
  
  permissions:
    smartlink-project-managers:
      - create_projects
      - manage_budgets
      - view_all_timesheets
    smartlink-employees:
      - submit_timesheet
      - view_own_timesheet

Poplee Core HR

{
  "poplee_settings": {
    "employee_sync": {
      "source": "sso",
      "update_on_login": true,
      "fields_mapping": {
        "department": "{{department}}",
        "job_title": "{{title}}",
        "manager": "{{manager_email}}",
        "location": "{{office_location}}"
      }
    }
  }
}

Daten-Synchronisierung

Lucca-API mit SSO

const axios = require('axios');

class LuccaAPIClient {
  constructor(apiKey, domain) {
    this.apiKey = apiKey;
    this.baseUrl = `https://${domain}.ilucca.net/api/v3`;
  }
  
  async syncUserFromSSO(ssoUserData) {
    // Benutzer anhand der E-Mail suchen
    const user = await this.getUserByEmail(ssoUserData.email);
    
    if (!user) {
      // Benutzer erstellen
      return await this.createUser({
        mail: ssoUserData.email,
        firstName: ssoUserData.given_name,
        lastName: ssoUserData.family_name,
        department: ssoUserData.department,
        authenticationMode: 'sso'
      });
    } else {
      // Benutzer aktualisieren
      return await this.updateUser(user.id, {
        department: ssoUserData.department,
        jobTitle: ssoUserData.title
      });
    }
  }
  
  async getUserByEmail(email) {
    const response = await axios.get(`${this.baseUrl}/users`, {
      headers: { 'Authorization': `lucca application=${this.apiKey}` },
      params: { mail: email }
    });
    return response.data.items[0];
  }
}

Lucca-Webhooks

// Endpunkt zum Empfangen von Lucca-Webhooks
app.post('/webhook/lucca', async (req, res) => {
  const { event, data } = req.body;
  
  switch(event) {
    case 'user.created':
      // Bei Bedarf mit SmartLink synchronisieren
      await syncNewUserToSmartLink(data);
      break;
      
    case 'leave.approved':
      // Über SmartLink benachrichtigen
      await sendNotification(data.userId, 'Ihr Urlaubsantrag wurde genehmigt');
      break;
      
    case 'timesheet.submitted':
      // Validierungsworkflow auslösen
      await triggerValidationWorkflow(data);
      break;
  }
  
  res.status(200).json({ success: true });
});

Konfigurationstest

1. Verbindungstest

Melden Sie sich von Lucca ab
Gehen Sie zu https://[your-instance].ilucca.net
Klicken Sie auf Mit SSO anmelden
Geben Sie Ihre geschäftliche E-Mail-Adresse ein
Authentifizieren Sie sich über SmartLink
Überprüfen Sie den Zugriff auf die verschiedenen Lucca-Module

2. Berechtigungstest

# API-Test mit SSO-Authentifizierung
curl -X GET "https://[your-instance].ilucca.net/api/v3/users/me" \
  -H "Authorization: lucca application=YOUR_API_KEY"

3. Mobile Test

Die Lucca Mobile-Apps unterstützen SSO:

Figgo Mobile (iOS/Android)
Timmi Mobile
Lucca Mobile (vereinheitlichte App)

Fehlerbehebung

Fehler "SSO-Authentifizierung fehlgeschlagen"

Problem: Die SSO-Authentifizierung funktioniert nicht

Lösung:

Überprüfen Sie, ob die Entitäts-ID [appid] für SAML ist
Für OIDC überprüfen Sie die Discovery-URL
Stellen Sie sicher, dass die E-Mail in Lucca vorhanden ist
Überprüfen Sie die Protokolle: Konfiguration → Authentifizierungsprotokolle

Gruppen werden nicht synchronisiert

Problem: Die Lucca-Rollen entsprechen nicht den SmartLink-Gruppen

Lösung:

// Richtige Konfiguration der Claims für Gruppen
{
  "groups_claim": "groups",
  "groups_mapping": {
    "smartlink-rh": "ADMIN_RH",
    "smartlink-managers": "MANAGER",
    "smartlink-employees": "COLLABORATEUR"
  }
}

Fehler "Benutzer nicht für dieses Modul autorisiert"

Problem: Der SSO-Benutzer hat keinen Zugriff auf bestimmte Module

Lösung:

Überprüfen Sie die zugewiesenen Lizenzen in Lucca
Überprüfen Sie die Berechtigungen der Benutzerrolle
Stellen Sie sicher, dass das Modul für den Benutzer aktiviert ist

Problem mit der Synchronisierung von Managern

Problem: Die Hierarchie wird nicht korrekt synchronisiert

Lösung:

<!-- SAML-Attribut für den Manager -->
<saml:Attribute Name="manager_email">
  <saml:AttributeValue>manager@unternehmen.de</saml:AttributeValue>
</saml:Attribute>

Sicherheit

Empfohlene Konfiguration

{
  "security_settings": {
    "enforce_sso": true,
    "session_timeout": "8h",
    "ip_filtering": {
      "enabled": true,
      "allowed_ips": ["10.0.0.0/8", "192.168.0.0/16"]
    },
    "api_security": {
      "token_rotation": "30d",
      "rate_limiting": true,
      "audit_api_calls": true
    },
    "data_protection": {
      "encryption_at_rest": true,
      "anonymize_exports": true,
      "gdpr_compliant": true
    }
  }
}

Lucca ist GDPR-konform mit:

Datenhosting in Frankreich
Recht auf Vergessenwerden
Datenportabilität
Verschlüsselung sensibler Daten
Vollständiges Audit-Trail

Migration bestehender Benutzer

Migrations-Skript

import csv
import requests
from datetime import datetime

class LuccaSSOMigration:
    def __init__(self, api_key, instance):
        self.api_key = api_key
        self.instance = instance
        self.api_url = f"https://{instance}.ilucca.net/api/v3"
    
    def migrate_users_to_sso(self, user_list_file):
        """Batch-Migration zu SSO"""
        results = []
        
        with open(user_list_file, 'r', encoding='utf-8') as file:
            reader = csv.DictReader(file)
            
            for user in reader:
                try:
                    # SSO für den Benutzer aktivieren
                    self.enable_sso_for_user(user['email'])
                    
                    # Passwortauthentifizierung deaktivieren
                    self.disable_password_auth(user['id'])
                    
                    # Benachrichtigungs-E-Mail senden
                    self.send_migration_email(user['email'])
                    
                    results.append({
                        'email': user['email'],
                        'status': 'Erfolg',
                        'timestamp': datetime.now()
                    })
                    
                except Exception as e:
                    results.append({
                        'email': user['email'],
                        'status': 'Fehlgeschlagen',
                        'error': str(e)
                    })
        
        return results
    
    def enable_sso_for_user(self, email):
        # Implementieren Sie die SSO-Aktivierung über die Lucca-API
        pass

Voraussetzungen​

Konfiguration mit OpenID Connect (Empfohlen)​

Konfiguration in SmartLink​

1. Anwendung erstellen​

2. OpenID Connect konfigurieren​

3. Erlaubte Umleitungs-URLs​

Konfiguration in Lucca​

1. Zugriff auf SSO-Einstellungen​

2. Konfiguration des Identitätsanbieters​

3. Attributzuordnung​

Konfiguration mit SAML 2.0​

Konfiguration in SmartLink​

1. SAML2 konfigurieren​

2. Metadaten abrufen​

Konfiguration in Lucca​

Konfiguration der Lucca-Module​

Figgo (Urlaubsverwaltung)​

Pagga (Lohnabrechnung)​

Timmi (Zeiterfassung)​

Poplee Core HR​

Daten-Synchronisierung​

Lucca-API mit SSO​

Lucca-Webhooks​

Konfigurationstest​

1. Verbindungstest​

2. Berechtigungstest​

3. Mobile Test​

Fehlerbehebung​

Fehler "SSO-Authentifizierung fehlgeschlagen"​

Gruppen werden nicht synchronisiert​

Fehler "Benutzer nicht für dieses Modul autorisiert"​

Problem mit der Synchronisierung von Managern​

Sicherheit​

Empfohlene Konfiguration​

GDPR-Konformität​

Migration bestehender Benutzer​

Migrations-Skript​

Ressourcen​

Voraussetzungen

Konfiguration mit OpenID Connect (Empfohlen)

Konfiguration in SmartLink

1. Anwendung erstellen

2. OpenID Connect konfigurieren

3. Erlaubte Umleitungs-URLs

Konfiguration in Lucca

1. Zugriff auf SSO-Einstellungen

2. Konfiguration des Identitätsanbieters

3. Attributzuordnung

Konfiguration mit SAML 2.0

Konfiguration in SmartLink

1. SAML2 konfigurieren

2. Metadaten abrufen

Konfiguration in Lucca

Konfiguration der Lucca-Module

Figgo (Urlaubsverwaltung)

Pagga (Lohnabrechnung)

Timmi (Zeiterfassung)

Poplee Core HR

Daten-Synchronisierung

Lucca-API mit SSO

Lucca-Webhooks

Konfigurationstest

1. Verbindungstest

2. Berechtigungstest

3. Mobile Test

Fehlerbehebung

Fehler "SSO-Authentifizierung fehlgeschlagen"

Gruppen werden nicht synchronisiert

Fehler "Benutzer nicht für dieses Modul autorisiert"

Problem mit der Synchronisierung von Managern

Sicherheit

Empfohlene Konfiguration

GDPR-Konformität

Migration bestehender Benutzer

Migrations-Skript

Ressourcen