Configure SCIM provisioning on Grafana Labs

Manage users and teams with SCIM

Fri, 03 Apr 2026 19:43:06 +0000

Manage users and teams with SCIM

Note
Available in Grafana Enterprise and Grafana Cloud.

SCIM streamlines identity management in Grafana by automating user lifecycle and team membership operations. This guide explains how SCIM works with existing Grafana setups, handles user provisioning, and manages team synchronization.

With SCIM, you can:

Automate user lifecycle from creation to deactivation
Manage existing users by linking them with identity provider identities
Automate team lifecycle by automatically creating teams when groups are added, updating team memberships, and deleting teams when groups are removed
Maintain security through automated deprovisioning
Replace Team Sync with more robust SCIM group synchronization

User provisioning with SCIM

SCIM provisioning works in conjunction with existing user management methods in Grafana. While SCIM automates user provisioning from the identity provider, users can still be created through SAML just-in-time provisioning when they log in, manually through the Grafana UI, or via automation tools like Terraform and the Grafana API. For the most consistent user management experience, we recommend centralizing user provisioning through SCIM.

Note
User provisioning requires user_sync_enabled = true in the SCIM configuration. See Configure SCIM in Grafana for more information.

Warning
After a user is provisioned through SCIM, they cannot be deleted from Grafana - they can only be deactivated through the identity provider. This is important to consider when planning your user management strategy, especially for compliance and data retention requirements.

For detailed configuration steps specific to the identity provider, see:

How SCIM identifies users

SCIM uses a specific process to establish and maintain user identity between the identity provider and Grafana:

Initial user lookup:
- The administrator configures SCIM at the Identity Provider, defining the Unique identifier field
- The identity provider looks up each user in Grafana using this unique identifier field as a filter
- The identity provider expects a single result from Grafana for each user
Identity linking based on lookup results:
- If there’s a single matching result: The identity provider retrieves the user’s unique ID at Grafana, saves it, confirms it can fetch the user’s information, and updates the user’s information in Grafana
- If there are no matching results: The identity provider attempts to create the user in Grafana. If successful, it retrieves and saves the user’s unique ID for future operations. If a user with the same email address already exists in Grafana, the user is updated and will be managed by SCIM from that point forward.
- The identity provider learns the relationship between the found Grafana user and the Grafana internal ID
- The identity provider updates Grafana with the External ID
- Grafana updates the authentication validations to expect this External ID
Matching the User During Login: When a user logs in via SAML, Grafana needs to securely match them to the correct user account provisioned by SCIM. This requires using a consistent, unique identifier across both processes (for example, the user’s objectId in Entra ID).
- Configure SAML Claims: Set up your identity provider (e.g., Entra ID) to include this unique identifier in the information it sends during SAML login.
- Configure Grafana SAML: In the Grafana SAML settings, use the assertion_attribute_login setting to specify which incoming SAML attribute contains this unique identifier.
- Configure SCIM Mapping: To complete the link, ensure your SCIM attribute mapping in the identity provider sets the user’s Grafana externalId attribute to be the same unique identifier provided via SAML (for example, the user’s objectId in Entra ID).
- See SAML configuration details for specific configuration guidance.

This process ensures secure and consistent user identification across both systems, preventing security issues that could arise from email changes or other user attribute modifications.

Note
During provisioning, if the identity provider sends user attributes that has no use in Grafana, those attributes will be gracefully ignored.

Existing Grafana users

For users who already exist in the Grafana instance:

SCIM establishes the relationship through the External ID matching process
Creates a secure link with the identity provider identity
Preserves all existing settings and access
Keeps the account active and unchanged until assigned in the identity provider

Handling users from other provisioning methods

To prevent conflicts and maintain consistent user management, disable or restrict other provisioning methods when implementing SCIM. This ensures that all new users are created through SCIM and prevents duplicate or conflicting user records.

SAML Just-in-Time (JIT) provisioning:
- Disable allow_sign_up in SAML settings to prevent automatic user creation
- Existing JIT-provisioned users will continue to work but should be migrated to SCIM
Terraform or API provisioning:
- Stop creating new users through these methods
- Existing users will continue to work but should be migrated to SCIM
- Consider removing or archiving Terraform user creation resources
Manual user creation:
- Restrict UI-based user creation to administrators only
- Plan to migrate manually created users to SCIM

