raulcnadal/applivery-scim-bridge repository overview

⁠Overview

SCIM Bridge is a tool intended to work in tandem with Applivery UEM. It allows administrators to push LDAP(S) data such as groups, users and attributes to Applivery using SCIM Protocol.

⁠Quick Start Deployment

Use this docker-compose.yml to deployApplivery SCIM Bridgeon any Docker environment (ARM64 or AMD64).

version: '3.8'

services:
  applivery-scim-bridge:
    image: raulcnadal/applivery-scim-bridge:latest
    container_name: applivery-scim-bridge
    ports:
      - "8501:8501"
    volumes:
      # Automatically creates the persistent data folder relative to the compose file
      - ./applivery-scim-bridge/data:/app/data
    restart: unless-stopped
    environment:
      - PYTHONUNBUFFERED=1
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8501/_stcore/health"]
      interval: 30s
      timeout: 10s
      retries: 3

We recommend you adding a nice REverse Proxy with ACME Certbot DNS-01 plugin such as Nginx Proxy Manager, Nginz, Traefik, etc to handle TLS encryption.

Ex.

version: '3.8'

networks:
  applivery_net:
    name: applivery_net
    driver: bridge

services:
  applivery-scim-bridge:
    image: raulcnadal/applivery-scim-bridge:latest
    container_name: applivery-scim-bridge
    expose:
      - "8501" # Only accessible to other containers on applivery_net
    volumes:
      - ./applivery-scim-bridge/data:/app/data
    restart: unless-stopped
    environment:
      - PYTHONUNBUFFERED=1
    networks:
      - applivery_net
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8501/_stcore/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  nginx-proxy-manager:
    image: jc21/nginx-proxy-manager:latest
    container_name: nginx-proxy-manager
    restart: unless-stopped
    ports:
      # - "80:80" # 
      - "443:443" # Secure HTTPS port
      - "81:81"   # NPM Admin UI port
    environment:
      DB_SQLITE_FILE: "/data/database.sqlite"
    volumes:
      - ./npm/data:/data
      - ./npm/letsencrypt:/etc/letsencrypt
    networks:
      - applivery_net

⁠📘 Applivery SCIM Bridge: Administrator Guide

Welcome to the Applivery SCIM Bridge! This application acts as a secure, automated middleman between your on-premise or cloud LDAP directories (like Active Directory or OpenLDAP) and your Applivery environments.

It leverages the industry-standard SCIM (System for Cross-domain Identity Management) protocol to automatically provision, update, and de-provision user objects and group memberships directly into Applivery via a secure REST API.

⁠1. First-Time Setup & Authentication

Because the SCIM Bridge handles sensitive directory data and API tokens, it is protected by a localized security gateway.

• Initial Password Creation: The very first time you access the web interface, you will be greeted by the "First Time Setup" screen. Enter and confirm a secure Master Password. This password is irreversibly hashed (SHA-256) and saved to the local configuration.
• Subsequent Logins: Moving forward, you will use this Master Password to unlock the dashboard.
• Security Timeout: For your protection, the application features an automatic 15-minute inactivity timeout. If you leave the dashboard idle, you will be safely logged out and required to re-enter your password.

⁠2. Global Bridge Settings (Left Control Panel)

Once authenticated, use the Bridge Control Panel on the left side of the screen to configure your global settings. These settings apply to the entire engine.

⁠Applivery API Targets

Expand this section to define where the Bridge should send your SCIM payloads:

