SCIM: Backport 105026 to 12.0.1 (#105340)

Backport 105026 to 12.0.1
2025-05-13 12:29:17 -04:00
parent 2e6b7bf74a
commit a1c1523a41
5 changed files with 73 additions and 6 deletions
@@ -436,6 +436,37 @@ assertion_attribute_name = $__saml{firstName} $__saml{lastName}

 By default, new Grafana users using SAML authentication will have an account created for them automatically. To decouple authentication and account creation and ensure only users with existing accounts can log in with SAML, set the `allow_sign_up` option to false.

+## Integrating with SCIM Provisioning
+
+If you are also using SCIM provisioning for this Grafana application in Azure AD, it's crucial to align the user identifiers between SAML and SCIM for seamless operation. The unique identifier that links the SAML user to the SCIM provisioned user is determined by the `assertion_attribute_external_uid` setting in the Grafana SAML configuration. This `assertion_attribute_external_uid` should correspond to the `externalId` used in SCIM provisioning (typically set to the Azure AD `user.objectid`).
+
+1.  **Ensure Consistent Identifier in SAML Assertion:**
+
+    - The unique identifier from Azure AD (typically `user.objectid`) that you mapped to the `externalId` attribute in Grafana in your SCIM provisioning setup **must also be sent as a claim in the SAML assertion.** For more details on SCIM, refer to the [SCIM provisioning documentation](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-scim-provisioning/).
+    - In the Azure AD Enterprise Application, under **Single sign-on** > **Attributes & Claims**, ensure you add a claim that provides this identifier. For example, you might add a claim named `UserID` (or similar, like `externalId`) that sources its value from `user.objectid`.
+
+2.  **Configure Grafana SAML Settings for SCIM:**
+
+    - In the `[auth.saml]` section of your Grafana configuration, set `assertion_attribute_external_uid` to the name of the SAML claim you configured in the previous step (e.g., `userUID` or the full URI like `http://schemas.microsoft.com/identity/claims/objectidentifier` if that's how Azure AD sends it).
+    - The `assertion_attribute_login` setting should still be configured to map to the attribute your users will log in with (e.g., `userPrincipalName`, `mail`).
+
+    _Example Grafana Configuration:_
+
+    ```ini
+    [auth.saml]
+    # ... other SAML settings ...
+    assertion_attribute_login = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier # Or other login attribute
+    assertion_attribute_external_uid = http://schemas.microsoft.com/identity/claims/objectidentifier # Or your custom claim name for user.objectid
+    ```
+
+    Ensure that the value specified in `assertion_attribute_external_uid` precisely matches the name of the claim as it's sent in the SAML assertion from Azure AD.
+
+3.  **SCIM Linking Identifier and Azure AD:**
+    - By default (if `assertion_attribute_external_uid` is not set), Grafana uses the `userUID` attribute from the SAML assertion for SCIM linking.
+    - **Recommended for Azure AD:** For SCIM integration with Azure AD, it is necessary to:
+      1.  Ensure Azure AD sends the `user.objectid` in a claim.
+      2.  Either set this claim name in Azure AD to `userUID`, or, if you want to use a different claim name, set `assertion_attribute_external_uid` in Grafana to match the claim name you chose in Azure AD.
+
 ### Configure automatic login

 Set the `auto_login` option to true to attempt login automatically, skipping the login screen.
@@ -30,6 +30,18 @@ You can enable feature toggles through configuration file or environment variabl
 For more information, refer to the [feature toggles documentation](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#feature_toggles).
 {{< /admonition >}}

+{{< admonition type="warning" title="Critical: Aligning SAML Identifier with SCIM externalId" >}}
+When using SAML for authentication alongside SCIM provisioning, a critical security measure is to ensure proper alignment between the the SCIM user's `externalId` and the SAML user identifier. The unique identifier used for SCIM provisioning (which becomes the `externalId` in Grafana, often sourced from a stable IdP attribute like Azure AD's `user.objectid`) **must also be sent as a claim in the SAML assertion from your Identity Provider.**
+Furthermore, the Grafana SAML configuration must be correctly set up to identify and use this specific claim for linking the authenticated SAML user to their SCIM-provisioned user. This can be achieved by either ensuring the primary SAML login identifier by using the `assertion_attribute_external_uid` setting in Grafana to explicitly set the name of the SAML claim that contains the stable unique identifier attribute.
+
+**Why is this important?**
+A mismatch or inconsistent mapping between this SAML login identifier and the SCIM `externalId` creates a critical security vulnerability. If these two identifiers are not reliably and uniquely aligned for each individual user, Grafana may fail to correctly link an authenticated SAML session to the intended SCIM-provisioned user profile and its associated permissions. This can enable a malicious actor to impersonate another user—for instance, by crafting a SAML assertion that, due to the identifier misalignment, incorrectly grants them the access rights of the targeted user.
+
+Grafana relies on this linkage to correctly associate the authenticated user from SAML with the provisioned user from SCIM. Failure to ensure a consistent and unique identifier across both systems can break this linkage, leading to incorrect user mapping and potential unauthorized access.
+
+Always verify that your SAML identity provider is configured to send a stable, unique user identifier that your SCIM configuration maps to `externalId`. Refer to your identity provider's documentation and the specific Grafana SCIM integration guides (e.g., for [Azure AD](configure-scim-with-azuread/) or [Okta](configure-scim-with-okta/)) for detailed instructions on configuring these attributes correctly.
+{{< /admonition >}}
+
 ## Benefits

 {{< admonition type="note" >}}
@@ -33,6 +33,14 @@ You can enable feature toggles through configuration file or environment variabl
 For more information, refer to the [feature toggles documentation](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#feature_toggles).
 {{< /admonition >}}

+{{< admonition type="note" >}}
+**Important SAML and SCIM Configuration:**
+When using SAML for authentication alongside SCIM provisioning with Azure AD, 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 (../\_index.md#critical-aligning-saml-user-id-with-scim-externalid)](../_index.md#critical-aligning-saml-user-id-with-scim-externalid).
+
+Refer to the [SAML authentication with Azure AD documentation](../../configure-authentication/saml/#integrating-with-scim-provisioning) for specific instructions on how to configure SAML claims and Grafana SAML settings for your Azure AD SCIM setup.
+{{< /admonition >}}
+
 ## Prerequisites

 Before configuring SCIM with Azure AD, ensure you have:
@@ -70,24 +78,29 @@ Configure the enterprise application in Azure AD to enable automated user and te
 1. In the application overview, select **Provisioning**
 2. Click **+ New Configuration**
 3. Configure the following settings:
-   - **Tenant URL:** `https://{grafana_url}/scim`
+   - **Tenant URL:** `https://{your-grafana-domain}/apis/scim.grafana.app/v0alpha1/namespaces/stacks-{stack-id}`
+     Replace `{your-grafana-domain}` with your Grafana instance's domain (e.g., `your-stack.grafana.net` for Grafana Cloud or `grafana.yourcompany.com` for self-hosted instances). Replace `{stack-id}` with your Grafana Cloud stack ID.
   - **Secret Token:** Enter the service account token from Grafana
 4. Click **Test connection** to verify the configuration
 5. 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 Azure AD enterprise application. This is where you will define how Azure AD attributes correspond to the SCIM attributes for Grafana, including the mandatory `externalId`.
+
 {{< admonition type="note" >}}
 Only work email addresses are supported. Azure AD must be configured to use `emails[type eq "work"].value` for email mapping.
+The `externalId` attribute in Grafana is mandatory. Azure AD uses this to uniquely identify users and groups. You must map an attribute from Azure AD to the `externalId` attribute in Grafana. This Azure AD attribute must be **a stable and a unique identifier for each individual user** (for example, the `objectId` attribute in Azure AD is commonly used for this purpose).
 {{< /admonition >}}

 Configure the following required attributes:

-| Azure AD Attribute. | Grafana Attribute              |
+| Azure AD Attribute  | Grafana Attribute              |
 | ------------------- | ------------------------------ |
 | `userPrincipalName` | `userName`                     |
 | `mail`              | `emails[type eq "work"].value` |
 | `displayName`       | `displayName`                  |
+| `objectId`          | `externalId`                   |

 ### Enable provisioning

@@ -40,6 +40,14 @@ Before configuring SCIM with Okta, ensure you have:
 - [SAML authentication configured with Okta](../../configure-authentication/saml/#set-up-saml-with-okta)
 - SCIM feature enabled in Grafana

+{{< admonition type="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 (../\_index.md#critical-aligning-saml-user-id-with-scim-externalid)](../_index.md#critical-aligning-saml-user-id-with-scim-externalid).
+
+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-authentication/saml/#set-up-saml-with-okta).
+{{< /admonition >}}
+
 ## 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.
@@ -75,7 +83,7 @@ In the **Integration** tab, configure:

 - **SCIM Connector base URL:**
  ```
-  https://{resource_name}/apis/scim.grafana.app/v0alpha1/namespaces/stacks-{stack-id}
+  https://{your-grafana-domain}/apis/scim.grafana.app/v0alpha1/namespaces/stacks-{stack-id}
  ```
 - **Unique identifier field:** userName
 - **Supported provisioning actions:**
@@ -63,9 +63,12 @@ SCIM uses a specific process to establish and maintain user identity between the
   - The identity provider updates Grafana with the External ID
   - Grafana updates the authentication validations to expect this External ID

-3. Authentication validation:
-   - Grafana expects the SAML integration to return the same External ID in SAML assertions
-   - This External ID is used to validate that the logged-in user matches the provisioned user
+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.
+   - **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 Azure AD).
+   - See [SAML configuration details](../../configure-authentication/saml/#integrating-with-scim-provisioning) 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.