public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

SCIM: Update docs with the reject_non_provisioned_users flag (#108657)

Browse Source 
* update docs with the reject_non_provisioned_users flag

* update docs with new flag and new create user behaviour

* address feedback

* run prettier
This commit is contained in:
Mihai Doarna
2025-07-28 11:32:14 +03:00
committed by GitHub
parent f9b34baa35
commit cef7f2b337
2 changed files with 10 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/setup-grafana/configure-security/configure-scim-provisioning/_index.md
+7 -13
View File
@@ -50,7 +50,7 @@ Always verify that your SAML identity provider is configured to send a stable, u
## Benefits
{{< admonition type="note" >}}
SCIM provisioning only works SAML authentication.
SCIM provisioning only works with SAML authentication.
Other authentication methods aren't supported.
{{< /admonition >}}
@@ -67,25 +67,19 @@ When you enable SCIM in Grafana, the following requirements and restrictions app
1. **Use the same identity provider for user provisioning and for authentication flow**: You must use the same identity provider for both authentication and user provisioning.
2. **Authentication restrictions**:
- Users attempting to log in through other methods (LDAP, OAuth) will be blocked
- By default, users who are not provisioned through SCIM cannot access Grafana
3. **Security restriction**: When using SAML, the login authentication flow requires the SAML assertion exchange between the Identity Provider and Grafana to include the `userUID` SAML assertion with the user's unique identifier at the Identity Provider.
2. **Security restriction**: When using SAML, the login authentication flow requires the SAML assertion exchange between the Identity Provider and Grafana to include the `userUID` SAML assertion with the user's unique identifier at the Identity Provider.
- Configure `userUID` SAML assertion in [Azure AD](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-authentication/saml/configure-saml-with-azuread/#configure-saml-assertions-when-using-scim-provisioning)
- Configure `userUID` SAML assertion in [Okta](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-authentication/saml/configure-saml-with-okta/#configure-saml-assertions-when-using-scim-provisioning)
4. **Exceptions**: Users with Basic Auth credentials and those using their Grafana Cloud accounts can still log in regardless of these restrictions.
## Configure SCIM in Grafana
The table below describes all SCIM configuration options. Like any other Grafana configuration, you can apply these options as [environment variables](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#override-configuration-with-environment-variables).
| 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` |
| `allow_non_provisioned_users` | No | Allow non SCIM provisioned users to sign in to Grafana. | `false` |
| 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` |
{{< admonition type="warning" >}}
**Team Sync Compatibility**:
docs/sources/setup-grafana/configure-security/configure-scim-provisioning/manage-users-teams/_index.md
+3 -22
View File
@@ -63,7 +63,7 @@ SCIM uses a specific process to establish and maintain user identity between the
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
- **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
@@ -79,10 +79,6 @@ This process ensures secure and consistent user identification across both syste
### Existing Grafana users
{{< admonition type="note" >}}
Existing users must be assigned to the Grafana app in the identity provider to maintain access once SCIM is enabled.
{{< /admonition >}}
For users who already exist in the Grafana instance:
- SCIM establishes the relationship through the External ID matching process
@@ -147,13 +143,11 @@ The migration process uses the same [user identification mechanism](#how-scim-id
- 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.
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]
allow_non_provisioned_users = true
reject_non_provisioned_users = true
```
{{< /admonition >}}
@@ -282,19 +276,6 @@ Team membership maintenance:
### 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.