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:
Control plane does not use a group provider. Do not create an
etc/group-provider.propertiesfile on control plane. A managed cluster that uses the synchronized groups needs the file on its own coordinator. See Use the synchronized groups on a managed cluster. Control plane does not support the LDAP group provider, which queries the directory directly.Control plane also supports synchronization with SCIM. See Provision users and groups with SCIM.
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:
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.
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.
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-usersorstarburst.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:
On the coordinator of the cluster, create the file
etc/group-provider.propertieswith the following content:group-provider.name=portal
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 |
|---|---|---|
|
The base DN for user searches. |
None (required) |
|
The LDAP search filter for user entries. For example, |
None (required) |
|
The LDAP attribute that contains the username. For example, |
None (required) |
|
The LDAP attribute that contains a unique identifier for each user. For
example, |
None |
|
The base DN for group searches. |
None (required) |
|
The LDAP search filter for group entries. For example, |
None (required) |
|
The LDAP attribute that contains the group name. For example,
|
None (required) |
|
The LDAP attribute that contains a unique identifier for each group. For
example, |
None |
|
The LDAP attribute on a group entry that lists its members. For example,
|
None (required) |
|
How often to synchronize. |
|
|
A regular expression that transforms usernames and group names read from
LDAP. Do not set together with |
None |
|
The path to a JSON file with rules that transform usernames and group names
read from LDAP. Do not set together with |
None |
|
The maximum percentage of users, and of groups, that a synchronization can delete. |
|
|
Disables the deletion threshold. |
|
|
Logs the changes a synchronization would make without applying them. |
|
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 |
|---|---|---|
|
The URL of a named LDAP server. Every property with the prefix
|
None |
|
A regular expression that transforms group names read from LDAP. It
overrides |
None |
|
The path to a JSON file with rules that transform group names read from
LDAP. It overrides |
None |
|
A comma-separated list of |
None |
|
The maximum number of retries for LDAP fetch operations. |
|
|
The delay before the first retry. |
|
|
The multiplier for the exponential backoff between retries. |
|
|
How long the synchronization lock is held. |
|