Synchronize users and groups with LDAP#

Starburst control plane can synchronize users and groups from an LDAP directory. Synchronization is one of two ways to provision users and groups in control plane. The other is SCIM. See Provision users and groups with SCIM. You can use one provisioning type at a time. With LDAP synchronization, synchronization is the only source of group memberships in control plane, and it works with any authentication method.

LDAP synchronization is different from LDAP authentication. LDAP authentication checks the user name and the password when a user logs in. It does not create accounts, and it does not synchronize groups. See LDAP authentication.

LDAP synchronization needs control plane in managed mode, with control-plane.enabled set to true. Control plane does not start if you set starburst.users.provisioning.type without managed mode.

Control plane uses the same synchronization as SEP, described in LDAP user and group provisioning in SEP, with the following differences:

To enable LDAP user and group synchronization, set the following property in your config.properties file:

starburst.users.provisioning.type=LDAP

Configure the connection to the LDAP server with the ldap-user-provisioning. prefix. The connection is independent of LDAP authentication and can use a different service account:

ldap-user-provisioning.ldap.url=ldaps://ldap-server:636
ldap-user-provisioning.ldap.ssl.truststore.path=/path/to/ldap-truststore.pem
ldap-user-provisioning.ldap.bind-user=cn=service-account,dc=example,dc=com
ldap-user-provisioning.ldap.bind-password=<BIND_PASSWORD>

The connection also accepts ldap-user-provisioning.ldap.allow-insecure, ldap-user-provisioning.ldap.ssl.truststore.password, ldap-user-provisioning.ldap.ssl.keystore.path, and ldap-user-provisioning.ldap.ssl.keystore.password.

Then configure which users and groups to synchronize:

ldap-user-provisioning.user-search-base=ou=people,dc=example,dc=com
ldap-user-provisioning.user-search-filter=(objectClass=inetOrgPerson)
ldap-user-provisioning.user-name-attribute=uid
ldap-user-provisioning.group-search-base=ou=groups,dc=example,dc=com
ldap-user-provisioning.group-search-filter=(objectClass=groupOfNames)
ldap-user-provisioning.group-name-attribute=cn
ldap-user-provisioning.group-membership-attribute=member

Control plane runs the first synchronization at startup, and then at the interval set in ldap-user-provisioning.sync-interval. When you run multiple instances of control plane, only one instance synchronizes at a time.

Synchronization deletes users and groups that no longer exist in the LDAP directory. To protect against an incomplete LDAP response, a synchronization fails without changes if it would delete more than ldap-user-provisioning.deletion-threshold-percent of the users or of the groups. This check applies only when control plane has at least 10 users or groups.

How synchronization affects login#

With LDAP synchronization, control plane creates accounts only through synchronization. It does not create an account when a user logs in. A user who authenticates but has no active account receives HTTP status 403, and control plane refuses the request. Control plane runs this check on every request, including requests that use an existing session. A user whom synchronization deleted stays deleted, and logging in does not create the user again. A user who is inactive stays refused.

Without a provisioning type, control plane creates an account for a new user when the user logs in. This is just-in-time (JIT) provisioning. JIT is the default when Starburst access control is on and you set no provisioning type.

Accounts that already exist keep their IDs and grants, and their users can still log in. When synchronization finds an existing account with the same user name, it takes the account over. The account keeps its ID, its creation time, its active state, its direct grants, and its valid default roles. Group reconciliation can change the permissions that the user inherits. Existing accounts that synchronization does not manage keep their access. Review them if you want the directory to be the only authority.

Before you turn on synchronization#

Before you set starburst.users.provisioning.type to LDAP, do the following:

  1. Check that the user name from LDAP, after identifier mapping, matches the user name that authentication produces, after user mapping. Otherwise, control plane refuses the user.

  2. Run a successful synchronization, and check that it created the accounts of all users who need access. The synchronization at startup runs in the background, and a failed or dry-run synchronization creates no accounts.

  3. On a new installation, provision the first administrator before their first request. Synchronize the user or the group that you set in starburst.access-control.authorized-users or starburst.access-control.authorized-groups. These properties do not skip the check for an existing account.