New users

For users who don’t yet exist in Grafana:

SCIM creates accounts when users are assigned to Grafana in the identity provider
Sets up initial access based on identity provider group memberships and SAML role mapping
No manual Grafana account creation needed

Role management

SCIM handles user synchronization but not role assignments. Role management is handled through Role Sync, and any role changes take effect during user authentication.

Migrating existing users to SCIM provisioning

If you have an existing Grafana instance with manually created users and want to migrate to IDP-based SCIM provisioning, you can leverage the SCIM identification mechanism to seamlessly link existing users with their IDP identities.

Migration overview

The migration process uses the same user identification mechanism described earlier, but focuses on linking existing Grafana users with their corresponding IDP identities rather than creating new users.

Key benefits of this approach:

Preserves all existing user settings, dashboards, and permissions
No disruption to user access during migration
Gradual migration possible (users can be migrated in batches)
Maintains audit trails and historical data

Migration steps

Prepare the identity provider:
- Ensure all existing Grafana users have corresponding accounts in your IDP
- Verify that the unique identifier field (e.g., email, username, or object ID) matches between systems
- Configure SCIM application in your IDP but don’t assign users yet
Configure SCIM in Grafana:
- Set up SCIM endpoint and authentication as described in Configure SCIM in Grafana
- Enable user_sync_enabled = true
- Configure the unique identifier field to match your IDP setup

Note
To restrict login access to only SCIM-provisioned users, enable the [auth.scim][reject_non_provisioned_users] option. Cloud Portal users can always sign in regardless of this setting.
ini
[auth.scim]
reject_non_provisioned_users = true

Test the matching mechanism:

Use the SCIM API to verify that existing users can be found using the unique identifier:

curl --location 'https://{$GRAFANA_URL}/apis/scim.grafana.app/v0alpha1/namespaces/{$STACK_ID}/Users?filter=userName eq "existing.user@company.com"' \
--header 'Authorization: Bearer glsa_xxxxxxxxxxxxxxxxxxxxxxxx'

This should return exactly one user record for each existing user

Assign users in the IDP:
- Begin assigning existing users to the Grafana application in your IDP
- The SCIM identification process will automatically link existing Grafana users with their IDP identities
- Monitor the process for any conflicts or errors
Verify the migration:
- Check that users can still access Grafana with their existing permissions
- Verify that SAML/SSO login works correctly for migrated users
- Ensure External ID is properly set for each migrated user

Migration considerations

Before migration:

Backup your Grafana database - Always have a recovery plan
Audit existing users - Document current user accounts and their access levels
Plan for exceptions - Some users might need manual intervention if unique identifiers don’t match

During migration:

Monitor logs - Watch for SCIM errors or conflicts during the linking process in Grafana and your Identity Provider
Batch processing - Consider migrating users in small batches to identify issues early
Communication - Inform users about the migration timeline and any required actions

After migration:

Disable manual provisioning - Prevent new users from being created outside of SCIM
Update documentation - Ensure team procedures reflect the new IDP-based workflow
Regular audits - Periodically verify that IDP and Grafana users remain in sync

Troubleshooting migration issues

Multiple users found for unique identifier:

Review your unique identifier field configuration
Check for duplicate accounts in Grafana or the IDP
Consider using a more specific identifier (e.g., object ID instead of email)

User not found during lookup:

Verify the unique identifier value matches exactly between systems
Check that the user exists in both Grafana and the IDP

Authentication failures after migration:

Confirm the SAML assertion assertion_attribute_external_uid includes the correct unique identifier
Verify that your SAML configuration uses the same unique identifier for both SCIM and SAML authentication

Team provisioning with SCIM

SCIM provides automated team management capabilities that go beyond what Team Sync offers. While Team Sync only maps identity provider groups to existing Grafana teams, SCIM can automatically create and delete teams based on group changes in the identity provider.

Note
Team provisioning requires group_sync_enabled = true in the SCIM configuration. See Configure SCIM in Grafana for more information.

