Grafana文档

设置

配置安全

配置身份验证

配置SAML认证

在Grafana中配置SAML身份验证

SAML身份验证集成允许您的Grafana用户使用外部SAML 2.0身份提供程序(IdP)进行登录。为了实现这一点，Grafana成为身份验证流中的服务提供者(Service Provider, SP)，与IdP交互以交换用户信息。

SAML单点登录(SSO)标准是多种多样且灵活的。我们的实现包含了为Grafana提供平滑身份验证体验所需的特性子集。

注意:可以在Grafana企业而且Grafana云专业和高级．

支持SAML

Grafana支持以下SAML 2.0绑定:

从服务提供者(SP)到身份提供者(IdP):
- http - post绑定
- http重定向绑定
从身份提供者(IdP)到服务提供者(SP):
- http - post绑定

在安全方面:

Grafana支持签名和加密断言。
Grafana不支持签名或加密请求。

在启动方面，Grafana支持:

SP-initiated请求
IdP-initiated请求

缺省情况下，启用sp发起的请求。有关如何启用idp发起的登录的说明，请参见idp发起的单点登录．

在Grafana配置文件中编辑SAML选项

在(auth.saml)节中的配置文件，设置启用来真正的．
配置证书及私钥．
在应用程序创建后被重定向的Okta应用程序页面上，导航到上签字标签查找身份提供者元数据链接到设置部分。
设置idp_metadata_url到从上一步获得的URL。URL应该如下所示https:// < your-org-id > .okta.com/app/ <应用程序id > / sso / saml /元数据．
将以下选项设置为在第十步SAML集成设置。属性上可以找到此属性一般应用程序页面的选项卡(属性声明而且组属性语句在SAML设置部分)。
保存配置文件，然后重新启动Grafana服务器。

当你完成后，Grafana配置可能看起来像这样:

[server] root_url = https://grafana.example.com [auth.]Saml] enabled = true private_key_path = "/path/to/private_key. "Pem " certificate_path = "/path/to/certificate. Pem " certificate_path = "/path/to/certificate. Pem " certificate_path = "cert" idp_metadata_url = "https://my-org.okta.com/app/my-application/sso/saml/metadata" assertion_attribute_name = DisplayName assertion_attribute_login =登录assertion_attribute_email =电子邮件assertion_attribute_groups =组

在Grafana中启用SAML身份验证

中使用SAML集成auth.saml节中的自定义配置文件，设置启用来真正的．

指配置有关配置Grafana的更多信息。

证书及私钥

SAML SSO标准使用非对称加密在SP (Grafana)和IdP之间交换信息。要执行这种加密，您需要一个公共部分和一个私有部分。在本例中，X.509证书提供公共部分，而私钥提供私有部分。私钥需要在PKCS # 8格式。

属性的两种指定方式证书而且private_key．

没有后缀(证书或private_key)，配置假设您已经提供了base64编码的文件内容。
与_path后缀(certificate_path或private_key_path)，然后Grafana将输入的值视为文件路径，并尝试从文件系统读取该文件。

注意:每个配置选项只能使用一种形式。使用多种形式，比如两者都用证书而且certificate_path，将导致错误。

例子如何生成SAML凭证:

以生成有效期为一年的自签名证书和私钥为例:

$ openssl req -x509 -newkey rsa:4096 -keyout密钥。Pem -out cert.pem -days 365 -nodes

对cert.pem和密钥进行base64编码。pem文件:(在Mac上不需要-w0开关，仅适用于Linux)

$ base64 -w0键。Pem > key.pem。Base64 $ Base64 -w0 cert.pem > cert.pem. Base64

base64编码的值(key.pem。base64, cert.pem.base64文件)然后用于证书和private_key。

您提供的键应该如下所示:

-----开始私钥----- ... ...-----结束私钥-----

使用Okta设置SAML

Grafana支持通过Okta进行用户身份验证，这在您希望用户使用单点登录访问Grafana时非常有用。本指南将跟随您完成在Grafana中配置SAML身份验证的步骤Okta．您需要是Okta组织中的管理员才能访问admin Console并创建SAML集成。您还需要编辑Grafana配置文件和重新启动Grafana服务器的权限。

在开始之前:

