Docs: Extend SAML docs (improvements, assertion mapping) (#96367)
* Move the configuration options to the bottom and extend it * Improve assertion mapping docs for Okta * fix typo * Update index.md --------- Co-authored-by: Irene Rodríguez <irene.rodriguez@grafana.com>
This commit is contained in:
Misi
Irene Rodríguez
+59
-53
@@ -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` |
|
||||
|
||||
Reference in New Issue
Block a user