From 49c2ac52d12342aa72e723cadeaa5334a6af2969 Mon Sep 17 00:00:00 2001 From: "Grot (@grafanabot)" <43478413+grafanabot@users.noreply.github.com> Date: Tue, 9 May 2023 14:15:18 +0100 Subject: [PATCH] [v10.0.x] Add name_id_format to doc (#67928) Add name_id_format to doc (#67803) * add name_id_format to doc * add labels * add missing pipe * add available name ID options * Update docs/sources/setup-grafana/configure-security/configure-authentication/saml/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-security/configure-authentication/saml/index.md * Apply suggestions from code review Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * lint --------- Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> (cherry picked from commit 6f4d4a67508ee98d8d5f0fa2311a6cc466a84a45) Co-authored-by: Jo --- .../configure-authentication/_index.md | 4 ++ .../configure-authentication/saml/index.md | 68 ++++++++++++------- 2 files changed, 47 insertions(+), 25 deletions(-) diff --git a/docs/sources/setup-grafana/configure-security/configure-authentication/_index.md b/docs/sources/setup-grafana/configure-security/configure-authentication/_index.md index e450af2a7bc..48205d8528e 100644 --- a/docs/sources/setup-grafana/configure-security/configure-authentication/_index.md +++ b/docs/sources/setup-grafana/configure-security/configure-authentication/_index.md @@ -10,6 +10,10 @@ cascade: - oss description: Learn about all the ways in which you can configure Grafana to authenticate users. +labels: + products: + - cloud + - enterprise title: Configure authentication weight: 100 --- 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 e3d0a6190db..16905c8f891 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 @@ -10,6 +10,10 @@ aliases: - ../../../enterprise/saml/troubleshoot-saml/ description: Learn how to configure SAML authentication in Grafana's configuration file. menuTitle: Configure SAML using the configuration file +labels: + products: + - cloud + - enterprise title: Configure SAML authentication using the configuration file weight: 1100 --- @@ -168,31 +172,32 @@ Grafana supports user authentication through Okta, which is useful when you want The table below describes all SAML configuration options. Continue reading below for details on specific options. Like any other Grafana configuration, you can apply these options as [environment variables]({{< relref "../../../configure-grafana/#override-configuration-with-environment-variables" >}}). -| Setting | Required | Description | Default | -| ---------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- | -| `enabled` | No | Whether SAML authentication is allowed | `false` | -| `single_logout` | No | Whether SAML Single Logout enabled | `false` | -| `allow_sign_up` | No | Whether to allow new Grafana user creation through SAML login. If set to `false`, then only existing Grafana users can log in with SAML. | `true` | -| `auto_login` | No | Whether SAML auto login is enabled | `false` | -| `allow_idp_initiated` | No | Whether SAML IdP-initiated login is allowed | `false` | -| `certificate` or `certificate_path` | Yes | Base64-encoded string or Path for the SP X.509 certificate | | -| `private_key` or `private_key_path` | Yes | Base64-encoded string or Path for the SP private key | | -| `signature_algorithm` | No | Signature algorithm used for signing requests to the IdP. Supported values are rsa-sha1, rsa-sha256, rsa-sha512. | | -| `idp_metadata`, `idp_metadata_path`, or `idp_metadata_url` | Yes | Base64-encoded string, Path or URL for the IdP SAML metadata XML | | -| `max_issue_delay` | No | Duration, since the IdP issued a response and the SP is allowed to process it | `90s` | -| `metadata_valid_duration` | No | Duration, for how long the SP metadata is valid | `48h` | -| `relay_state` | No | Relay state for IdP-initiated login. Should match relay state configured in IdP | | -| `assertion_attribute_name` | No | Friendly name or name of the attribute within the SAML assertion to use as the user name. Alternatively, this can be a template with variables that match the names of attributes within the SAML assertion. | `displayName` | -| `assertion_attribute_login` | No | Friendly name or name of the attribute within the SAML assertion to use as the user login handle | `mail` | -| `assertion_attribute_email` | No | Friendly name or name of the attribute within the SAML assertion to use as the user email | `mail` | -| `assertion_attribute_groups` | No | Friendly name or name of the attribute within the SAML assertion to use as the user groups | | -| `assertion_attribute_role` | No | Friendly name or name of the attribute within the SAML assertion to use as the user roles | | -| `assertion_attribute_org` | No | Friendly name or name of the attribute within the SAML assertion to use as the user organization | | -| `allowed_organizations` | No | List of comma- or space-separated organizations. User should be a member of at least one organization to log in. | | -| `org_mapping` | No | List of comma- or space-separated Organization:OrgId:Role mappings. Organization can be `*` meaning "All users". Role is optional and can have the following values: `Viewer`, `Editor` or `Admin`. | | -| `role_values_editor` | No | List of comma- or space-separated roles which will be mapped into the Editor role | | -| `role_values_admin` | No | List of comma- or space-separated roles which will be mapped into the Admin role | | -| `role_values_grafana_admin` | No | List of comma- or space-separated roles which will be mapped into the Grafana Admin (Super Admin) role | +| Setting | Required | Description | Default | +| ---------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- | +| `enabled` | No | Whether SAML authentication is allowed | `false` | +| `single_logout` | No | Whether SAML Single Logout enabled | `false` | +| `allow_sign_up` | No | Whether to allow new Grafana user creation through SAML login. If set to `false`, then only existing Grafana users can log in with SAML. | `true` | +| `auto_login` | No | Whether SAML auto login is enabled | `false` | +| `allow_idp_initiated` | No | Whether SAML IdP-initiated login is allowed | `false` | +| `certificate` or `certificate_path` | Yes | Base64-encoded string or Path for the SP X.509 certificate | | +| `private_key` or `private_key_path` | Yes | Base64-encoded string or Path for the SP private key | | +| `signature_algorithm` | No | Signature algorithm used for signing requests to the IdP. Supported values are rsa-sha1, rsa-sha256, rsa-sha512. | | +| `idp_metadata`, `idp_metadata_path`, or `idp_metadata_url` | Yes | Base64-encoded string, Path or URL for the IdP SAML metadata XML | | +| `max_issue_delay` | No | Duration, since the IdP issued a response and the SP is allowed to process it | `90s` | +| `metadata_valid_duration` | No | Duration, for how long the SP metadata is valid | `48h` | +| `relay_state` | No | Relay state for IdP-initiated login. Should match relay state configured in IdP | | +| `assertion_attribute_name` | No | Friendly name or name of the attribute within the SAML assertion to use as the user name. Alternatively, this can be a template with variables that match the names of attributes within the SAML assertion. | `displayName` | +| `assertion_attribute_login` | No | Friendly name or name of the attribute within the SAML assertion to use as the user login handle | `mail` | +| `assertion_attribute_email` | No | Friendly name or name of the attribute within the SAML assertion to use as the user email | `mail` | +| `assertion_attribute_groups` | No | Friendly name or name of the attribute within the SAML assertion to use as the user groups | | +| `assertion_attribute_role` | No | Friendly name or name of the attribute within the SAML assertion to use as the user roles | | +| `assertion_attribute_org` | No | Friendly name or name of the attribute within the SAML assertion to use as the user organization | | +| `allowed_organizations` | No | List of comma- or space-separated organizations. User should be a member of at least one organization to log in. | | +| `org_mapping` | No | List of comma- or space-separated Organization:OrgId:Role mappings. Organization can be `*` meaning "All users". Role is optional and can have the following values: `Viewer`, `Editor` or `Admin`. | | +| `role_values_editor` | No | List of comma- or space-separated roles which will be mapped into the Editor role | | +| `role_values_admin` | No | List of comma- or space-separated roles which will be mapped into the Admin role | | +| `role_values_grafana_admin` | No | List of comma- or space-separated roles which will be mapped into the Grafana Admin (Super Admin) role | | +| `name_id_format` | No | The Name ID Format to request within the SAML assertion | `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` | ### Signature algorithm @@ -200,6 +205,19 @@ The table below describes all SAML configuration options. Continue reading below The SAML standard recommends using a digital signature for some types of messages, like authentication or logout requests. If the `signature_algorithm` option is configured, Grafana will put a digital signature into SAML requests. Supported signature types are `rsa-sha1`, `rsa-sha256`, `rsa-sha512`. This option should match your IdP configuration, otherwise, signature validation will fail. Grafana uses key and certificate configured with `private_key` and `certificate` options for signing SAML requests. +### Specify user's Name ID + +The `name_id_format` configuration field specifies the format of the NameID element in the SAML assertion. + +By default, this is set to `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` and does not need to be specified in the configuration file. + +The following list includes valid configuration field values: + +- `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified` +- `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` +- `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` +- `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` + ### IdP metadata You also need to define the public part of the IdP for message verification. The SAML IdP metadata XML defines where and how Grafana exchanges user information.