要配置与Okta的SAML集成，首先要在Okta组织内部创建集成。在Okta中添加集成
确保您拥有管理SAML身份验证的权限。有关Grafana中的角色和权限的更多信息，请参阅角色和权限．

使用Okta建立SAML:

登录Okta门户．
通过单击进入Okta组织中的管理控制台管理在右上角。如果您在开发人员控制台，则单击开发人员控制台在左上角，单击经典的UI切换到管理控制台。
在管理控制台中，导航到应用程序>应用程序．
点击添加应用程序．
点击创建新应用启动应用程序集成向导。
选择网络作为一个平台。
选择SAML 2.0在登录方法部分中。
点击创建．
在一般设置选项卡，输入您的Grafana集成的名称。您也可以上传一个logo。

在配置SAML选项卡，输入与你的Grafana实例相关的SAML信息:

在URL单点登录字段，使用saml / acs例如，您的Grafana实例的端点URL，https://grafana.example.com/saml/acs．
在受众URI (SP实体ID)字段，使用saml /元数据例如端点URL，https://grafana.example.com/saml/metadata．
保持默认值为名称ID格式而且应用程序的用户名．

在属性语句(可选)节，输入与Grafana共享的SAML属性，例如:

属性名(在Grafana中)	值(在Okta配置文件中)
登录	`user.login`
电子邮件	`user.email`
DisplayName	`用户。firstName + " " + user.lastName`

在组属性语句(可选)部分，输入组属性名(例如，集团)，并设置filter为匹配正则表达式*返回所有用户组。

点击下一个．
在最后的Feedback选项卡上，填写表单，然后单击完成．

在Grafana中配置SAML身份验证

下表描述了所有SAML配置选项。继续阅读下面的具体选项。与任何其他Grafana配置一样，您可以将这些选项应用为环境变量．

设置	要求	描述	默认的
`启用`	没有	是否允许SAML认证	`假`
`single_logout`	没有	是否启用SAML Single Logout	`假`
`allow_sign_up`	没有	是否允许通过SAML登录创建新的Grafana用户。如果设置为`假`，则只有现有的Grafana用户才能使用SAML登录。	`真正的`
`allow_idp_initiated`	没有	是否允许SAML idp发起登录	`假`
`证书`或`certificate_path`	是的	SP X.509证书的base64编码字符串或路径
`private_key`或`private_key_path`	是的	SP私钥的base64编码字符串或路径
`signature_algorithm`	没有	用于向IdP签名请求的签名算法。支持的取值为:rsa-sha1、rsa-sha256、rsa-sha512。
`idp_metadata`，`idp_metadata_path`,或`idp_metadata_url`	是的	IdP SAML元数据XML的base64编码字符串、路径或URL
`max_issue_delay`	没有	持续时间，因为IdP发出响应，允许SP处理它	`90年代`
`metadata_valid_duration`	没有	持续时间，SP元数据有效的时间	`48小时`
`relay_state`	没有	idp发起登录的中继状态。IdP中应配置匹配中继状态吗
`assertion_attribute_name`	没有	友好的名称或SAML断言中用作用户名的属性的名称。或者，这可以是一个包含与SAML断言中的属性名称匹配的变量的模板。	`displayName`
`assertion_attribute_login`	没有	友好的名称或SAML断言中用作用户登录句柄的属性的名称	`邮件`
`assertion_attribute_email`	没有	友好的名称或SAML断言中用作用户电子邮件的属性的名称	`邮件`
`assertion_attribute_groups`	没有	友好的名称或SAML断言中用作用户组的属性的名称
`assertion_attribute_role`	没有	友好的名称或SAML断言中用作用户角色的属性的名称
`assertion_attribute_org`	没有	友好的名称或SAML断言中用作用户组织的属性的名称
`allowed_organizations`	没有	以逗号或空格分隔的组织的列表。用户必须是至少一个组织的成员才能登录。
`org_mapping`	没有	以逗号或空格分隔的组织:OrgId:角色映射的列表。组织可以是`＊`即“所有用户”。Role为可选参数，取值包括:`查看器`，`编辑器`或`管理`．
`role_values_editor`	没有	将映射到Editor角色的以逗号或空格分隔的角色列表
`role_values_admin`	没有	将映射到Admin角色的以逗号或空格分隔的角色列表
`role_values_grafana_admin`	没有	用逗号或空格分隔的角色列表，这些角色将映射到Grafana Admin(超级管理员)角色

