Provision users and groups with SCIM#
Starburst control plane can provision users and groups from an identity provider (IdP) by using the System for Cross-domain Identity Management (SCIM) protocol. The IdP pushes users, groups, and group memberships to control plane. This is different from LDAP synchronization, where control plane pulls them from a directory. You can use one provisioning type at a time. After the users and groups exist in control plane, use Starburst access control to give them access to data.
SCIM provisioning 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 protocol as SEP, described in SCIM user and group synchronization 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 provisioned groups needs the file on its own coordinator. See Use the provisioned groups on a managed cluster.You set the secret token in the configuration of control plane, not in the configuration of a cluster.
Enable SCIM provisioning#
Add the following properties to the config.properties file of control plane.
The secret token is the bearer token that the IdP uses to connect:
starburst.users.provisioning.type=SCIM
starburst.users.provisioning.scim.secret-token=<SECRET_TOKEN>
The secret token is required, and it cannot be empty. Store it as a secret. See Configure a secrets provider.
Network connectivity requirements#
Your IdP must reach the SCIM endpoint of control plane, /scim/v2. If you run
control plane in a private network, use one of the following approaches to allow
the IdP to reach it:
IP allowlisting: add the IP ranges of your IdP to your security groups.
Public endpoint: expose the SCIM endpoint to the internet with a secure load balancer.
Reverse proxy: use a reverse proxy to forward SCIM requests to control plane.
Configure the identity provider#
The IdP must connect to control plane, either directly or through a network proxy. The following steps are for Microsoft Entra ID and Okta.
Microsoft Entra ID#
To connect Microsoft Entra ID, which was Azure Active Directory, to control plane as a SCIM identity provider:
In Azure, go to Enterprise applications, and click New application.
Click Create your own application.
Enter a name for the application, select Integrate any other application you don’t find in the gallery (Non-gallery), and click Create.
From the navigation menu, select Users and groups. Click Add user/group. In the Add Assignment pane, click None Selected.
Use the Search bar to find and select the users or groups to assign to the application.
On the page of the new application, go to Provisioning, and click Get started.
Select Automatic in Provisioning Mode. In the Tenant URL field, enter the URL of control plane with the suffix
/scim/v2. In the Secret token field, enter the token that you set.Click Test connection. If the test succeeds, click Save.
Go to the Overview page, and select Start provisioning. The provisioning is scheduled, and it can take some time to finish.
Okta#
To connect Okta to control plane as a SCIM identity provider:
In Okta, go to Applications, and click Create App Integration.
Select SAML 2.0, and click Next.
Note
Okta does not support SCIM provisioning for OIDC - OpenID Connect applications. To use SCIM provisioning with OAuth2 authentication, create a second app integration with the SAML 2.0 sign-in method.
Enter a name for the integration, and click Next.
Enter a Single sign-on URL and an Audience URI (SP Entity ID). Provisioning does not use these values. Set them to the URL of control plane, and click Next.
Select I’m an Okta customer adding an internal app, and click Finish.
On the General tab, click Edit in the App Settings section.
Select the Enable SCIM provisioning checkbox, and click Save.
On the Provisioning tab, click Edit.
In the SCIM connector base URL field, enter the URL of control plane with the suffix
/scim/v2. In Unique identifier field for users, enter a user identifier.Select Import New Users and Profile Updates, Push New Users, Push Profile Updates, and Push Groups.
Select the HTTP Header authentication mode. In the Authorization field, enter the token that you set.
Click Test Connector Configuration. If the test succeeds, click Save.
On the Assignments tab, in the Assign menu, select the users or groups to assign to the app integration.
On the Provisioning tab, click Edit again.
Enable Create Users, Update User Attributes, and Deactivate Users, and click Save.
On the Push Groups tab, in the Push Groups menu, select the users or groups to add to the group push.
How SCIM provisioning affects login#
With SCIM provisioning, control plane creates accounts only when the IdP pushes them. 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 the IdP deleted stays deleted, and logging in does not create the user again. A user who is inactive stays refused. When you reactivate the user in the IdP, the user can log in again. Role assignments and default roles follow the groups that the IdP provisions.
Accounts that already exist keep their IDs and grants, and their users can still log in. To find an existing user, the IdP sends filtered SCIM queries by the user name, and it uses the resource ID that control plane assigned to update the user. A request that creates a user that already exists returns HTTP status 409. It does not take over the existing account. An update that changes the user takes the account over, and the account keeps its ID.
On a new installation, provision the first administrator before their first
request. Create the user with SCIM, by using the secret token. The properties
starburst.access-control.authorized-users and
starburst.access-control.authorized-groups 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. For more about the account lifecycle, see
How synchronization affects login.
Use the provisioned groups on a managed cluster#
Control plane stores the users and groups that it provisions. 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 provisioned 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 LDAP synchronization as well. For the other steps to connect a cluster, see Connect a cluster to control plane.
Limitations#
Okta does not support using the same group for both app assignments and Group Push. To keep the group memberships consistent between Okta and control plane, use separate groups for app assignments and for Group Push. See the Okta documentation.
Control plane does not support nested group membership.