---
component: ROOT
version: "2026.1"
slug: ROOT/administration/user-provisioning
canonical_url: "https://docs.gradle.com/develocity/2026.1/administration/access-control/user-provisioning/"
title: "User Provisioning"
description: "Automate user account management and lifecycle in Develocity using SCIM 2.0 or local configuration."
keywords: []
status: current
---

<!-- llms-index: https://docs.gradle.com/develocity/llms.txt -->

# User Provisioning

<a id="preamble"></a>

Govern the automated lifecycle of user accounts, from initial synchronization to ongoing maintenance via your identity provider.

This ensures that permissions stay in sync with your organization’s source of truth and reduces the administrative overhead of manual account management.

<a id="local-user-management"></a>

## Local User Management

For smaller teams or service accounts, you can manage users manually within Develocity. These accounts can coexist with SCIM-managed accounts provided the usernames and emails are unique.

<a id="create-a-local-user"></a>

### Create a Local User

1.  Navigate to **Administration**  **Access control**.
    
2.  Select the **Users** tab.
    
3.  Click **Add user**.
    
4.  Provide the username, email, and a secure initial password.
    
5.  Assign the appropriate **Roles** to the user.
    
6.  Click **Save**.
    

![Add Local User in Develocity UI](https://docs.gradle.com/develocity/2026.1/administration/access-control/user-provisioning/../../_images/dv-ui-add-local-user.png)

Add Local User in Develocity UI

<a id="configuration-fields"></a>

#### Configuration Fields

<table class="tableblock frame-all grid-all stretch"><colgroup><col style="width: 25%;"> <col style="width: 75%;"></colgroup><tbody><tr><td class="tableblock halign-left valign-top">Setting</td><td class="tableblock halign-left valign-top">Description</td></tr><tr><td class="tableblock halign-left valign-top">Username</td><td class="tableblock halign-left valign-top">The unique identifier for the user. Must be lowercase and cannot conflict with SCIM-managed usernames</td></tr><tr><td class="tableblock halign-left valign-top">Email</td><td class="tableblock halign-left valign-top">The user’s email address. This is used for notifications and must be unique across all users.</td></tr><tr><td class="tableblock halign-left valign-top">Password</td><td class="tableblock halign-left valign-top">A secure initial password for the user. The user will be prompted to change this on first login.</td></tr><tr><td class="tableblock halign-left valign-top">Roles</td><td class="tableblock halign-left valign-top">The permissions assigned to the user. Choose from predefined roles or create custom ones to fit your organization’s needs.</td></tr></tbody></table>

For more details on role and project group definitions, see [Roles and Permissions](https://docs.gradle.com/develocity/2026.1/administration/access-control/permissions-and-roles/) and [Project Level Access Control](https://docs.gradle.com/develocity/2026.1/administration/access-control/project-level-access-control/).

> [!TIP]
> Keep your configuration safe
> 
> Before making major changes to system settings, consider exporting your current configuration via **Administration**  **System Maintenance**  **Import/Export**.

<a id="scim_integration"></a>

## SCIM 2.0 Provisioning

Develocity supports the **System for Cross-domain Identity Management (SCIM 2.0)** protocol. This allows Identity Providers (IdPs) like Okta or Microsoft Entra ID to push user and group changes directly to Develocity.

<a id="configure-via-the-user-interface"></a>

### Configure via the User Interface

To enable SCIM integration in Develocity:

1.  Navigate to **Administration**  **Access control**.
    
2.  Select the **SCIM** tab.
    
3.  Check the **Enable SCIM integration** checkbox.
    
4.  Click **Generate token** (or **Regenerate token** if updating an existing setup).
    
5.  **Important:** Copy the **Base URL** and **SCIM token** immediately. You will need these to configure your Identity Provider.
    
6.  Click **Save**, then click **Apply** in the upper right header.
    

![SCIM Configuration in Develocity UI](https://docs.gradle.com/develocity/2026.1/administration/access-control/user-provisioning/../../_images/dv-ui-scim.png)

SCIM Configuration in Develocity UI

<a id="configure-via-unattended-configuration"></a>

## Configure via Unattended Configuration

If you manage your Develocity security policy via Helm or GitOps, enable the SCIM endpoint in your `values.yaml` file.

```yaml
version: 15
systemPassword: "«hashed-system-password»"
auth:
  scim:
    enabled: true
    token:
      hash: C5tFAR9uF6vCMSWtKT77p5vKEj9po7WOaZ5aBZFtIZk=:GbbMg4NkEIG7OwSpGdaRx3OmzfdlTS21/QCpN6r8en9jK9Rw== (1)
      length: 52 (2)
      prefix: wrcrghvyory4owu7accwe2f6xr (3)
```

1. The hashed token used for SCIM authentication.
2. The length of the token.
3. The prefix of the token.

After updating your values.yaml file, you will need to re-deploy Develocity using Helm for the changes to take effect. See [Unattended Configuration](https://docs.gradle.com/develocity/2026.1/administration/unattended-configuration/) for more details.

> [!IMPORTANT]
> Applying the configuration updates the system services and may take several minutes to complete.

* * *

<a id="identity-provider-setup"></a>

## Identity Provider Setup

Once SCIM is enabled in Develocity, configure your provider using the **Base URL** and **Bearer Token** obtained above.

<a id="scim_azuread"></a>

### Microsoft Entra ID (formerly Azure AD)

This section assumes you have a pre-existing application for Develocity in Microsoft Entra ID, and the application is already configured for SAML single sign on. If not, configure an application before proceeding.

To sync users from Entra ID, navigate to your Develocity application in the Azure portal:

1.  Navigate to **Manage**  **Provisioning**.
    
2.  Navigate to **Manage**  **Provisioning** (again).
    
3.  In the **Provisioning Mode** field, select **Automatic**.
    
4.  Set the "Tenant URL" field to the "Base URL" value from the Develocity application (should look like `https://«hostname»/identity/scim/v2`).
    
5.  Set the "Secret Token" field to the "SCIM token" value from the Develocity application.
    
6.  Select **Save**.
    
7.  Navigate to **Mappings**  **Provision Microsoft Entra ID Groups**.
    
8.  Set **Enabled** to **No**.
    
9.  Click **Save** and confirm by clicking **Yes**.
    
10.  Navigate to **Provisioning**.
     
11.  Navigate to **Mappings**  **Provision Microsoft Entra ID Users**.
     
12.  In the **Target Object Actions** section, uncheck **Create**.
     
13.  Click **Save** and confirm by clicking **Yes**.
     
14.  Navigate to **Provisioning**.
     
15.  In the **Settings** section, set **Provisioning Status** to **On**.
     
16.  Select **Save**.
     

> [!TIP]
> The default attribute mappings should work without modification.

> [!NOTE]
> Users who have been assigned to the application but haven’t yet logged in won’t show in the Develocity interface and will be skipped during provisioning operations. Microsoft Entra ID performs provisioning on a fixed cycle, which may cause noticeable delays before changes take effect. See How long will it take to provision users? for more information. For more information, refer to the Microsoft Entra ID documentation: How Application Provisioning works in Microsoft Entra ID

<a id="scim_okta"></a>

### Okta

This section assumes you have a pre-existing app integration for Develocity in Okta, and the app integration is already configured for SAML 2.0 single sign on. If not, configure an app integration before proceeding.

> [!NOTE]
> Okta requires a trusted SSL certificate.

1.  Navigate to your SAML 2.0 app integration.
    
2.  Navigate to the **General** tab.
    
3.  In the **App Settings** section:
    
    1.  Click **Edit**.
        
    2.  In the **Provisioning** field, check **Enable SCIM provisioning**.
        
    3.  Click **Save**.
        
    
4.  Navigate to the **Provisioning** tab (won’t be visible if you missed the previous step).
    
5.  In the **Settings**  **Integration** section:
    
    1.  Click **Edit**.
        
    2.  Set the **SCIM connector base URL** field to the "Base URL" value from the Develocity application (should look like `https://«hostname»/identity/scim/v2`).
        
    3.  Set the **Unique identifier field for users** field to "userName".
        
    4.  In the **Supported provisioning actions** section, check **Push New Users** and **Push Profile Updates**.
        
    5.  In the **Authentication Mode** field, select **HTTP Header**.
        
    6.  Set the "HTTP Header", "Authorization", "Bearer" field to the "SCIM token" value from the Develocity application.
        
    7.  Click **Test Connector Configuration**.
        
    8.  Review the results and click **Close**.
        
    9.  Click **Save**.
        
    
6.  In the **Settings**  **To App** section (won’t be visible if you missed the previous step):
    
    1.  Click **Edit**.
        
    2.  In the **Update User Attributes** field, check **Enable**.
        
    3.  Click **Save**.
        
    

> [!TIP]
> The default attribute mappings should work without modification.

> [!NOTE]
> Users who have been assigned to the application but haven’t yet logged in may cause an error message like "Automatic provisioning of user …​ to app …​ failed: Matching user not found" to be shown. This is expected and not harmful. If you want to clear the error, go to Okta’s **Dashboard**  **Tasks** page after the user has logged in, select the relevant app assignments, and click **Retry Selected**.

> [!NOTE]
> Okta [doesn’t delete users](https://developer.okta.com/docs/api/openapi/okta-scim/guides/scim-20/#delete-users) via SCIM. Rather, it sets the `active` attribute to `false`.

For more information, refer to the Okta documentation:

*   [Add an app integration to Okta](https://help.okta.com/en-us/Content/Topics/Provisioning/lcm/lcm-add-application.htm)
    
*   [Configure provisioning for an app integration](https://help.okta.com/en-us/Content/Topics/Provisioning/lcm/lcm-provision-application.htm)
    

<a id="technical-notes-and-limitations"></a>

## Technical Notes and Limitations

*   **Authentication:** SCIM authentication is only supported via Bearer Tokens.
    
*   **Username Normalization:** All usernames are normalized to lowercase.
    
*   **Conflicts:** Users created via SCIM are local to Develocity and will block using that `userName` with an identity provider.
    
*   **First Login Requirement:** Identity providers create users on first login; attempts to update a user before first login will fail.
    
*   **Supported User Attributes** (others may work):
    
    *   `active`
        
    *   `emails`
        
    *   `id`
        
    *   `name.familyName`
        
    *   `name.givenName`
        
    
*   **Supported Group Attributes** (others may work):
    
    *   `displayName`
        
    *   `id`
        
    *   `members`
        
    
*   **Deletion Behavior:** Most providers (like Okta) don’t "delete" users via SCIM; they set the `active` attribute to `false`, which disables the user’s access in Develocity.