签名算法

注意:在Grafana版本7.3及更高版本中可用。

SAML标准建议对某些类型的消息(如身份验证或注销请求)使用数字签名。如果signature_algorithm选项配置后，Grafana将把数字签名放入SAML请求。支持的签名类型包括rsa-sha1，rsa-sha256，rsa-sha512．此选项应与您的IdP配置匹配，否则签名验证将失败。Grafana使用配置的密钥和证书private_key而且证书签名SAML请求的选项。

国内流离失所者的元数据

您还需要为消息验证定义IdP的公共部分。SAML IdP元数据XML定义了Grafana在何处以及如何交换用户信息。

Grafana支持三种指定IdP元数据的方式。

没有后缀idp_metadata， Grafana假设base64编码的XML文件内容。
与_path后缀，Grafana假设一个文件路径，并尝试从文件系统读取文件。
与_url后缀，Grafana假设一个URL，并尝试从给定的位置加载元数据。

最大发行延迟

防止SAML响应重放攻击和SP (Grafana)和IdP之间的内部时钟倾斜。您可以设置IdP发出响应和SP (Grafana)处理响应之间的最大时间。

配置选项指定为持续时间，例如Max_issue_delay = 90s或Max_issue_delay = 1h．

元数据有效期

SP元数据可能在某个时点过期，可能是由于证书轮换或位置绑定的更改。Grafana允许您指定元数据的有效期。利用validUntil字段时，您可以告诉消费者您的元数据何时有效。持续时间的计算方法是将持续时间与当前时间相加。

配置选项指定为持续时间，例如Metadata_valid_duration = 48h．

身份提供者(IdP)注册

为了使SAML集成正确工作，您需要让IdP知道SP。

作为Grafana的一部分，集成提供了两个关键端点:

的saml /元数据端点，其中包含SP元数据。您可以手动下载并上传它，也可以直接从端点发出IdP请求。一些提供者将其命名为标识符或实体ID。
的saml / acs端点，用于接收ACS(断言客户服务)回调。一些提供者将其命名为SSO URL或Reply URL。

idp发起的单点登录

注意:在Grafana版本7.3及更高版本中可用。

默认情况下，Grafana只允许服务提供者(SP)发起的登录(当用户通过Grafana的登录页面使用SAML登录时)。如果希望用户直接从标识提供程序(IdP)登录到Grafana，请设置allow_idp_initiated配置选项真正的和配置relay_state与IdP配置中指定的值相同。

idp发起的SSO存在一些安全风险，因此在启用此特性之前，请确保了解这些风险。当使用idp发起的SSO时，Grafana会收到未经请求的SAML请求，并且无法验证登录流是由用户启动的。这使得很难检测SAML消息是否被窃取或替换。因此，idp发起的SSO容易受到跨站登录请求伪造(CSRF)和中间人(MITM)攻击。我们不建议使用idp发起的SSO并尽可能禁用它。

单注销

注意:在Grafana版本7.3及更高版本中可用。

SAML的单次注销功能允许用户从与通过SAML SSO建立的当前IdP会话相关联的所有应用程序中注销。如果single_logout选项设置为真正的当用户退出时，Grafana请求IdP结束用户会话，从而触发用户使用相同IdP会话登录的所有其他应用程序的注销(应用程序应该支持单次注销)。相反，如果连接到同一个IdP的另一个应用程序使用一次登出退出，Grafana将接收来自IdP的登出请求并结束用户会话。

http重定向而且http - post绑定支持单次登出。当使用http重定向绑定查询应该包括请求签名。

断言映射

在SAML SSO认证流程中，Grafana接收ACS回调。回调包含SAML响应中嵌入的经过身份验证的用户的所有相关信息。Grafana解析响应以在其内部数据库中创建(或更新)用户。

为了映射用户信息，Grafana会查看断言中的各个属性。您可以将这些属性看作键/值对(尽管它们包含的信息不止这些)。

Grafana提供了配置选项，允许您修改要查看哪些键以获取这些值。在Grafana中创建用户需要的数据是Name、Login handle和email。

