mirror of https://github.com/grafana/grafana
SAML: fix pkcs8 doc and refactoring SAML docs (#47337)
* 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>owensmallwood/add_cache_hits_to_query_analytics
Eric Leijonmarck
3 years ago
committed by
GitHub
parent
a245531f0c
commit
17bd741fc0
@ -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 >}} |
||||
@ -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 |
||||
``` |
||||
@ -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**. |
||||
@ -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 |
||||
``` |
||||
Loading…
Reference in new issue