Warning
Teams provisioned through SCIM cannot be deleted manually from Grafana - they can only be deleted by removing their corresponding groups from the identity provider. Optionally, you can disable SCIM group sync to allow manual deletion of teams.

For detailed configuration steps specific to the identity provider, see:

SCIM vs Team Sync

Warning
Do not enable both SCIM Group Sync and Team Sync simultaneously as these methods can conflict with each other. However, you can use SCIM for user provisioning while keeping Team Sync for team management until migration support is available.

Choose one team synchronization method:

If you enable SCIM Group Sync, disable Team Sync and use SCIM for team management
If you prefer Team Sync, do not enable SCIM Group Sync

Warning
Team Sync Migration: Support for migrating from Team Sync to SCIM Group Sync is coming soon. Until this support is released, we recommend keeping your existing Team Sync setup for team management. You can still benefit from SCIM user provisioning capabilities while using Team Sync for team management.

Key differences

SCIM Group Sync provides several advantages over Team Sync:

Automatic team creation: SCIM automatically creates Grafana teams when new groups are added to the identity provider
Automatic team deletion: SCIM removes teams when their corresponding groups are deleted from the identity provider
Real-time updates: Team memberships are updated immediately when group assignments change
Simplified management: No need to manually create teams in Grafana before mapping them

How team synchronization works

SCIM manages teams through the following process:

Group assignment:

User is assigned to groups in the identity provider
SCIM detects group membership changes

Team creation and mapping:

Creates Grafana teams for new identity provider groups
Maps users to appropriate teams
Removes users from teams when group membership changes

Team membership maintenance:

Continuously syncs team memberships
Removes users from teams when removed from groups
Updates team memberships when groups change

Next steps

Configure SCIM with Entra ID

Fri, 03 Apr 2026 19:43:06 +0000

Configure SCIM with Entra ID

Note
Available in Grafana Enterprise and Grafana Cloud.

This guide explains how to configure SCIM provisioning with Entra ID to automate user and team management in Grafana.

Note
Important SAML and SCIM Configuration: When using SAML for authentication alongside SCIM provisioning with Entra ID, it is crucial to correctly align user identifiers. For detailed information on why this is critical for security and how to configure it, refer to the main SCIM provisioning documentation.

Refer to the SAML authentication with Entra ID documentation for specific instructions on how to configure SAML claims and Grafana SAML settings for your Entra ID SCIM setup.

Prerequisites

Before configuring SCIM with Entra ID, ensure you have:

Grafana Enterprise or a paid Grafana Cloud account with SCIM provisioning enabled.
Admin access to both Grafana and Entra ID
SCIM feature enabled in Grafana

Configure SCIM in Grafana

To enable SCIM provisioning in Grafana, create a service account and generate a service account token that will be used to authenticate SCIM requests from Entra ID.

Create a service account

Navigate to Administration > Users and access > Service accounts
Click Add service account
Create a new service account with Role: “None”
In the service account Permissions tab, add these permissions:

Allow the service account to sync users:
- org.users:read
- org.users:write
- org.users:add
- org.users:remove
Allow the service account to sync groups:
- teams:read
- teams:create
- teams:write
- teams:delete
Create a new token for the newly created service account and save it securely
- This token will be used in the Entra ID configuration

Configure SCIM in Entra ID

Configure the enterprise application in Entra ID to enable automated user and team synchronization with Grafana. This involves creating a new application and setting up both authentication and provisioning.

Create the enterprise application

Open Azure Portal Entra ID (Entra ID)
Click + Add dropdown
Click Add Enterprise Application
Click + Create Your Own Application
Name the application and select non-gallery

Configure provisioning

In the application overview, select Provisioning
Click + New Configuration
Configure the following settings:

Tenant URL:

You can copy the tenant URL directly from the SCIM UI at Administration > Authentication > SCIM. Your stack domain and stack ID can also be found in the SCIM UI.

Alternatively, you can construct the URL manually:
- For Grafana Cloud instances:
```
https://{stack-name}.grafana.net/apis/scim.grafana.app/v0alpha1/namespaces/stacks-{stack-id}
```
  Replace {stack-name} and {stack-id} with your Grafana Cloud stack name and ID.