的`assertion_attribute_name`选项

assertion_attribute_name是一个特殊的断言映射，它可以是一个简单的键，表示映射到SAML响应上的单个断言属性，也可以是一个复杂的模板，其中包含使用美元__saml{<属性>}语法。如果该属性配置错误，Grafana将在启动时记录错误消息并禁止SAML登录。如果SAML响应中缺少模板中的变量，Grafana还将在尝试登录后记录错误。

例子

#普通字符串映射assertion_attribute_name = displayName

#模板映射assertion_attribute_name = $__saml{firstName} $__saml{lastName}

允许新用户注册

默认情况下，使用SAML身份验证的新Grafana用户将自动为他们创建一个帐户。要分离身份验证和帐户创建，并确保只有拥有现有帐户的用户才能使用SAML登录，请设置allow_sign_up选项为false。

配置团队同步

注意:在Grafana 7.0及更高版本中提供了对SAML的团队同步支持。

要使用SAML团队同步，请设置assertion_attribute_groups到存储用户组的属性名。然后，Grafana将使用从SAML断言提取的属性值，将用户添加到外部组同步选项卡上配置的同名的组中。

了解更多关于Team Sync的信息

配置角色同步

注意:在Grafana 7.0及更高版本中可用。

角色同步允许您将用户角色从标识提供者映射到Grafana。若要启用角色同步，请配置Editor、Admin和Grafana Admin角色的角色属性和可能的值。有关用户角色的更多信息，请参见角色和权限．

在配置文件中，设置assertion_attribute_role选项设置为将从中提取角色信息的属性名。
设置role_values_editor属性映射到编辑器的角色。
设置role_values_admin选项映射到组织的值管理的角色。
设置role_values_grafana_admin属性映射到Grafana管理的角色。

如果用户角色不匹配任何配置的值，则查看器角色将被分配。

有关Grafana中的角色和权限的更多信息，请参阅角色和权限．

示例配置:

(auth.saml)assertion_attribute_role= role role_values_editor = editor, developer role_values_admin = admin, operator role_values_grafana_admin = superadmin

重要的:配置角色同步后，在Grafana中手动修改的用户角色和组织成员将在下次用户登录时被覆盖。在IdP中分配用户组织和角色。

注意:在Grafana版本9.2及更高版本中可用。

如果不希望用户组织和角色与IdP同步，可以使用skip_org_role_sync配置选项。

示例配置:

(auth.saml)skip_org_role_sync= true

配置组织映射

注意:在Grafana 7.0及更高版本中可用。

组织映射允许您根据从标识提供程序获得的属性值将用户分配到Grafana中的特定组织。

在配置文件中设置assertion_attribute_org到存储组织信息的属性名。如果希望某个用户属于多个组织，则此属性可以是一个数组。
集org_mapping的逗号分隔列表中的组织:OrgId将组织从IdP映射到由id指定的Grafana组织。如果希望用户在多个组织中具有不同的角色，则可以将此选项设置为逗号分隔的列表组织:OrgId:角色映射。

例如，使用以下配置分配用户工程组织到带有id的Grafana组织2作为编辑器和用户销售-到带有id的组织3.作为管理员，基于Org断言属性值:

(auth.saml)assertion_attribute_org= Org org_mapping = Engineering:2:Editor, Sales:3:Admin

你可以为IdP和Grafana指定多个组织:

org_mapping =工程:2，销售:2将用户映射到工程而且销售来2在Grafana。
org_mapping =工程:2，工程:3分配工程两个2而且3.在Grafana。

你可以使用＊作为SAML组织，如果你想让你所有的用户都在一些默认角色的Grafana组织中:

org_mapping = *:2:编辑器将所有用户映射到2在Grafana担任编辑。

注意:在Grafana版本9.2及更高版本中可用。

你可以使用＊如果您希望将来自给定SAML组织的所有用户添加到所有现有的Grafana组织，则将Grafana组织作为映射中的Grafana组织。

org_mapping = Engineering:*将用户映射到工程所有现存的Grafana组织。
org_mapping = Administration:*:Admin将用户映射到政府所有现有的Grafana组织的管理员。

配置允许的组织

注意:在Grafana 7.0及更高版本中可用。

