Docs: Add a reference to Terraform SCIM resource (#110290)

* Docs: Add a reference to Terraform SCIM resource * Refactor troublshooting page * Refactor troublshooting page
2025-08-28 18:33:14 +02:00
parent 8458436b61
commit 90ccc8fc5a
3 changed files with 105 additions and 49 deletions
@@ -95,8 +95,33 @@ The table below describes all SCIM configuration options. Like any other Grafana
 [auth.scim]
 user_sync_enabled = true
 group_sync_enabled = false
+reject_non_provisioned_users = false
 ```

+## Configure SCIM using Terraform
+
+You can also configure SCIM provisioning in Grafana using the [Grafana Terraform provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/scim_config). This approach is particularly useful for infrastructure-as-code deployments and automated provisioning.
+
+### Terraform SCIM configuration example
+
+```hcl
+resource "grafana_scim_config" "scim_config" {
+  user_sync_enabled            = true
+  group_sync_enabled           = false
+  reject_non_provisioned_users = false
+}
+```
+
+### Terraform SCIM configuration options
+
+The Terraform `grafana_scim_config` resource supports the same configuration options as the manual configuration:
+
+| Setting                        | Required | Description                                                                                                                                                                                | Default |
+| ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
+| `user_sync_enabled`            | Yes      | Enable SCIM user provisioning. When enabled, Grafana will create, update, and deactivate users based on SCIM requests from your identity provider.                                         | `false` |
+| `group_sync_enabled`           | No       | Enable SCIM group provisioning. When enabled, Grafana will create, update, and delete teams based on SCIM requests from your identity provider. Cannot be enabled if Team Sync is enabled. | `false` |
+| `reject_non_provisioned_users` | No       | When enabled, prevents non-SCIM provisioned users from signing in. Cloud Portal users can always sign in regardless of this setting.                                                       | `false` |
+
 ## Supported identity providers

 The following identity providers are supported:
@@ -135,5 +160,6 @@ The following table compares SCIM with other synchronization methods to help you
 ## Next steps

 - [Manage users and teams with SCIM provisioning](manage-users-teams/)
+- [Troubleshoot SCIM provisioning](troubleshooting/)
 - [Configure SCIM with Azure AD](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-scim-provisioning/configure-scim-with-azuread/)
 - [Configure SCIM with Okta](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-scim-provisioning/configure-scim-with-okta/)
@@ -272,53 +272,8 @@ Team membership maintenance:
 - Removes users from teams when removed from groups
 - Updates team memberships when groups change

-## Troubleshooting
+## Next steps

-### User provisioning issues
-
-#### 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")` |
+- [Troubleshoot SCIM provisioning](../troubleshooting/)
+- [Configure SCIM with Azure AD](../configure-scim-with-azuread/)
+- [Configure SCIM with Okta](../configure-scim-with-okta/)
@@ -0,0 +1,75 @@
+---
+description: Troubleshoot common SCIM provisioning issues in Grafana, including user provisioning, authentication, and login problems.
+keywords:
+  - grafana
+  - scim
+  - troubleshooting
+  - user-provisioning
+  - authentication
+labels:
+  products:
+    - cloud
+    - enterprise
+menuTitle: Troubleshoot SCIM
+title: Troubleshoot SCIM provisioning
+weight: 400
+---
+
+# 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:
+
+```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")` |
+
+## Next steps
+
+- [Manage users and teams with SCIM provisioning](../manage-users-teams/)
+- [Configure SCIM with Azure AD](../configure-scim-with-azuread/)
+- [Configure SCIM with Okta](../configure-scim-with-okta/)