- For self-hosted instances:
```
https://{your-grafana-domain}/apis/scim.grafana.app/v0alpha1/namespaces/default
```
  Replace {your-grafana-domain} with your Grafana instance’s domain (e.g., grafana.yourcompany.com).
Secret Token: Enter the service account token from Grafana

Click Test connection to verify the configuration
Click Create to save the settings

Configure attribute mappings

After setting the Tenant URL and Secret Token, navigate to the Mappings section within the same Provisioning settings in your Entra ID enterprise application and then click Provision Microsoft Entra ID Users. This is where you will define how Entra ID attributes correspond to the SCIM attributes for Grafana, including the mandatory externalId.

Note

Only work email addresses are supported. Entra ID must be configured to use emails[type eq "work"].value for email mapping.

The externalId attribute in Grafana is mandatory. Entra ID uses this to uniquely identify users and groups. You must map an attribute from Entra ID to the externalId attribute in Grafana. This Entra ID attribute must be a stable and a unique identifier for each individual user (for example, the objectId attribute in Entra ID is commonly used for this purpose).

Configure the following required attributes:

Entra ID Attribute	Grafana Attribute
`userPrincipalName`	`userName`
`mail`	`emails[type eq "work"].value`
`displayName`	`displayName`
`objectId`	`externalId`
`Switch([IsSoftDeleted], , "False", "True", "True", "False")`	`active`

Note
During provisioning, if the identity provider sends user attributes that has no use in Grafana, those attributes will be gracefully ignored.

Enable provisioning

Click Start provisioning from the top action bar in the Overview page from your Entra ID enterprise application.

Configure group provisioning

To enable group synchronization:

Navigate to the Groups tab in provisioning
Enable Group provisioning
Select the groups to synchronize with Grafana
Save the changes

Test the integration

After completing the configuration:

Test the SCIM connector in Entra ID
Assign a test user to the application
Verify the user is provisioned in Grafana
Test group synchronization if configured

Configure SCIM with Okta

Fri, 03 Apr 2026 19:43:06 +0000

Configure SCIM with Okta

Note
Available in Grafana Enterprise and Grafana Cloud.

This guide explains how to configure SCIM provisioning with Okta to automate user and team management in Grafana.

Prerequisites

Before configuring SCIM with Okta, ensure you have:

Grafana Enterprise or a paid Grafana Cloud account with SCIM provisioning enabled.
Admin access to both Grafana and Okta
SAML authentication configured with Okta
SCIM feature enabled in Grafana

Note
Important SAML and SCIM Configuration: When using SAML for authentication alongside SCIM provisioning with Okta, it is crucial to correctly align user identifiers. For detailed information on why this is critical for security and how to configure it, refer to the main SCIM provisioning documentation.

Ensure your Okta SAML application is configured to send a stable, unique identifier (that will map to the Grafana SCIM externalId) as a SAML claim. Then, configure the Grafana SAML settings to use this claim. For general Okta SAML setup, refer to Set up SAML with Okta.

Configure SCIM in Grafana

To enable SCIM provisioning in Grafana, create a service account and generate an access token that will be used to authenticate SCIM requests from Okta.

Create a service account

Navigate to Administration > Users and access > Service accounts
Click Add service account
Create a new service account with Role: “None”
In the service account Permissions tab, add these permissions:

Allow the service account to sync users:
- org.users:read
- org.users:write
- org.users:add
- org.users:remove
Allow the service account to sync groups:
- teams:read
- teams:create
- teams:write
- teams:delete
Create a new token for the newly created service account and save it securely
- This token will be used in the Okta configuration

Configure SCIM in Okta

Configure both SAML authentication and SCIM provisioning in Okta to enable automated user and team synchronization with Grafana. Start by creating a SAML application, then enable and configure SCIM provisioning for that application.

Enable SCIM provisioning

Navigate to the General tab of your SAML App Integration in Okta
Enable SCIM provisioning
- A new provisioning tab will appear

Configure provisioning settings

To enable user provisioning through SCIM, configure the SCIM integration settings in Grafana by specifying the connector URL, authentication mode, and supported provisioning actions. Follow these steps to complete the integration.

