Lucca

This guide explains how to set up single sign-on (SSO) between VaultysHub and Lucca using SAML 2.0 or OpenID Connect.

Prerequisites

• Lucca account with SSO module enabled
• Administrator access to Lucca
• Application configured in VaultysHub with SAML2 or OpenID Connect
• Verified email domain

Note: SSO requires the activation of the SSO module in your Lucca contract.

Configuration with OpenID Connect (Recommended)

Configuration in VaultysHub

1. Create the application

1. Log in to VaultysHub as an administrator
2. Go to Applications → Add
3. Create a new application:
   • Name: Lucca
   • URL: https://[your-instance].ilucca.net
   • Description: Complete HR suite (Figgo, Pagga, Timmi, etc.)
   • Icon: Choose the Lucca icon

2. Configure OpenID Connect

1. In the Authentication tab
2. Select OpenID Connect
3. Note the information:
   • Client ID: lucca-xxxxxx
   • Client Secret: secret-xxxxxx
   • App ID: [appid] (unique identifier generated automatically)

3. Redirect URLs

Add to Allowed Redirect URLs:

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

Configuration in Lucca

1. Access SSO settings

1. Log in to Lucca as an administrator
2. Go to Configuration → Settings → Authentication
3. Click on Single Sign-On (SSO)
4. Select OpenID Connect

2. Identity provider configuration

Configure the following settings:

• Discovery URL: https://[your-instance].link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration
• Client ID: lucca-xxxxxx (from VaultysHub)
• Client Secret: secret-xxxxxx (from VaultysHub)
• Scopes: openid profile email

3. Attribute mapping

Lucca Attribute	OpenID Claim	Required
Email	email	Yes
First Name	given_name	Yes
Last Name	family_name	Yes

VaultysHub does not transmit groups, employee ID, service, or manager: this information is managed directly in Lucca.

Configuration with SAML 2.0

Configuration in VaultysHub

1. Configure SAML2

1. In the Lucca application
2. Authentication tab → SAML2
3. Configure:
   • Entity ID: the Entity ID of the Service Provider provided by Lucca (and not the URL of VaultysHub)
   • ACS URL: https://[your-instance].ilucca.net/identity/saml2/acs
   • NameID Format: emailAddress

2. Retrieve metadata

Note the URLs:

• IdP Metadata: https://[your-instance].link.vaultys.org/api/saml2/metadata/[appid]
• SSO URL: https://[your-instance].link.vaultys.org/api/saml2/sso/[appid]
• Entity ID: https://[your-instance].link.vaultys.org/[appid]

Single Logout from VaultysHub is not supported.

Configuration in Lucca

1. In Configuration → Authentication → SAML 2.0
2. Import the metadata or configure manually:
   • IdP Entity ID: https://[your-instance].link.vaultys.org/[appid]
   • SSO URL: https://[your-instance].link.vaultys.org/api/saml2/sso/[appid]
   • X.509 Certificate: Import from VaultysHub

Configuration of Lucca modules

VaultysHub does not transmit user groups: roles and access to modules are assigned directly in Lucca.

Figgo (Leave Management)

{
  "figgo_settings": {
    "auto_provision": true,
    "sync_managers": true,
    "default_leave_policy": "standard"
  }
}

Pagga (Payroll Management)

{
  "pagga_settings": {
    "restricted_access": true
  }
}

Timmi (Time Management)

timmi_configuration:
  projects:
    default_access: "member"
  
  time_tracking:
    mandatory: true
    validation_workflow: "manager"

Poplee Core HR

{
  "poplee_settings": {
    "employee_sync": {
      "source": "sso",
      "update_on_login": true
    }
  }
}

Data Synchronization

Lucca API with SSO

const axios = require('axios');

class LuccaAPIClient {
  constructor(apiKey, domain) {
    this.apiKey = apiKey;
    this.baseUrl = `https://${domain}.ilucca.net/api/v3`;
  }
  
  async syncUserFromSSO(ssoUserData) {
    // Search for the user by email
    const user = await this.getUserByEmail(ssoUserData.email);
    
    if (!user) {
      // Create the user
      return await this.createUser({
        mail: ssoUserData.email,
        firstName: ssoUserData.given_name,
        lastName: ssoUserData.family_name,
        authenticationMode: 'sso'
      });
    } else {
      // Update the user
      return await this.updateUser(user.id, {
        firstName: ssoUserData.given_name,
        lastName: ssoUserData.family_name
      });
    }
  }
  
  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

// Endpoint to receive Lucca webhooks
app.post('/webhook/lucca', async (req, res) => {
  const { event, data } = req.body;
  
  switch(event) {
    case 'user.created':
      // Sync with VaultysHub if necessary
      await syncNewUserToVaultysHub(data);
      break;
      
    case 'leave.approved':
      // Notify via VaultysHub
      await sendNotification(data.userId, 'Your leave request has been approved');
      break;
      
    case 'timesheet.submitted':
      // Trigger validation workflow
      await triggerValidationWorkflow(data);
      break;
  }
  
  res.status(200).json({ success: true });
});

Configuration Testing

1. Connection Test

1. Log out of Lucca
2. Go to https://[your-instance].ilucca.net
3. Click on Log in with SSO
4. Enter your professional email
5. Authenticate via VaultysHub
6. Check access to various Lucca modules

2. Permission Test

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

3. Mobile Test

Lucca Mobile applications support SSO:

• Figgo Mobile (iOS/Android)
• Timmi Mobile
• Lucca Mobile (unified app)

Troubleshooting

Error "SSO Authentication Failed"

Problem: SSO authentication is not working

Solution:

1. Ensure the Entity ID is https://[your-instance].link.vaultys.org/[appid] for SAML
2. For OIDC, check the Discovery URL
3. Make sure the email exists in Lucca
4. Check the logs: Configuration → Authentication Logs

Groups are not synchronized

Problem: Lucca roles do not match VaultysHub groups

Solution: this is the expected behavior. VaultysHub does not transmit groups: assign roles directly in Lucca.

Error "User not authorized for this module"

Problem: The SSO user does not have access to certain modules

Solution:

1. Check the licenses assigned in Lucca
2. Verify the user's role permissions
3. Ensure the module is enabled for the user

Manager synchronization issue

Problem: The hierarchy is not correctly synchronized

Solution: VaultysHub does not transmit the user's manager. Manage the hierarchy directly in Lucca.

Security

Recommended Configuration

{
  "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
    }
  }
}

GDPR Compliance

Lucca is GDPR compliant with:

• Data hosting in France
• Right to be forgotten
• Data portability
• Encryption of sensitive data
• Complete audit trail

Migration of Existing Users

Migration Script

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 to SSO"""
        results = []
        
        with open(user_list_file, 'r', encoding='utf-8') as file:
            reader = csv.DictReader(file)
            
            for user in reader:
                try:
                    # Enable SSO for the user
                    self.enable_sso_for_user(user['email'])
                    
                    # Disable password authentication
                    self.disable_password_auth(user['id'])
                    
                    # Send notification email
                    self.send_migration_email(user['email'])
                    
                    results.append({
                        'email': user['email'],
                        'status': 'success',
                        'timestamp': datetime.now()
                    })
                    
                except Exception as e:
                    results.append({
                        'email': user['email'],
                        'status': 'failed',
                        'error': str(e)
                    })
        
        return results
    
    def enable_sso_for_user(self, email):
        # Implement SSO activation via Lucca API
        pass

Resources

• Lucca SSO Documentation
• Lucca API Documentation
• Lucca Support
• SAML/OIDC Configuration VaultysHub
• Lucca Community