Skip to content

LDAP Sync Plugin

Audience: System Administrators

Content Summary: This page details how to enable Immuta's LDAP Sync plugin. This plugin takes an existing and configured LDAP IAM and seeds Immuta with all of its users, subject to the intersection of the IAM's user search filter and the plugin's (optional) user search filter. Users with the Immuta USER_ADMIN permission on the Immuta instance can manually interact with the plugin via a custom API endpoint. The plugin can also be configured to run periodically to maintain synchronization with the remote LDAP IAM.

Overview

The LDAP Sync Plugin is an extension to the Immuta LDAP IAM to allow LDAP users to be synchronized with Immuta without having to log in to the Immuta Web UI. The plugin expands the LDAP IAM by adding the following features:

  • New User Sync - New users returned by the configured LDAP IAM's User Search Filter will be synchronized into Immuta as if they logged into the Web UI. The User profile, User Group membership, and SQL Accounts will all be created based on the LDAP IAM configuration.
  • Existing User Sync - Existing users returned by the configured LDAP IAM's User Search Filter will have their User Group memberships re-synchronized as if they logged into the Web UI.
  • Disabled User Sync - Users who exist in Immuta and are associated with the configured LDAP IAM, but no longer are returned by the LDAP IAM's User Search Filter, will be disabled. All access to Immuta will be revoked for the user.
  • Scheduled Periodic Sync - Runs the synchronization process based on a configurable schedule.

Installation

Acquire the plugin

Download the LDAP Plugin from Immuta's Archives site.

Immuta Archives site access required

A user with access to Immuta's Archives site is required to conduct this download. Credentials to access the site can be obtained by visiting the Immuta Download Site and logging in with your Immuta Accounts credentials if prompted. At the very bottom of the page is an All Archives section with a here link that will take you directly to the archives site with your account credentials already applied.

Upload the plugin to Immuta

  1. As a user with Immuta's APPLICATION_ADMIN permission, access the Advanced Settings section of Immuta's App Settings page.

    Access App Settings / Advance Settings

  2. Click Upload Server Plugin, and a modal will pop up. Use the modal to upload the custom ZIP file.

    Upload custom plugin step 1

  3. Once the upload has completed successfully, verify that your plugin is listed and Save. Note: Saving here will restart your Immuta services.

    Upload custom plugin step 2

Configuration

The LDAP sync plugin is configured through custom YAML added in the Advanced Configuration section of the App Settings page.

LDAP plugin configuration

The table below details available settings and their meanings.

Key Description Default Value Example Value
iamId The case-sensitive IAM ID the plugin will run (must be an LDAP IAM). Plugin will detect first LDAP IAM by default. null DemoAD
scheduler.enabled Boolean value on whether the job should be scheduled to run periodically. false true or false
scheduler.cronRule A cron rule to apply on the scheduler. 0 0 * * * *(See the cron man pages for details.)
endpointPath The plugin's endpoint path following the Immuta base URL. /iam/{iamid}/sync /iam/{iamid}/myendpoint

Plugin Usage

Once you've uploaded and configured the plugin, test the endpoint manually to ensure that the plugin has been deployed successfully and is working as expected.

By default, the plugin only takes effect when the sync endpoint is manually called. It will not run a periodic sync job until explicitly configured to do so. Run a "dry run" to verify that your LDAP configuration is correct before configuring a periodic run.

Immuta API Authentication Required

The LDAP Sync plugin's endpoint leverages Immuta's standard bearer token authentication like most other components of the Immuta API. Additionally, only users with Immuta's USER_ADMIN permission will be able to interact with this custom endpoint. For instructions on getting authenticated, please see the API Authentication section of this site.

"Dry Run" Testing

The plugin supports a "dry run" mode, where LDAP queries will be executed per your configuration, but no actual user accounts will be created or modified.

Always do a dry run first

Use this option to verify that your general IAM settings and LDAP plugin settings are working as intended before executing live requests.

A dry run can be conducted against any query if dryRun is added to the request's body with the value of true, as shown below.

curl --request POST \
  "https://example.immuta.com/iam/ldap/sync" \
  --header "Authorization: Bearer exampletoken1234" \
  --header "Content-Type: application/json" \
  --data '{"userId":"*","dryRun":true}'

To run a "live" report, simply remove the "dryRun":true like this:

curl --request POST \
  "https://example.immuta.com/iam/ldap/sync" \
  --header "Authorization: Bearer exampletoken1234" \
  --header "Content-Type: application/json" \
  --data '{"userId":"*"}'

Run a Single User Import

To import a single user, issue a POST command similar to the following, with the userID field set to a valid username. For example, to retrieve the record of a user with a user ID of 'usera' in the remote LDAP server, simply set the userId in the payload to be {"userId": "usera"}. The full sample command would be

curl --request POST \
  "<IMMUTA URL>/iam/<IMMUTA IAM ID>/sync" \
  --header "Authorization: Bearer <AUTHENTICATION TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{"userId":"usera","dryRun":false}'

The expected response would be something similar to

{
  "importedUsers": [
    {
      "dn": "uid=Plug Test,ou=Users,dc=immuta,dc=com",
      "userId": "usera",
    }
  ]
}

Run a Full Import

To run the full import job manually, simply pass a wildcard (*) for the userId parameter instead of a specific userId:

curl --request POST \
  "<IMMUTA URL>/iam/<IMMUTA IAM ID>/sync" \
  --header "Authorization: Bearer <AUTHENTICATION TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{"userId":"*","dryRun":false}'

If two users were imported in the job, the expected response would look like this:

{
  "importedUsers": [
    {
      "dn": "uid=Plug Test,ou=Users,dc=immuta,dc=com",
      "userId": "usera",
    }, {
      "dn": "cn=Immuta Test,ou=Users,dc=immuta,dc=com",
      "userId": "userb",
    }
  ]
}

Scheduling a Periodic Synchronization Job

Once you have confirmed that your plugin is working as intended manually, you may want to enable a periodic sync to take place via a scheduled cron job. Alter the cronRule to your desired schedule as previously shown in Configuration.