Configure SCIM integration

In the Integration tab, configure:

SCIM Connector base URL:

You can copy the complete SCIM Connector base URL directly from the SCIM UI at Administration > Authentication > SCIM. This is displayed as the Tenant URL in the UI. Your stack domain and stack ID can also be found in the SCIM UI.

Alternatively, you can construct the URL manually:
- For Grafana Cloud instances:
```
https://{stack-name}.grafana.net/apis/scim.grafana.app/v0alpha1/namespaces/stacks-{stack-id}
```
  Replace {stack-name} and {stack-id} with your Grafana Cloud stack name and ID.
- For self-hosted instances:
```
https://{your-grafana-domain}/apis/scim.grafana.app/v0alpha1/namespaces/default
```
  Replace {your-grafana-domain} with your Grafana instance’s domain (e.g., grafana.yourcompany.com).
Unique identifier field: userName
Supported provisioning actions:
- Import New Users and Profile Updates
- Push New Users
- Push Profile Updates
Authentication Mode: HTTP Header
Authorization: Bearer {your-grafana-service-account-token}
Click Test Connector Configuration and then save the configuration

In the To App tab, enable:

Create Users
Update User Attributes
Deactivate Users

After completing the configuration:

Test the SCIM connector in Okta
Assign a test user to the application
Verify the user is provisioned in Grafana

Troubleshoot SCIM provisioning

Fri, 03 Apr 2026 19:43:06 +0000

Troubleshoot SCIM provisioning

This page provides solutions for common issues you might encounter when configuring and using SCIM provisioning in Grafana.

User provisioning issues

Error: “invalid namespace”

Cause: The SCIM endpoint URL is incorrectly formatted.

Solution: Verify your URL follows the correct format:

https://{$GRAFANA_URL}/apis/scim.grafana.app/v0alpha1/namespaces/{$STACK_ID}/Users

Where:

{$GRAFANA_URL} is your Grafana URL (subdomain format)
{$STACK_ID} is your Grafana stack ID:
- Grafana Cloud: Format like stack-123 (found in your Grafana Cloud dashboard)
- On-premises: Use default or the name of the organization

Authentication issues

Error: “HTTP 403 Forbidden”

Cause: Either incorrect token or insufficient permissions.

Solution:

Check token: Generate a new token from the Service Account details page
Verify permissions: Ensure the service account has Editor or Admin role in the Grafana instance

Error: “HTTP 401 Unauthorized”

Cause: Invalid or expired authentication token.

Solution: Generate a new token from the Service Account details page in Grafana.

Error: “User sync failed”

Cause: The user’s unique identifier field is not correctly configured in SAML assertions.

Solution: Add the required SAML assertion based on your identity provider:

SAML Assertion	Identity Provider	Value
`userUID`	Entra ID	`objectId`
`userUID`	Okta	`user.getInternalProperty("id")`

Configure SCIM provisioning on Grafana Labs

Manage users and teams with SCIM

Manage users and teams with SCIM

User provisioning with SCIM

How SCIM identifies users

Existing Grafana users

Handling users from other provisioning methods

New users

Role management

Migrating existing users to SCIM provisioning

Migration overview

Migration steps

Migration considerations

Troubleshooting migration issues

Team provisioning with SCIM

SCIM vs Team Sync

Key differences

How team synchronization works

Next steps

Configure SCIM with Entra ID

Configure SCIM with Entra ID

Prerequisites

Configure SCIM in Grafana

Create a service account

Configure SCIM in Entra ID

Create the enterprise application

Configure provisioning

Configure attribute mappings

Enable provisioning

Configure group provisioning

Test the integration

Configure SCIM with Okta

Configure SCIM with Okta

Prerequisites

Configure SCIM in Grafana

Create a service account

Configure SCIM in Okta

Enable SCIM provisioning

Configure provisioning settings

Configure SCIM integration

Troubleshoot SCIM provisioning

Troubleshoot SCIM provisioning

User provisioning issues

Error: “invalid namespace”

Authentication issues

Error: “HTTP 403 Forbidden”

Error: “HTTP 401 Unauthorized”

Login issues

Error: “User sync failed”

Next steps