SCIM: doc upgrades (#108098)

* Add public preview warning * Add migration strategy * Add troubleshooting guide * Improve description * Improve docs * Add versbosity * Addresss PR comments
2025-07-16 20:39:09 +02:00
parent 2444fb1caf
commit 91a54d0e0e
4 changed files with 188 additions and 4 deletions
@@ -24,6 +24,10 @@ Available in [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/g
 Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.
 {{< /admonition >}}

+{{< admonition type="warning" >}}
+**Public Preview:** SCIM provisioning is currently in Public Preview. While functional, the feature is actively being refined and may undergo changes. We recommend thorough testing in non-production environments before deploying to production systems.
+{{< /admonition >}}
+
 {{< admonition type="note" >}}
 This feature is behind the `enableSCIM` feature toggle.
 You can enable feature toggles through configuration file or environment variables.
@@ -24,6 +24,10 @@ weight: 320
 Available in [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
 {{< /admonition >}}

+{{< admonition type="warning" >}}
+**Public Preview:** SCIM provisioning is currently in Public Preview. While functional, the feature is actively being refined and may undergo changes. We recommend thorough testing in non-production environments before deploying to production systems.
+{{< /admonition >}}
+
 This guide explains how to configure SCIM provisioning with Azure AD to automate user and team management in Grafana.

 {{< admonition type="note" >}}
@@ -22,6 +22,10 @@ weight: 320
 Available in [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
 {{< /admonition >}}

+{{< admonition type="warning" >}}
+**Public Preview:** SCIM provisioning is currently in Public Preview. While functional, the feature is actively being refined and may undergo changes. We recommend thorough testing in non-production environments before deploying to production systems.
+{{< /admonition >}}
+
 This guide explains how to configure SCIM provisioning with Okta to automate user and team management in Grafana.

 {{< admonition type="note" >}}
@@ -21,6 +21,10 @@ weight: 310
 Available in [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
 {{< /admonition >}}

+{{< admonition type="warning" >}}
+**Public Preview:** SCIM provisioning is currently in Public Preview. While functional, the feature is actively being refined and may undergo changes. We recommend thorough testing in non-production environments before deploying to production systems.
+{{< /admonition >}}
+
 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:
@@ -52,18 +56,21 @@ For detailed configuration steps specific to the identity provider, see:

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

-1. Initial user lookup:
+1. **Initial user lookup:**

-   - The identity provider looks up users in Grafana using the user's login and the Unique identifier field (configurable at IdP)
+   - 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

-2. Identity linking:
+2. **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 there's a conflict with an existing user, the identity provider flags the error and Grafana logs the error message
   - 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

-3. Matching the User During Login:
+3. **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 Azure AD).
   - **Configure SAML Claims:** Set up your identity provider (e.g., Azure AD) 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.
@@ -116,6 +123,107 @@ For users who don't yet exist in Grafana:

 SCIM handles user synchronization but not role assignments. Role management is handled through [Role Sync](../../configure-authentication/saml#configure-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](#how-scim-identifies-users) 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
+
+1. **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
+
+2. **Configure SCIM in Grafana:**
+
+   - Set up SCIM endpoint and authentication as described in [Configure SCIM in Grafana](../../configure-scim-provisioning#configure-scim-in-grafana)
+   - Enable `user_sync_enabled = true`
+   - Configure the unique identifier field to match your IDP setup
+
+{{< admonition type="note" >}}
+When `user_sync_enabled = true`, non-provisioned users will be disallowed from logging in, except for `admin` and Grafana.com login.
+
+If you want to allow non-provisioned users to log in, enable the `[auth.scim][allow_non_provisioned_users]` option.
+
+```ini
+[auth.scim]
+allow_non_provisioned_users = true
+```
+
+{{< /admonition >}}
+
+3. **Test the matching mechanism:**
+
+   - Use the SCIM API to verify that existing users can be found using the unique identifier:
+
+   ```bash
+   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
+
+4. **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
+
+5. **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.
@@ -177,3 +285,67 @@ Team membership maintenance:
 - Continuously syncs team memberships
 - Removes users from teams when removed from groups
 - Updates team memberships when groups change
+
+## Troubleshooting
+
+### User provisioning issues
+
+#### Error: "User already exists in Grafana"
+
+**Cause:** The unique identifier field is not working as expected, causing conflicts during user creation.
+
+**Solution:** Test the unique identifier field to ensure it returns a single, unique user:
+
+```bash
+curl --location 'https://{$GRAFANA_URL}/apis/scim.grafana.app/v0alpha1/namespaces/{$STACK_ID}/Users?filter=userName eq "username@email.com"' \
+--header 'Authorization: Bearer glsa_xxxxxxxxxxxxxxxxxxxxxxxx'
+```
+
+The response should return exactly one user. If not, configure a different unique identifier field in your identity provider, or remove the duplicate users from Grafana.
+
+#### Error: "invalid namespace"
+
+**Cause:** The SCIM endpoint URL is incorrectly formatted.
+
+**Solution:** Verify your URL follows the correct format:
+
+```bash
+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:**
+
+1. **Check token:** Generate a new token from the Service Account details page
+2. **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.
+
+### Login issues
+
+#### 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`      | Azure AD          | `objectId`                       |
+| `userUID`      | Okta              | `user.getInternalProperty("id")` |