To go back to JIT provisioning, remove starburst.users.provisioning.type. Control plane then creates missing users when they log in, with new IDs. Stored inactive users stay inactive.

Use the synchronized groups on a managed cluster#

Control plane stores the users and groups that it synchronizes. A managed cluster reads the groups from control plane when its coordinator uses the portal group provider. The cluster does not select this provider by itself. Setting deployment.mode=MANAGED makes the provider available, but it does not select it.

To use the synchronized groups on a managed cluster:

  1. On the coordinator of the cluster, create the file etc/group-provider.properties with the following content:

    group-provider.name=portal
    
  2. Restart or redeploy the coordinator.

Control plane does not need this file. The step applies to groups from SCIM as well. For the other steps to connect a cluster, see Connect a cluster to control plane.

LDAP user and group synchronization properties#

Property

Description

Default

ldap-user-provisioning.user-search-base

The base DN for user searches.

None (required)

ldap-user-provisioning.user-search-filter

The LDAP search filter for user entries. For example, (objectClass=user) for Active Directory or (objectClass=inetOrgPerson) for OpenLDAP.

None (required)

ldap-user-provisioning.user-name-attribute

The LDAP attribute that contains the username. For example, sAMAccountName for Active Directory or uid for OpenLDAP.

None (required)

ldap-user-provisioning.user-unique-attribute

The LDAP attribute that contains a unique identifier for each user. For example, objectGUID for Active Directory or entryUUID for OpenLDAP. When not set, a user that moves to another DN is synchronized as a new user.

None

ldap-user-provisioning.group-search-base

The base DN for group searches.

None (required)

ldap-user-provisioning.group-search-filter

The LDAP search filter for group entries. For example, (objectClass=group) for Active Directory or (objectClass=groupOfNames) for OpenLDAP.

None (required)

ldap-user-provisioning.group-name-attribute

The LDAP attribute that contains the group name. For example, sAMAccountName for Active Directory or cn for OpenLDAP.

None (required)

ldap-user-provisioning.group-unique-attribute

The LDAP attribute that contains a unique identifier for each group. For example, objectGUID for Active Directory or entryUUID for OpenLDAP.

None

ldap-user-provisioning.group-membership-attribute

The LDAP attribute on a group entry that lists its members. For example, member.

None (required)

ldap-user-provisioning.sync-interval

How often to synchronize.

1h

ldap-user-provisioning.identifier-mapping.pattern

A regular expression that transforms usernames and group names read from LDAP. Do not set together with identifier-mapping.file.

None

ldap-user-provisioning.identifier-mapping.file

The path to a JSON file with rules that transform usernames and group names read from LDAP. Do not set together with identifier-mapping.pattern.

None

ldap-user-provisioning.deletion-threshold-percent

The maximum percentage of users, and of groups, that a synchronization can delete.

10

ldap-user-provisioning.allow-mass-deletion

Disables the deletion threshold.

false

ldap-user-provisioning.dry-run

Logs the changes a synchronization would make without applying them.

false

Matching synchronized users to logins#

Control plane looks up the groups of a user by the username after user mapping. That username must match the synchronized username after identifier mapping. Otherwise, control plane refuses the user because it finds no account, or the user has an account with no groups. Starburst access control matches usernames exactly, so Alice and alice are different users.

For example, if users log in with OAuth2 as alice@example.com and the LDAP directory contains uid=alice, map the login to alice:

http-server.authentication.oauth2.user-mapping.pattern=(.*)(@.*)

By default, synchronization keeps the original case of usernames and group names. To avoid mismatches in case between logins and synchronized names, make all identifiers lowercase. Create etc/ldap-identifier-mapping.json:

{
  "rules": [
    { "pattern": "(.*)", "case": "lower" }
  ]
}

Then set ldap-user-provisioning.identifier-mapping.file to etc/ldap-identifier-mapping.json, and use "case": "lower" in your user mapping rules as well.

Use multiple LDAP servers#

You can synchronize users and groups from more than one LDAP server, for example when your users are in separate directories. Each server works independently. Control plane records which server each user and group came from.

To add a server, give it a name. Then add the properties for that server with the prefix ldap-user-provisioning.<name>.. The following example configures two servers, corp and partners:

ldap-user-provisioning.corp.ldap.url=ldaps://ldap-corp:636
ldap-user-provisioning.corp.ldap.bind-user=cn=service-account,dc=corp,dc=example,dc=com
ldap-user-provisioning.corp.ldap.bind-password=<BIND_PASSWORD>
ldap-user-provisioning.corp.user-search-base=ou=people,dc=corp,dc=example,dc=com
ldap-user-provisioning.corp.user-search-filter=(objectClass=inetOrgPerson)
ldap-user-provisioning.corp.user-name-attribute=uid
ldap-user-provisioning.corp.group-search-base=ou=groups,dc=corp,dc=example,dc=com
ldap-user-provisioning.corp.group-search-filter=(objectClass=groupOfNames)
ldap-user-provisioning.corp.group-name-attribute=cn
ldap-user-provisioning.corp.group-membership-attribute=member

ldap-user-provisioning.partners.ldap.url=ldaps://ldap-partners:636
ldap-user-provisioning.partners.ldap.bind-user=cn=service-account,dc=partners,dc=example,dc=com
ldap-user-provisioning.partners.ldap.bind-password=<BIND_PASSWORD>
ldap-user-provisioning.partners.user-search-base=ou=people,dc=partners,dc=example,dc=com
ldap-user-provisioning.partners.user-search-filter=(objectClass=user)
ldap-user-provisioning.partners.user-name-attribute=sAMAccountName
ldap-user-provisioning.partners.group-search-base=ou=groups,dc=partners,dc=example,dc=com
ldap-user-provisioning.partners.group-search-filter=(objectClass=group)
ldap-user-provisioning.partners.group-name-attribute=sAMAccountName
ldap-user-provisioning.partners.group-membership-attribute=member

The properties without a name configure a server called default. You can use the default server together with named servers.

The synchronization settings apply to all servers. These settings are the interval, the deletion threshold, the dry run, the retries, and the lock expiration. Set them once, without a server name.

How multiple servers work#

  • Each server synchronizes on its own. If a synchronization fails or stops on one server, the other servers continue.

  • Control plane removes only the users and groups that came from the server that no longer lists them.

  • Control plane detects conflicts. One server cannot change a user or group that came from another server.

Map group names separately#

By default, the identifier mapping for a server applies to both user names and group names. To map group names differently, set group.identifier-mapping.pattern or group.identifier-mapping.file for the server. These properties override the general identifier mapping for groups.

Move accounts to another server#

If you replace or rename a server, use the ldap-user-provisioning.adopt-sources property. The new server then takes over the users and groups of the old server, and it keeps their accounts.

Set the property to a comma-separated list of <from>:<to> pairs. For example, the following value moves the accounts of the default server to the corp server:

ldap-user-provisioning.adopt-sources=default:corp

Accounts that you created before multiple servers were supported belong to the default server. Control plane removes adopted accounts that the new server does not list. The deletion threshold limits how many accounts it can remove.

Do not chain adoption. Map each old server directly to its final server. For example, do not set a:b,b:c.

Additional properties#

Property

Description

Default

ldap-user-provisioning.<name>.ldap.url

The URL of a named LDAP server. Every property with the prefix ldap-user-provisioning.<name>. configures the server called <name>. The properties without a name configure the server called default.

None

ldap-user-provisioning.group.identifier-mapping.pattern

A regular expression that transforms group names read from LDAP. It overrides identifier-mapping.pattern for groups.

None

ldap-user-provisioning.group.identifier-mapping.file

The path to a JSON file with rules that transform group names read from LDAP. It overrides identifier-mapping.file for groups.

None

ldap-user-provisioning.adopt-sources

A comma-separated list of <from>:<to> pairs. The LDAP server <to> takes over the users and groups of the server <from>.

None

ldap-user-provisioning.max-retry-attempts

The maximum number of retries for LDAP fetch operations.

3

ldap-user-provisioning.initial-retry-delay

The delay before the first retry.

5s

ldap-user-provisioning.retry-backoff-multiplier

The multiplier for the exponential backoff between retries.

2.0

ldap-user-provisioning.lock-expiration

How long the synchronization lock is held.

30m