• SCIM URL: The base endpoint for the Applivery SCIM API (defaults to https://link.applivery.io/v1).
• Target Tokens: Paste your specific Bearer tokens for the MDM Portal, Admin Dashboard, and Enterprise Store. You only need to provide tokens for the environments you actually plan to use.
• Webhook URL (Optional): Provide a Slack, Microsoft Teams, or custom webhook URL to receive real-time alerts about sync successes, failures, and manual admin triggers.
• Click Save API Settings when finished.

⁠Sync Schedule

• Interval Slider: Choose how often the background engine should query your directories (e.g., every 60, 120, or 360 minutes).
• Engine Toggle: Click START AUTO SYNC to activate the background worker. The main dashboard will indicate if the engine is "Operational" or "Idle".

⁠Backup/Restore

• Export JSON: Instantly download a complete, encrypted backup of your entire configuration (including LDAP sources, mappings, and scheduled intervals).
• Restore JSON: Upload a previously saved configuration file to instantly restore your bridge settings. Perfect for disaster recovery or migrating to a new server.

⁠3. Configuring LDAP Sources

Navigate to the LDAP Sources tab to define the directories you want to sync users from. You can add as many independent sources as you need.

⁠Adding a Source

Click ➕ Add New LDAP Source. You will be prompted to choose a creation method:

• Start from scratch: Creates a blank template.
• Clone existing source: A massive time-saver if you are managing multiple sub-domains. This will instantly copy the URL, credentials, Base DN, search filters, and custom attribute mappings from an existing source so you only have to tweak the differences.

⁠Connection Details & Safety Locks

Expand your new source and toggle ⚙️ Edit Connection Details:

1. Directory Preset: Select "Active Directory", "Okta / OpenLDAP", or "Custom".
   • ⚠️ Safety Lock: Once you select a preset, it automatically populates the complex schema attributes below it and permanently locks the dropdown. This prevents admins from accidentally hot-swapping presets and destroying a working configuration. If you need a different preset, simply create a new source.
2. Connection Security: Select your protocol. LDAPS is highly recommended for production environments to ensure passwords and user data are encrypted in transit.
3. Credentials: Enter your LDAP URL, Admin DN (username), Password, and Base DN.
4. Test Connection: Always click this before saving to verify the bridge can reach your directory!

⁠Browsing & Selecting Groups

Instead of manually typing group distinguished names, use the Browse LDAP Groups to Sync search bar. Type a partial group name (e.g., "engineering"), and the bridge will query your LDAP server and provide a dropdown of matching groups. Click Add Group to lock it into the sync list.

⁠Attribute Mapping

The bridge automatically handles standard SCIM core attributes (First Name, Last Name, Email, Status). Use the Add Mapping section to link custom LDAP attributes (like department or title) to custom SCIM keys.

• ⚠️ Important Applivery Configuration: The SCIM protocol requires a matching destination for custom data. For these mappings to work, you must also log into your Applivery Admin Dashboard, navigate to your custom properties/attributes settings, and create matching fields using the exact same SCIM keys you defined here. If the keys do not exist in Applivery, the Bridge will successfully push the data, but Applivery will drop the unrecognized fields.

⁠4. Executing Synchronizations

The Applivery SCIM Bridge offers three distinct ways to sync your data, giving you total control.

⁠Method A: Automated Background Sync

Once started from the left pane, the global sponge engine runs silently in the background based on your chosen interval. It processes all configured sources and groups automatically. You can monitor its heartbeat via the Sync History log on the main Dashboard.

⁠Method B: Manual Bulk Sync (Dashboard Tab)

Need to force an update immediately without waiting for the next automated cycle?

1. Go to the Dashboard tab.
2. Check the boxes next to the specific LDAP sources you want to process.
3. Click Trigger Sync.
4. Review the warning prompt (bulk syncs generate significant network traffic) and confirm. A progress window will show you exactly which source and group is currently being processed.

⁠Method C: Surgical On-Demand Sync (On-Demand Tab)

Perfect for IT helpdesks when a single user needs immediate access.

1. Go to the On-Demand tab.
2. Select the target LDAP Source.
3. Search for the specific user by Name or Email.
4. Click Sync Now. The engine will immediately fetch that single user's latest data from LDAP and push it via SCIM directly to your configured Applivery targets.

⁠5. Auditing & Logs

Navigate to the Logs tab to view the raw, real-time output of the application.

• This view displays the last 100 system events, including LDAP connection attempts, SCIM API HTTP responses, and background engine heartbeats.
• Use this tab to troubleshoot if a user is failing to sync (e.g., missing required email attributes or encountering API token rejections).
• Click Clear to wipe the current log file and start fresh.

⁠Reset Master Password

Upon first boot, Applivery SCIM Bridge will request the admin to set a master password to protect access to the administrator dashboard.

If you ever need to reset the master password, follow these simple steps:

1. Locate the persistent data folder: Find the applivery-scim-bridge directory where your Docker engine stores persistent data.

   Example:

   sudo find / -type d -name "applivery-scim-bridge"
   
   # Output might look like:
   # /data/compose/182/applivery-scim-bridge
   

   Copy

2. Edit the configuration file: Navigate into the data folder inside that directory and open the config_db.json file in your preferred text editor.

3. Find the hashed password: Scroll to the very bottom of the JSON file. You will see a line containing the encrypted password hash that looks like this:

   "auth_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
   

   Copy

4. Clear the hash: Simply delete the long string of letters and numbers between the quotes so the value is completely empty. It should look exactly like this:

   "auth_hash": ""
   

   Copy

5. Save and Reload: Save the config_db.json file and refresh the Applivery SCIM Bridge web page. The system will detect the empty hash and immediately prompt you to create a new secure master password!

🇪🇺 Proudly crafted by Applivery in Europe.