与allowed_organizations选项，您可以指定一个组织列表，其中用户必须是其中至少一个组织的成员才能登录到Grafana。

SAML配置示例

(auth.saml)启用= true certificate_path = "/path/to/certificate.cert" private_key_path = "/path/to/private_key.pem" idp_metadata_path = "/my/metadata.xml" max_issue_delay = 90s metadata_valid_duration = 48h assertion_attribute_name = displayName assertion_attribute_login = mail assertion_attribute_email = mail assertion_attribute_groups = Group assertion_attribute_role = Role assertion_attribute_org = Org role_values_editor = editor, developer role_values_admin = admin, operator role_values_grafana_admin = superadmin org_mapping = Engineering:2:Editor, Engineering:3:Viewer, Sales:3:Editor, *:1:Editor allowed_organizations = Engineering, Sales

在Grafana中解决SAML身份验证问题

要排除故障并获取更多日志信息，请在配置文件中启用SAML调试日志记录。指配置获取更多信息。

[log] filters = saml.auth:debug

故障排除

以下是在Grafana中配置SAML身份验证时发现的常见问题以及如何解决这些问题。

SAML身份验证失败，出现错误:

Asn1:结构错误:标签不匹配

我们只支持一种私钥格式:PKCS#8。

密钥可以是不同的格式(PKCS#1或PKCS#12);在这种情况下，可能需要转换私钥格式。

下面的命令创建一个pkcs8密钥文件。

$ openssl req -x509 -newkey rsa:4096 -keyout密钥。Pem -out cert.pem -days 365 -nodes

转换私钥格式为base64

下面的命令将键转换为base64格式。

对cert.pem和密钥进行base64编码。pem文件:(在Mac上不需要-w0开关，仅适用于Linux)

$ base64 -w0键。Pem > key.pem。Base64 $ Base64 -w0 cert.pem > cert.pem. Base64

base64编码的值(key.pem。base64, cert.pem.base64文件)然后用于证书和private_key。

您提供的键应该如下所示:

-----开始私钥----- ... ...-----结束私钥-----

当用户使用SAML登录并显示“不允许起源”时，用户可能是从IdP(身份提供程序)服务发出登录，或者用户位于反向代理的后面。这可能发生在Grafana的CSRF检查认为请求无效时。欲了解更多信息CSRF．

要解决此问题，可以配置csrf_trusted_origins或csrf_additional_headersSAML配置中的选项。

配置文件示例:

# config.ini…[security] csrf_trusted_origins = https://grafana.example.com csrf_additional_headers = X-Forwarded-Host…

从不是Grafana服务器根URL的URL访问Grafana登录页面会导致实例返回以下错误:“登录会话已过期”。

如果您通过代理服务器访问grafana，请确保cookie被正确地重写到grafana的根URL。cookie必须设置在与root_urlGrafana。这通常是反向代理的域/地址。

检查代理服务器配置中的cookie设置，以确保cookie没有被丢弃

查看你的grafana配置中的以下设置:

[security] cookie_samesite = none

该设置应该设置为none，以允许grafana会话cookie正确地使用重定向。

[security] cookie_secure = true

确保cookie_secure设置为true，以确保cookie仅通过HTTPS发送。

这个页面有用吗?

建议编辑

为文档做贡献

报告问题

在Grafana中配置SAML身份验证

支持SAML

在Grafana配置文件中编辑SAML选项

在Grafana中启用SAML身份验证

证书及私钥

例子如何生成SAML凭证:

使用Okta设置SAML

在Grafana中配置SAML身份验证

签名算法

国内流离失所者的元数据

最大发行延迟

元数据有效期

身份提供者(IdP)注册

idp发起的单点登录

单注销

断言映射

的assertion_attribute_name选项

允许新用户注册

配置团队同步

配置角色同步

配置组织映射

配置允许的组织

SAML配置示例

在Grafana中解决SAML身份验证问题

故障排除

SAML身份验证失败，出现错误:

转换私钥格式为base64

SAML登录尝试失败，请求响应“不允许起源”

SAML登录尝试失败，请求响应“登录会话已过期”

这个页面有用吗?

相关的文档

相关资源来自Grafana实验室bob电竞频道

的`assertion_attribute_name`选项