IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-25 18:55:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

SAML: fix pkcs8 doc and refactoring SAML docs (#47337)

Browse Source 
* refactoring: saml docs

* refactoring: relreferences

* adding error as presented in issue

* refactor: update sentence

* refactor: more relref fixes that was missing

* refactor: more relref fixes that was missing

* Apply suggestions from code review

Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com>

* refactor: move saml with okta

* fix: spell and small corrections

* add: enterprise tag

Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com>
This commit is contained in:
Eric Leijonmarck 2022-04-13 17:18:59 +01:00 committed by GitHub
parent a245531f0c
commit 17bd741fc0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 281 additions and 175 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
docs/sources/auth/_index.md
View File

@ -12,14 +12,14 @@ Here is a table showing all supported authentication providers and the features
See also, [Grafana Authentication]({{< relref "grafana.md" >}}).
| Provider | Support | Role mapping | Team sync<br> _(Enterprise only)_ | Active sync<br> _(Enterprise only)_ |
| ---------------------------------------------------------------- | :-----: | :----------: | :-------------------------------: | :---------------------------------: |
| [Auth Proxy]({{< relref "auth-proxy.md" >}}) | v2.1+ | - | v6.3+ | - |
| [Azure AD OAuth]({{< relref "azuread.md" >}}) | v6.7+ | v6.7+ | v6.7+ | - |
| [Generic OAuth]({{< relref "generic-oauth.md" >}}) | v4.0+ | v6.5+ | - | - |
| [GitHub OAuth]({{< relref "github.md" >}}) | v2.0+ | - | v6.3+ | - |
| [GitLab OAuth]({{< relref "gitlab.md" >}}) | v5.3+ | - | v6.4+ | - |
| [Google OAuth]({{< relref "google.md" >}}) | v2.0+ | - | - | - |
| [LDAP]({{< relref "ldap.md" >}}) | v2.1+ | v2.1+ | v5.3+ | v6.3+ |
| [Okta OAuth]({{< relref "okta.md" >}}) | v7.0+ | v7.0+ | v7.0+ | - |
| [SAML]({{< relref "../enterprise/saml.md" >}}) (Enterprise only) | v6.3+ | v7.0+ | v7.0+ | - |
| Provider | Support | Role mapping | Team sync<br> _(Enterprise only)_ | Active sync<br> _(Enterprise only)_ |
| -------------------------------------------------------------- | :-----: | :----------: | :-------------------------------: | :---------------------------------: |
| [Auth Proxy]({{< relref "auth-proxy.md" >}}) | v2.1+ | - | v6.3+ | - |
| [Azure AD OAuth]({{< relref "azuread.md" >}}) | v6.7+ | v6.7+ | v6.7+ | - |
| [Generic OAuth]({{< relref "generic-oauth.md" >}}) | v4.0+ | v6.5+ | - | - |
| [GitHub OAuth]({{< relref "github.md" >}}) | v2.0+ | - | v6.3+ | - |
| [GitLab OAuth]({{< relref "gitlab.md" >}}) | v5.3+ | - | v6.4+ | - |
| [Google OAuth]({{< relref "google.md" >}}) | v2.0+ | - | - | - |
| [LDAP]({{< relref "ldap.md" >}}) | v2.1+ | v2.1+ | v5.3+ | v6.3+ |
| [Okta OAuth]({{< relref "okta.md" >}}) | v7.0+ | v7.0+ | v7.0+ | - |
| [SAML]({{< relref "../enterprise/saml/" >}}) (Enterprise only) | v6.3+ | v7.0+ | v7.0+ | - |

26
docs/sources/auth/overview.md
View File

@ -8,20 +8,20 @@ weight = 1
Grafana provides many ways to authenticate users. Some authentication integrations also enable syncing user permissions and org memberships.
Here is a table showing all supported authentication providers and the features available for them. [Team sync]({{< relref "../enterprise/team-sync.md" >}}) and [active sync]({{< relref "../enterprise/enhanced_ldap.md#active-ldap-synchronization" >}}) are only available in Grafana Enterprise.
The following table shows all supported authentication providers and the features available for them. [Team sync]({{< relref "../enterprise/team-sync.md" >}}) and [active sync]({{< relref "../enterprise/enhanced_ldap.md#active-ldap-synchronization" >}}) are only available in Grafana Enterprise.
| Provider | Support | Role mapping | Team sync<br> _(Enterprise only)_ | Active sync<br> _(Enterprise only)_ |
| ---------------------------------------------------------------- | :-----: | :----------: | :-------------------------------: | :---------------------------------: |
| [Auth Proxy]({{< relref "auth-proxy.md" >}}) | v2.1+ | - | v6.3+ | - |
| [Azure AD OAuth]({{< relref "azuread.md" >}}) | v6.7+ | v6.7+ | v6.7+ | - |
| [Generic OAuth]({{< relref "generic-oauth.md" >}}) | v4.0+ | v6.5+ | - | - |
| [GitHub OAuth]({{< relref "github.md" >}}) | v2.0+ | - | v6.3+ | - |
| [GitLab OAuth]({{< relref "gitlab.md" >}}) | v5.3+ | - | v6.4+ | - |
| [Google OAuth]({{< relref "google.md" >}}) | v2.0+ | - | - | - |
| [JWT]({{< relref "jwt.md" >}}) | v8.0+ | - | - | - |
| [LDAP]({{< relref "ldap.md" >}}) | v2.1+ | v2.1+ | v5.3+ | v6.3+ |
| [Okta OAuth]({{< relref "okta.md" >}}) | v7.0+ | v7.0+ | v7.0+ | - |
| [SAML]({{< relref "../enterprise/saml.md" >}}) (Enterprise only) | v6.3+ | v7.0+ | v7.0+ | - |
| Provider | Support | Role mapping | Team sync<br> _(Enterprise only)_ | Active sync<br> _(Enterprise only)_ |
| -------------------------------------------------------------- | :-----: | :----------: | :-------------------------------: | :---------------------------------: |
| [Auth Proxy]({{< relref "auth-proxy.md" >}}) | v2.1+ | - | v6.3+ | - |
| [Azure AD OAuth]({{< relref "azuread.md" >}}) | v6.7+ | v6.7+ | v6.7+ | - |
| [Generic OAuth]({{< relref "generic-oauth.md" >}}) | v4.0+ | v6.5+ | - | - |
| [GitHub OAuth]({{< relref "github.md" >}}) | v2.0+ | - | v6.3+ | - |
| [GitLab OAuth]({{< relref "gitlab.md" >}}) | v5.3+ | - | v6.4+ | - |
| [Google OAuth]({{< relref "google.md" >}}) | v2.0+ | - | - | - |
| [JWT]({{< relref "jwt.md" >}}) | v8.0+ | - | - | - |
| [LDAP]({{< relref "ldap.md" >}}) | v2.1+ | v2.1+ | v5.3+ | v6.3+ |
| [Okta OAuth]({{< relref "okta.md" >}}) | v7.0+ | v7.0+ | v7.0+ | - |
| [SAML]({{< relref "../enterprise/saml/" >}}) (Enterprise only) | v6.3+ | v7.0+ | v7.0+ | - |
## Grafana Auth

2
docs/sources/auth/saml.md
View File

@ -10,4 +10,4 @@ weight = 1100
The SAML authentication integration allows your Grafana users to log in by using an external SAML Identity Provider (IdP). To enable this, Grafana becomes a Service Provider (SP) in the authentication flow, interacting with the IdP to exchange user information.
> SAML authentication integration is available in Grafana Cloud Pro and Advanced and in Grafana Enterprise. For more information, refer to [SAML authentication]({{< relref "../enterprise/saml.md" >}}) in [Grafana Enterprise]({{< relref "../enterprise" >}}).
> SAML authentication integration is available in Grafana Cloud Pro and Advanced and in Grafana Enterprise. For more information, refer to [SAML authentication]({{< relref "../enterprise/saml/" >}}) in [Grafana Enterprise]({{< relref "../enterprise" >}}).

4
docs/sources/enterprise/_index.md
View File

@ -29,7 +29,7 @@ Supported auth providers:
- [GitLab OAuth]({{< relref "../auth/gitlab.md#team-sync-enterprise-only" >}})
- [LDAP]({{< relref "enhanced_ldap.md#ldap-group-synchronization-for-teams" >}})
- [Okta]({{< relref "../auth/okta.md#team-sync-enterprise-only" >}})
- [SAML]({{< relref "saml.md#configure-team-sync" >}})
- [SAML]({{< relref "./saml/configure-saml.md#configure-team-sync" >}})
### Enhanced LDAP integration
@ -37,7 +37,7 @@ With Grafana Enterprise [enhanced LDAP]({{< relref "enhanced_ldap.md" >}}), you
### SAML authentication
[SAML authentication]({{< relref "saml.md" >}}) enables your Grafana Enterprise users to authenticate with SAML.
[SAML authentication]({{< relref "./saml" >}}) enables your Grafana Enterprise users to authenticate with SAML.
## Enterprise features

2
docs/sources/enterprise/auditing.md
View File

@ -122,7 +122,7 @@ pattern of the `requestUri` field is given.
\* Where `AUTH-MODULE` is the name of the authentication module: `grafana`, `saml`,
`ldap`, etc. \
\*\* Includes manual log out, token expired/revoked, and [SAML Single Logout]({{< relref "saml.md#single-logout" >}}).
\*\* Includes manual log out, token expired/revoked, and [SAML Single Logout]({{< relref "./saml/configure-saml.md#single-logout" >}}).
#### User management

15
docs/sources/enterprise/saml/_index.md Normal file
View File

@ -0,0 +1,15 @@
---
title: 'SAML authentication'
description: 'Grafana SAML authentication'
keywords: ['grafana', 'saml', 'documentation', 'saml-auth', 'enterprise']
aliases: ['/docs/grafana/latest/auth/saml/']
weight: 10
---
# SAML authentication
SAML authentication integration enables your Grafana users to log in by using an external SAML 2.0 Identity Provider (IdP). To enable this, Grafana becomes a Service Provider (SP) in the authentication flow, interacting with the IdP to exchange user information.
> Only available in Grafana Enterprise v6.3+. If you experience any issues with our implementation, contact our [Technical Support team](https://grafana.com/contact?plcmt=top-nav&cta=contactus)
{{< section >}}

74
docs/sources/enterprise/saml/about-saml.md Normal file
View File

@ -0,0 +1,74 @@
---
title: 'About SAML authentication in Grafana'
menuTitle: 'About SAML authentication'
description: 'SAML authentication'
keywords: ['grafana', 'saml', 'documentation', 'saml-auth', 'enterprise']
aliases: ['/docs/grafana/latest/auth/saml/']
weight: 20
---
# About SAML authentication
SAML authentication integration allows your Grafana users to log in by using an external SAML 2.0 Identity Provider (IdP). To enable this, Grafana becomes a Service Provider (SP) in the authentication flow, interacting with the IdP to exchange user information.
The SAML single sign-on (SSO) standard is varied and flexible. Our implementation contains a subset of features needed to provide a smooth authentication experience into Grafana.
> Only available in Grafana Enterprise v6.3+. If you encounter any problems with our implementation, please don't hesitate to contact us.
## Supported SAML
Grafana supports the following SAML 2.0 bindings:
- From the Service Provider (SP) to the Identity Provider (IdP):
- `HTTP-POST` binding
- `HTTP-Redirect` binding
- From the Identity Provider (IdP) to the Service Provider (SP):
- `HTTP-POST` binding
In terms of security:
- Grafana supports signed and encrypted assertions.
- Grafana does not support signed or encrypted requests.
In terms of initiation, Grafana supports:
- SP-initiated requests
- IdP-initiated requests
By default, SP-initiated requests are enabled. For instructions on how to enable IdP-initiated logins, see https://grafana.com/docs/grafana/latest/enterprise/saml/#idp-initiated-single-sign-on-sso.
### Edit SAML options in the Grafana config file
Once you have enabled saml, you can configure Grafana to use it for SAML authentication. Refer to [Configuration]({{< relref "../../administration/configuration.md" >}}) to get more information about how to configure Grafana.
**Edit SAML options in Grafana config file:**
1. In the `[auth.saml]` section in the Grafana configuration file, set [`enabled`]({{< relref ".././enterprise-configuration.md#enabled" >}}) to `true`.
1. Configure the [certificate and private key]({{< relref "#certificate-and-private-key" >}}).
1. On the Okta application page where you have been redirected after application created, navigate to the **Sign On** tab and find **Identity Provider metadata** link in the **Settings** section.
1. Set the [`idp_metadata_url`]({{< relref ".././enterprise-configuration.md#idp-metadata-url" >}}) to the URL obtained from the previous step. The URL should look like `https://<your-org-id>.okta.com/app/<application-id>/sso/saml/metadata`.
1. Set the following options to the attribute names configured at the **step 10** of the SAML integration setup. You can find this attributes on the **General** tab of the application page (**ATTRIBUTE STATEMENTS** and **GROUP ATTRIBUTE STATEMENTS** in the **SAML Settings** section).
- [`assertion_attribute_login`]({{< relref ".././enterprise-configuration.md#assertion-attribute-login" >}})
- [`assertion_attribute_email`]({{< relref ".././enterprise-configuration.md#assertion-attribute-email" >}})
- [`assertion_attribute_name`]({{< relref ".././enterprise-configuration.md#assertion-attribute-name" >}})
- [`assertion_attribute_groups`]({{< relref ".././enterprise-configuration.md#assertion-attribute-groups" >}})
1. Save the configuration file and and then restart the Grafana server.
When you are finished, the Grafana configuration might look like this example:
```bash
[server]
root_url = https://grafana.example.com
[auth.saml]
enabled = true
private_key_path = "/path/to/private_key.pem"
certificate_path = "/path/to/certificate.cert"
idp_metadata_url = "https://my-org.okta.com/app/my-application/sso/saml/metadata"
assertion_attribute_name = DisplayName
assertion_attribute_login = Login
assertion_attribute_email = Email
assertion_attribute_groups = Group
```

168
docs/sources/enterprise/saml.md → docs/sources/enterprise/saml/configure-saml.md
View File

@ -1,46 +1,15 @@
+++
title = "SAML Authentication"
description = "Grafana SAML Authentication"
keywords = ["grafana", "saml", "documentation", "saml-auth"]
aliases = ["/docs/grafana/latest/auth/saml/"]
weight = 900
+++
---
title: 'Configure SAML authentication in Grafana'
menuTitle: 'Configure SAML'
description: 'This contains information on how to configure SAML authentication in Grafana'
keywords: ['grafana', 'saml', 'documentation', 'saml-configuration', 'enterprise']
aliases: ['/docs/grafana/latest/auth/saml/']
weight: 40
---
# SAML authentication
# Configure SAML authentication in Grafana
SAML authentication integration allows your Grafana users to log in by using an external SAML 2.0 Identity Provider (IdP). To enable this, Grafana becomes a Service Provider (SP) in the authentication flow, interacting with the IdP to exchange user information.
The SAML single sign-on (SSO) standard is varied and flexible. Our implementation contains a subset of features needed to provide a smooth authentication experience into Grafana.
> Only available in Grafana Enterprise v6.3+. If you encounter any problems with our implementation, please don't hesitate to contact us.
## Supported SAML
Grafana supports the following SAML 2.0 bindings:
- From the Service Provider (SP) to the Identity Provider (IdP):
- `HTTP-POST` binding
- `HTTP-Redirect` binding
- From the Identity Provider (IdP) to the Service Provider (SP):
- `HTTP-POST` binding
In terms of security:
- Grafana supports signed and encrypted assertions.
- Grafana does not support signed or encrypted requests.
In terms of initiation, Grafana supports:
- SP-initiated requests
- IdP-initiated requests
By default, SP-initiated requests are enabled. For instructions on how to enable IdP-initiated logins, see https://grafana.com/docs/grafana/latest/enterprise/saml/#idp-initiated-single-sign-on-sso.
## Set up SAML authentication
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 "../administration/configuration.md#configure-with-environment-variables" >}}).
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 "../../administration/configuration.md#configure-with-environment-variables" >}}).
| Setting | Required | Description | Default |
| ---------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
@ -65,24 +34,7 @@ The table below describes all SAML configuration options. Continue reading below
| `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 | |
### Enable SAML authentication
To use the SAML integration, in the `auth.saml` section of in the Grafana custom configuration file, set `enabled` to `true`.
Refer to [Configuration]({{< relref "../administration/configuration.md" >}}) for more information about configuring Grafana.
### Certificate and private key
The SAML SSO standard uses asymmetric encryption to exchange information between the SP (Grafana) and the IdP. To perform such encryption, you need a public part and a private part. In this case, the X.509 certificate provides the public part, while the private key provides the private part.
Grafana supports two ways of specifying both the `certificate` and `private_key`.
- Without a suffix (`certificate` or `private_key`), the configuration assumes you've supplied the base64-encoded file contents.
- With the `_path` suffix (`certificate_path` or `private_key_path`), then Grafana treats the value entered as a file path and attempts to read the file from the file system.
You can only use one form of each configuration option. Using multiple forms, such as both `certificate` and `certificate_path`, results in an error.
| `role_values_grafana_admin` | No | List of comma- or space-separated roles which will be mapped into the Grafana Admin (Super Admin) role |
### Signature algorithm
@ -151,24 +103,24 @@ By default, new Grafana users using SAML authentication will have an account cre
> Team sync support for SAML only available in Grafana v7.0+
To use SAML Team sync, set [`assertion_attribute_groups`]({{< relref "./enterprise-configuration.md#assertion-attribute-groups" >}}) to the attribute name where you store user groups. Then Grafana will use attribute values extracted from SAML assertion to add user into the groups with the same name configured on the External group sync tab.
To use SAML Team sync, set [`assertion_attribute_groups`]({{< relref ".././enterprise-configuration.md#assertion-attribute-groups" >}}) to the attribute name where you store user groups. Then Grafana will use attribute values extracted from SAML assertion to add user into the groups with the same name configured on the External group sync tab.
[Learn more about Team Sync]({{< relref "../enterprise/team-sync.md" >}})
[Learn more about Team Sync]({{< relref "../../enterprise/team-sync.md" >}})
### Configure role sync
> Only available in Grafana v7.0+
Role sync allows you to map user roles from an identity provider to Grafana. To enable role sync, configure role attribute and possible values for the Editor, Admin, and Grafana Admin roles. For more information about user roles, refer to [About users and permissions]({{< relref "../administration/manage-users-and-permissions/about-users-and-permissions.md" >}}).
Role sync allows you to map user roles from an identity provider to Grafana. To enable role sync, configure role attribute and possible values for the Editor, Admin, and Grafana Admin roles. For more information about user roles, refer to [About users and permissions]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md" >}}).
1. In the configuration file, set [`assertion_attribute_role`]({{< relref "./enterprise-configuration.md#assertion-attribute-role" >}}) option to the attribute name where the role information will be extracted from.
1. Set the [`role_values_editor`]({{< relref "./enterprise-configuration.md#role-values-editor" >}}) option to the values mapped to the `Editor` role.
1. Set the [`role_values_admin`]({{< relref "./enterprise-configuration.md#role-values-admin" >}}) option to the values mapped to the organization `Admin` role.
1. Set the [`role_values_grafana_admin`]({{< relref "./enterprise-configuration.md#role-values-grafana-admin" >}}) option to the values mapped to the `Grafana Admin` role.
1. In the configuration file, set [`assertion_attribute_role`]({{< relref ".././enterprise-configuration.md#assertion-attribute-role" >}}) option to the attribute name where the role information will be extracted from.
1. Set the [`role_values_editor`]({{< relref ".././enterprise-configuration.md#role-values-editor" >}}) option to the values mapped to the `Editor` role.
1. Set the [`role_values_admin`]({{< relref ".././enterprise-configuration.md#role-values-admin" >}}) option to the values mapped to the organization `Admin` role.
1. Set the [`role_values_grafana_admin`]({{< relref ".././enterprise-configuration.md#role-values-grafana-admin" >}}) option to the values mapped to the `Grafana Admin` role.
If a user role doesn't match any of configured values, then the `Viewer` role will be assigned.
Refer to [About users and permissions]({{< relref "../administration/manage-users-and-permissions/about-users-and-permissions.md" >}}) for more information about roles and permissions in Grafana.
Refer to [About users and permissions]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md" >}}) for more information about roles and permissions in Grafana.
Example configuration:
@ -188,8 +140,8 @@ role_values_grafana_admin = superadmin
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 "./enterprise-configuration.md#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 "./enterprise-configuration.md#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. In configuration file, set [`assertion_attribute_org`]({{< relref ".././enterprise-configuration.md#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 ".././enterprise-configuration.md#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:
@ -212,7 +164,7 @@ You can use `*` as an Organization if you want all your users to be in some orga
> Only available in Grafana v7.0+
With the [`allowed_organizations`]({{< relref "./enterprise-configuration.md#allowed-organizations" >}}) option you can specify a list of organizations where the user must be a member of at least one of them to be able to log in to Grafana.
With the [`allowed_organizations`]({{< relref ".././enterprise-configuration.md#allowed-organizations" >}}) option you can specify a list of organizations where the user must be a member of at least one of them to be able to log in to Grafana.
## Example SAML configuration
@ -237,79 +189,3 @@ role_values_grafana_admin = superadmin
org_mapping = Engineering:2:Editor, Engineering:3:Viewer, Sales:3:Editor, *:1:Editor
allowed_organizations = Engineering, Sales
```
## Set up SAML with Okta
This guide will follow you through the steps of configuring SAML authentication in Grafana with [Okta](https://okta.com/). You need to be an admin in your Okta organization to access Admin Console and create SAML integration. You also need permissions to edit Grafana config file and restart Grafana server.
### Configure the SAML integration in Okta
To configure SAML integration with Okta, create integration inside the Okta organization first.
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**.
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`.
- Leave the default values for **Name ID format** and **Application username**.
- In the **ATTRIBUTE STATEMENTS (OPTIONAL)** section, enter the SAML attributes to be shared with Grafana, for example:
| Attribute name (in Grafana) | Value (in Okta profile) |
| --------------------------- | -------------------------------------- |
| Login | `user.login` |
| Email | `user.email` |
| DisplayName | `user.firstName + " " + user.lastName` |
- 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.
1. Click **Next**.
1. On the final Feedback tab, fill out the form and then click **Finish**.
### Edit SAML options in the Grafana config file
Once the application is created, configure Grafana to use it for SAML authentication. Refer to [Configuration]({{< relref "../administration/configuration.md" >}}) to get more information about how to configure Grafana.
1. In the `[auth.saml]` section in the Grafana configuration file, set [`enabled`]({{< relref "./enterprise-configuration.md#enabled" >}}) to `true`.
1. Configure the [certificate and private key]({{< relref "#certificate-and-private-key" >}}).
1. On the Okta application page where you have been redirected after application created, navigate to the **Sign On** tab and find **Identity Provider metadata** link in the **Settings** section.
1. Set the [`idp_metadata_url`]({{< relref "./enterprise-configuration.md#idp-metadata-url" >}}) to the URL obtained from the previous step. The URL should look like `https://<your-org-id>.okta.com/app/<application-id>/sso/saml/metadata`.
1. Set the following options to the attribute names configured at the **step 10** of the SAML integration setup. You can find this attributes on the **General** tab of the application page (**ATTRIBUTE STATEMENTS** and **GROUP ATTRIBUTE STATEMENTS** in the **SAML Settings** section).
- [`assertion_attribute_login`]({{< relref "./enterprise-configuration.md#assertion-attribute-login" >}})
- [`assertion_attribute_email`]({{< relref "./enterprise-configuration.md#assertion-attribute-email" >}})
- [`assertion_attribute_name`]({{< relref "./enterprise-configuration.md#assertion-attribute-name" >}})
- [`assertion_attribute_groups`]({{< relref "./enterprise-configuration.md#assertion-attribute-groups" >}})
1. Save the configuration file and and then restart the Grafana server.
When you are finished, the Grafana configuration might look like this example:
```bash
[server]
root_url = https://grafana.example.com
[auth.saml]
enabled = true
private_key_path = "/path/to/private_key.pem"
certificate_path = "/path/to/certificate.cert"
idp_metadata_url = "https://my-org.okta.com/app/my-application/sso/saml/metadata"
assertion_attribute_name = DisplayName
assertion_attribute_login = Login
assertion_attribute_email = Email
assertion_attribute_groups = Group
```
## Troubleshoot SAML authentication
To troubleshoot and get more log information, enable SAML debug logging in the configuration file. Refer to [Configuration]({{< relref "../administration/configuration.md#filters" >}}) for more information.
```bash
[log]
filters = saml.auth:debug
```

65
docs/sources/enterprise/saml/enable-saml.md Normal file
View File

@ -0,0 +1,65 @@
---
title: 'Enable SAML authentication in Grafana'
menuTitle: 'Enable SAML authentication'
description: 'This contains information to enable SAML authentication in Grafana'
keywords: ['grafana', 'saml', 'documentation', 'saml-auth', 'enterprise']
aliases: ['/docs/grafana/latest/auth/saml/']
weight: 30
---
# Enable SAML authentication in Grafana
To use the SAML integration, in the `auth.saml` section of in the Grafana custom configuration file, set `enabled` to `true`.
Refer to [Configuration]({{< relref "../../administration/configuration.md" >}}) for more information about configuring Grafana.
## Certificate and private key
The SAML SSO standard uses asymmetric encryption to exchange information between the SP (Grafana) and the IdP. To perform such encryption, you need a public part and a private part. In this case, the X.509 certificate provides the public part, while the private key provides the private part. The private key needs to be issued in a [PKCS#8](https://en.wikipedia.org/wiki/PKCS_8) format.
Grafana supports two ways of specifying both the `certificate` and `private_key`.
- Without a suffix (`certificate` or `private_key`), the configuration assumes you've supplied the base64-encoded file contents.
- With the `_path` suffix (`certificate_path` or `private_key_path`), then Grafana treats the value entered as a file path and attempts to read the file from the file system.
> **Note:** You can only use one form of each configuration option. Using multiple forms, such as both `certificate` and `certificate_path`, results in an error.
---
### **Example** of how to generate SAML credentials:
An example of how to generate a self-signed certificate and private key that's valid for one year:
```sh
$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes​
```
Base64-encode the cert.pem and key.pem files:
(-w0 switch is not needed on Mac, only for Linux)
```sh
$ base64 -w0 key.pem > key.pem.base64
$ base64 -w0 cert.pem > cert.pem.base64
```
The base64-encoded values (`key.pem.base64, cert.pem.base64` files) are then used for certificate and private_key.
The keys you provide should look like:
It should look like:
```
-----BEGIN PRIVATE KEY-----
...
...
-----END PRIVATE KEY-----
```
If you have a key that looks like:
```
-----BEGIN CERTIFICATE-----
...
...
-----END CERTIFICATE-----
```

45
docs/sources/enterprise/saml/setup-saml-with-okta.md Normal file
View File

@ -0,0 +1,45 @@
---
title: 'Setup SAML authentication with Okta in Grafana'
menuTitle: 'SAML authentication with Okta'
description: 'This is a guide to setup SAML authentication with Okta in Grafana'
keywords: ['grafana', 'saml', 'documentation', 'saml-auth', 'enterprise']
weight: 30
---
# Setup SAML with Okta
Grafana supports user authentication through Okta, which is useful when you want your users to access Grafana using single sign on. This guide will follow you through the steps of configuring SAML authentication in Grafana with [Okta](https://okta.com/). You need to be an admin in your Okta organization to access Admin Console and create SAML integration. You also need permissions to edit Grafana config file and restart Grafana server.
## Before you begin
- To configure SAML integration with Okta, create integration inside the Okta organization first. [Add integration in Okta](https://help.okta.com/en/prod/Content/Topics/Apps/apps-overview-add-apps.htm)
- Ensure you have permission to administer SAML authentication. For more information about permissions, refer to [About users and permissions]({{< relref "../manage-users-and-permissions/about-users-and-permissions.md#">}}).
**To setup SAML with Okta:**
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**.
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`.
- Leave the default values for **Name ID format** and **Application username**.
- In the **ATTRIBUTE STATEMENTS (OPTIONAL)** section, enter the SAML attributes to be shared with Grafana, for example:
| Attribute name (in Grafana) | Value (in Okta profile) |
| --------------------------- | -------------------------------------- |
| Login | `user.login` |
| Email | `user.email` |
| DisplayName | `user.firstName + " " + user.lastName` |
- 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.
1. Click **Next**.
1. On the final Feedback tab, fill out the form and then click **Finish**.

31
docs/sources/enterprise/saml/troubleshoot-saml.md Normal file
View File

@ -0,0 +1,31 @@
---
title: 'Troubleshoot SAML Authentication in Grafana'
menuTitle: 'Troubleshoot SAML Authentication'
description: 'This contains information on how to troubleshoot SAML authentication in Grafana'
keywords: ['grafana', 'saml', 'documentation', 'saml-auth', 'enterprise']
aliases: ['/docs/grafana/latest/auth/saml/']
weight: 50
---
# Troubleshoot SAML authentication in Grafana
To troubleshoot and get more log information, enable SAML debug logging in the configuration file. Refer to [Configuration]({{< relref "../../administration/configuration.md#filters" >}}) for more information.
```bash
[log]
filters = saml.auth:debug
```
## Known issues
### SAML authentication fails with error:
- `asn1: structure error: tags don't match`
We only support one private key format: PKCS#8.
The keys may be in a different format (PKCS#1 or PKCS#12); in that case, it may be necessary to convert the private key format.
```bash
$ openssl pkcs8 -topk8 -nocrypt -in <yourkey> -out private.pem
```

2
docs/sources/enterprise/team-sync.md
View File

@ -29,7 +29,7 @@ This mechanism allows Grafana to remove an existing synchronized user from a tea
- [GitLab OAuth]({{< relref "../auth/gitlab.md#team-sync-enterprise-only" >}})
- [LDAP]({{< relref "enhanced_ldap.md#ldap-group-synchronization-for-teams" >}})
- [Okta]({{< relref "../auth/okta.md#team-sync-enterprise-only" >}})
- [SAML]({{< relref "saml.md#configure-team-sync" >}})
- [SAML]({{< relref "./saml/configure-saml.md#configure-team-sync" >}})
## Synchronize a Grafana team with an external group