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 dca76450dc2..08e01f5dcc2 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 @@ -284,68 +284,31 @@ Grafana supports user authentication through Okta, which is useful when you want 1. Log in to the [Okta portal](https://login.okta.com/). 1. Go to the Admin Console in your Okta organization by clicking **Admin** in the upper-right corner. If you are in the Developer Console, then click **Developer Console** in the upper-left corner and then click **Classic UI** to switch over to the Admin Console. 1. In the Admin Console, navigate to **Applications** > **Applications**. -1. Click **Add Application**. -1. Click **Create New App** to start the Application Integration Wizard. -1. Choose **Web** as a platform. -1. Select **SAML 2.0** in the Sign on method section. +1. Click **Create App Integration** to start the Application Integration Wizard. +1. Choose **SAML 2.0** as the **Sign-in method**. 1. Click **Create**. 1. On the **General Settings** tab, enter a name for your Grafana integration. You can also upload a logo. 1. On the **Configure SAML** tab, enter the SAML information related to your Grafana instance: - In the **Single sign on URL** field, use the `/saml/acs` endpoint URL of your Grafana instance, for example, `https://grafana.example.com/saml/acs`. - - In the **Audience URI (SP Entity ID)** field, use the `/saml/metadata` endpoint URL, for example, `https://grafana.example.com/saml/metadata`. + - In the **Audience URI (SP Entity ID)** field, use the `/saml/metadata` endpoint URL, by default it is the `/saml/metadata` endpoint of your Grafana instance (for example `https://example.grafana.com/saml/metadata`). This could be configured differently, but the value here must match the `entity_id` setting of the SAML settings of Grafana. - Leave the default values for **Name ID format** and **Application username**. + {{% admonition type="note" %}} + If you plan to enable SAML Single Logout, consider setting the **Name ID format** to `EmailAddress` or `Persistent`. This must match the `name_id_format` setting of the Grafana instance. + {{% /admonition %}} - In the **ATTRIBUTE STATEMENTS (OPTIONAL)** section, enter the SAML attributes to be shared with Grafana. The attribute names in Okta need to match exactly what is defined within Grafana, for example: - | Attribute name (in Grafana) | Name and value (in Okta profile) | - | --------------------------- | -------------------------------------------------- | - | Login | Login `user.login` | - | Email | Email `user.email` | - | DisplayName | DisplayName `user.firstName + " " + user.lastName` | + | Attribute name (in Grafana) | Name and value (in Okta profile) | Grafana configuration (under `auth.saml`) | + | --------------------------- | ---------------------------------------------------- | ----------------------------------------- | + | Login | Login - `user.login` | `assertion_attribute_login = Login` | + | Email | Email - `user.email` | `assertion_attribute_email = Email` | + | DisplayName | DisplayName - `user.firstName + " " + user.lastName` | `assertion_attribute_name = DisplayName` | - - In the **GROUP ATTRIBUTE STATEMENTS (OPTIONAL)** section, enter a group attribute name (for example, `Group`) and set filter to `Matches regex .*` to return all user groups. + - In the **GROUP ATTRIBUTE STATEMENTS (OPTIONAL)** section, enter a group attribute name (for example, `Group`, ensure it matches the `asssertion_attribute_groups` setting in Grafana) and set filter to `Matches regex .*` to return all user groups. 1. Click **Next**. 1. On the final Feedback tab, fill out the form and then click **Finish**. -## Configure SAML authentication in Grafana - -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` | -| `name` | No | Name used to refer to the SAML authentication in the Grafana user interface. | `SAML` | -| `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: `None`, `Viewer`, `Editor` or `Admin`. | | -| `role_values_none` | No | List of comma- or space-separated roles which will be mapped into the None role | | -| `role_values_viewer` | No | List of comma- or space-separated roles which will be mapped into the Viewer role | | -| `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` | -| `client_id` | No | Client ID of the IdP service application used to retrieve more information about the user from the IdP. | | -| `client_secret` | No | Client secret of the IdP service application used to retrieve more information about the user from the IdP. | | -| `token_url` | No | URL to retrieve the access token from the IdP. | | -| `force_use_graph_api` | No | Whether to use the IdP service application retrieve more information about the user from the IdP. | `false` | - ### Signature algorithm 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. @@ -358,10 +321,13 @@ By default, this is set to `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` 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` +| `name_id_format` value in the configuration file or Terraform | `Name identifier format` on the UI | +| ------------------------------------------------------------- | ---------------------------------- | +| `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` | Default | +| `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified` | Unspecified | +| `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` | Email address | +| `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` | Persistent | +| `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` | Transient | ### IdP metadata @@ -721,3 +687,43 @@ cookie_secure = true ``` Ensure cookie_secure is set to true to ensure that cookies are only sent over HTTPS. + +## Configure SAML authentication in Grafana + +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` | +| `name` | No | Name used to refer to the SAML authentication in the Grafana user interface. | `SAML` | +| `entity_id` | No | The entity ID of the service provider. This is the unique identifier of the service provider. | `https://{Grafana URL}/saml/metadata` | +| `single_logout` | No | Whether SAML Single Logout is 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 | Maximum time allowed between the issuance of an AuthnRequest by the SP and the processing of the Response. | `90s` | +| `metadata_valid_duration` | No | Duration for which the SP metadata remains valid. | `48h` | +| `relay_state` | No | Relay state for IdP-initiated login. This should match the relay state configured in the 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: `None`, `Viewer`, `Editor` or `Admin`. | | +| `role_values_none` | No | List of comma- or space-separated roles which will be mapped into the None role. | | +| `role_values_viewer` | No | List of comma- or space-separated roles which will be mapped into the Viewer role. | | +| `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. | | +| `skip_org_role_sync` | No | Whether to skip organization role synchronization. | `false` | +| `name_id_format` | No | Specifies the format of the requested NameID element in the SAML AuthnRequest. | `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` | +| `client_id` | No | Client ID of the IdP service application used to retrieve more information about the user from the IdP. (Microsoft Entra ID only) | | +| `client_secret` | No | Client secret of the IdP service application used to retrieve more information about the user from the IdP. (Microsoft Entra ID only) | | +| `token_url` | No | URL to retrieve the access token from the IdP. (Microsoft Entra ID only) | | +| `force_use_graph_api` | No | Whether to use the IdP service application retrieve more information about the user from the IdP. (Microsoft Entra ID only) | `false` |