From 5ecc3343db77baea2ba50e167829afb12347aaeb Mon Sep 17 00:00:00 2001
From: Misi <mgyongyosi@users.noreply.github.com>
Date: Wed, 18 Dec 2024 16:12:50 +0100
Subject: [PATCH] Docs: Add org role mapping improvements to SAML docs (#98178)

Docs: Add org role mapping improvements
---
 .../configure-authentication/saml/index.md    | 35 +++++++++++++++----
 1 file changed, 28 insertions(+), 7 deletions(-)

diff --git a/docs/sources/setup-grafana/configure-security/configure-authentication/saml/index.md b/docs/sources/setup-grafana/configure-security/configure-authentication/saml/index.md
index 230edd20cb4..57dcc15fbc4 100644
--- a/docs/sources/setup-grafana/configure-security/configure-authentication/saml/index.md
+++ b/docs/sources/setup-grafana/configure-security/configure-authentication/saml/index.md
@@ -98,7 +98,7 @@ Related links:
 
 When you are finished, the Grafana configuration might look like this example:
 
-```bash
+```ini
 [server]
 root_url = https://grafana.example.com
 
@@ -498,16 +498,37 @@ skip_org_role_sync = true
 Organization mapping allows you to assign users to particular organization in Grafana depending on attribute value obtained from identity provider.
 
 1. In configuration file, set [`assertion_attribute_org`]({{< relref "../../../configure-grafana/enterprise-configuration#assertion_attribute_org" >}}) to the attribute name you store organization info in. This attribute can be an array if you want a user to be in multiple organizations.
-1. Set [`org_mapping`]({{< relref "../../../configure-grafana/enterprise-configuration#org_mapping" >}}) option to the comma-separated list of `Organization:OrgId` pairs to map organization from IdP to Grafana organization specified by id. If you want users to have different roles in multiple organizations, you can set this option to a comma-separated list of `Organization:OrgId:Role` mappings.
+1. Set [`org_mapping`]({{< relref "../../../configure-grafana/enterprise-configuration#org_mapping" >}}) option to the comma-separated list of `Organization:OrgId` pairs to map organization from IdP to Grafana organization specified by ID. If you want users to have different roles in multiple organizations, you can set this option to a comma-separated list of `Organization:OrgId:Role` mappings.
 
-For example, use following configuration to assign users from `Engineering` organization to the Grafana organization with id `2` as Editor and users from `Sales` - to the org with id `3` as Admin, based on `Org` assertion attribute value:
+For example, use following configuration to assign users from `Engineering` organization to the Grafana organization with ID `2` as Editor and users from `Sales` - to the org with ID `3` as Admin, based on `Org` assertion attribute value:
 
-```bash
+```ini
 [auth.saml]
 assertion_attribute_org = Org
 org_mapping = Engineering:2:Editor, Sales:3:Admin
 ```
 
+Starting from Grafana version 11.5, you can use the organization name instead of the organization ID in the `org_mapping` option. Ensure that the organization name you configure matches exactly with the organization name in Grafana, as it is case-sensitive. If the organization name is not found in Grafana, the mapping will be ignored. If the external organization or the organization name contains spaces, use the JSON syntax for the `org_mapping` option:
+
+```ini
+org_mapping = ["Org 1:2:Editor", "ExternalOrg:ACME Corp.:Admin"]
+```
+
+If one of the mappings contains a `:`, use the JSON syntax and escape the `:` with a backslash:
+
+```ini
+# Assign users from "External:Admin" to the organization with name "ACME Corp" as Admin
+org_mapping = ["External\:Admin:ACME Corp:Admin"]
+```
+
+For example, to assign users from `Engineering` organization to the Grafana organization with name `ACME Corp` as Editor and users from `Sales` - to the org with id `3` as Admin, based on `Org` assertion attribute value:
+
+```ini
+[auth.saml]
+assertion_attribute_org = Org
+org_mapping = ["Engineering:ACME Corp:Editor", "Sales:3:Admin"]
+```
+
 You can specify multiple organizations both for the IdP and Grafana:
 
 - `org_mapping = Engineering:2, Sales:2` to map users from `Engineering` and `Sales` to `2` in Grafana.
@@ -534,7 +555,7 @@ allowed_organizations = ["org 1", "second org"]
 
 ### Example SAML configuration
 
-```bash
+```ini
 [auth.saml]
 enabled = true
 auto_login = false
@@ -596,7 +617,7 @@ Go to [Terraform Registry](https://registry.terraform.io/providers/grafana/grafa
 
 To troubleshoot and get more log information, enable SAML debug logging in the configuration file. Refer to [Configuration]({{< relref "../../../configure-grafana#filters" >}}) for more information.
 
-```bash
+```ini
 [log]
 filters = saml.auth:debug
 ```
@@ -654,7 +675,7 @@ To solve this issue, you can configure either the [`csrf_trusted_origins`]({{< r
 
 Example of a configuration file:
 
-```bash
+```ini
 # config.ini
 ...
 [security]