配置 Okta OIDC 认证
Grafana 中提供了多种认证方法来验证用户身份。认证配置决定了哪些用户可以访问 Grafana 以及他们可以使用哪种方法登录。您还可以配置 Grafana,使其根据认证提供商集成返回的信息自动更新用户在 Grafana 中的角色和团队成员资格。
在决定认证方法时,考虑您当前的身份和访问管理系统以及所需的特定认证和授权功能非常重要。有关可用认证选项及其支持功能的完整列表,请参阅配置认证。
注意
如果用户在 Okta 中使用的电子邮件地址与其他认证提供商(例如 Grafana.com)使用的相同,您需要进行额外配置以确保用户正确匹配。有关更多信息,请参阅使用相同的电子邮件地址使用不同的身份提供商登录文档。
开始之前
要遵循本指南,请确保您在 Okta workspace 中拥有创建 OIDC 应用程序的权限。
创建 Okta 应用程序
在 Okta Admin Console 中,从 Applications 菜单中选择 Create App Integration。
对于 Sign-in method,选择 OIDC - OpenID Connect。
对于 Application type,选择 Web Application,然后点击 Next。
配置 New Web App Integration Operations
- App integration name: 为应用程序选择一个名称。
- Logo (可选): 添加徽标。
- Grant type: 选择 Authorization Code 和 Refresh Token。
- Sign-in redirect URIs: 将默认设置替换为 Grafana Cloud Okta 路径,将 <YOUR_ORG> 替换为您 Grafana 组织的名称:https://<YOUR_ORG>.grafana.net/login/okta。对于本地安装,使用 Grafana 服务器 URL:http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/okta。
- Sign-out redirect URIs (可选): 将默认设置替换为 Grafana Cloud Okta 路径,将 <YOUR_ORG> 替换为您 Grafana 组织的名称:https://<YOUR_ORG>.grafana.net/logout。对于本地安装,使用 Grafana 服务器 URL:http://<my_grafana_server_name_or_ip>:<grafana_server_port>/logout。
- Base URIs (可选): 添加任何 Base URIs
- Controlled access: 选择是将应用程序集成分配给组织中的所有人,还是仅分配给选定的组。您可以在创建应用程序后分配此选项。
记下以下内容
- ClientID
- Client Secret
- Auth URL 例如:https://<TENANT_ID>.okta.com/oauth2/v1/authorize
- Token URL 例如:https://<TENANT_ID>.okta.com/oauth2/v1/token
- API URL 例如:https://<TENTA_ID>.okta.com/oauth2/v1/userinfo
配置 Okta 到 Grafana 角色映射
在 Okta Admin Console 中,选择 Directory > Profile Editor。
选择您之前创建的 Okta Application Profile(默认名称为
<App name> User
)。选择 Add Attribute 并填写以下字段
- Data Type: string
- Display Name: 有意义的名称。例如,
Grafana Role
。 - Variable Name: 有意义的名称。例如,
grafana_role
。 - Description (可选): 角色的描述。
- Enum: 选择 Define enumerated list of values 并添加以下内容
- Display Name: Admin Value: Admin
- Display Name: Editor Value: Editor
- Display Name: Viewer Value: Viewer
剩余属性是可选的,可根据需要设置。
点击 Save。
(可选) 您可以将角色属性添加到默认 User profile 中。为此,请按照可选:将角色属性添加到 User (默认) Okta profile 部分中的步骤操作。
配置 Groups claim
- 在 Okta Admin Console 中,选择 Application > Applications。
- 选择您创建的 OpenID Connect 应用程序。
- 转到 Sign On 选项卡,并在 OpenID Connect ID Token 部分点击 Edit。
- 在 Group claim type 部分,选择 Filter。
- 在 Group claim filter 部分,保留默认名称
groups
(如果框为空则添加),然后选择 Matches regex 并添加以下正则表达式:.*
。 - 点击 Save。
- 点击页面顶部的 Back to applications 链接。
- 在 More 按钮下拉菜单中,点击 Refresh Application Data。
- 在 Okta 集成的 Grafana 中的 Scopes 字段中包含
groups
scope。对于 Terraform 或在 Grafana 配置文件中,在scopes
字段中包含groups
scope。
注意
如果您以不同方式配置
groups
claim,请确保groups
claim 是一个字符串数组。
可选:将角色属性添加到 User (默认) Okta profile
如果您想为 Okta 目录中的所有用户配置角色,可以将角色属性添加到 User (默认) Okta profile 中。
- 返回 Directory 部分,选择 Profile Editor。
- 选择 User (默认) Okta profile,点击 Add Attribute。
- 以与步骤 3 相同的方式设置所有属性。
- 选择 Add Mapping 添加您的新属性。例如,user.grafana_role -> grafana_role。
- 要向用户添加角色,请从 Directory 中选择用户,然后点击 Profile -> Edit。
- 从您的新属性中选择一个选项,然后点击 Save。
- 通过将
Role attribute path
(在 Terraform 和配置文件中为role_attribute_path
)设置为<YOUR_ROLE_VARIABLE>
来更新 Okta 集成。例如:role_attribute_path = grafana_role
(使用配置)。
使用 Grafana UI 配置 Okta 认证客户端
注意
在
ssoSettingsAPI
功能开关后可用,该开关默认启用。
作为 Grafana 管理员,您可以使用 Okta UI 在 Grafana 中配置 Okta OAuth2 客户端。为此,请导航到 Administration > Authentication > Okta 页面并填写表单。如果您在 Grafana 配置文件中已有配置,则表单将预填充这些值,否则表单将包含默认值。
填写完表单后,点击 Save。如果保存成功,Grafana 将应用新配置。
如果您需要将 UI 中所做的更改重置回默认值,请点击 Reset。重置更改后,Grafana 将应用 Grafana 配置文件中的配置(如果有)或默认值。
注意
如果您在高可用性模式下运行 Grafana,配置更改可能不会立即应用于所有 Grafana 实例。您可能需要等待几分钟才能使配置传播到所有 Grafana 实例。
有关更多信息,请参阅配置选项。
使用 Terraform provider 配置 Okta 认证客户端
注意
在
ssoSettingsAPI
功能开关后可用,该开关默认启用。从 Terraform provider v2.12.0 起支持。
resource "grafana_sso_settings" "okta_sso_settings" {
provider_name = "okta"
oauth2_settings {
name = "Okta"
auth_url = "https://<okta tenant id>.okta.com/oauth2/v1/authorize"
token_url = "https://<okta tenant id>.okta.com/oauth2/v1/token"
api_url = "https://<okta tenant id>.okta.com/oauth2/v1/userinfo"
client_id = "CLIENT_ID"
client_secret = "CLIENT_SECRET"
allow_sign_up = true
auto_login = false
scopes = "openid profile email offline_access"
role_attribute_path = "contains(groups[*], 'Example::DevOps') && 'Admin' || 'None'"
role_attribute_strict = true
allowed_groups = "Example::DevOps,Example::Dev,Example::QA"
}
}
访问Terraform Registry,获取使用 grafana_sso_settings
资源的完整参考。
使用 Grafana 配置文件配置 Okta 认证客户端
确保您有权访问Grafana 配置文件。
步骤
要使用我们的 Okta OIDC 集成将您的 Okta OIDC provider 与 Grafana 集成,请按照以下步骤操作
按照创建 Okta 应用程序 中的步骤在 Okta 中创建一个 OIDC 应用程序。
请参考下表更新 Grafana 配置文件中
[auth.okta]
部分的字段值字段 描述 client_id
这些值必须与您的 Okta OIDC 应用程序中的 client ID 匹配。 auth_url
您的 OIDC provider 的授权端点。 https://<okta-tenant-id>.okta.com/oauth2/v1/authorize
token_url
您的 Okta OIDC provider 的令牌端点。 https://<okta-tenant-id>.okta.com/oauth2/v1/token
api_url
您的 Okta OIDC provider 的用户信息端点。 https://<tenant-id>.okta.com/oauth2/v1/userinfo
enabled
启用 Okta OIDC 认证。将此值设置为 true
。查看其他 Okta OIDC配置选项列表,并根据需要完成配置。
可选:配置 refresh token。
可选:配置团队同步。
重启 Grafana。
您现在应该在登录页面上看到一个 Okta OIDC 登录按钮,并且能够使用您的 OIDC provider 登录或注册。
以下是按照上述说明配置后,一个最简功能集成示例
[auth.okta]
name = Okta
icon = okta
enabled = true
allow_sign_up = true
client_id = <client id>
scopes = openid profile email offline_access
auth_url = https://<okta tenant id>.okta.com/oauth2/v1/authorize
token_url = https://<okta tenant id>.okta.com/oauth2/v1/token
api_url = https://<okta tenant id>.okta.com/oauth2/v1/userinfo
role_attribute_path = grafana_role
role_attribute_strict = true
allowed_groups = "Example::DevOps" "Example::Dev" "Example::QA"
配置 refresh token
当用户使用 OAuth provider 登录时,Grafana 会验证 access token 是否已过期。当 access token 过期时,Grafana 会使用提供的 refresh token(如果存在)获取新的 access token,而无需用户再次登录。
如果 refresh token 不存在,Grafana 会在 access token 过期后将用户从系统中注销。
要启用 Refresh Token
,请转到 Okta 应用程序设置并
- 在
General
选项卡下,找到General Settings
部分。 - 在
Grant Type
选项中,启用Refresh Token
复选框。
在配置文件中,在 [auth.okta]
部分的 scopes
中添加 offline_access
,并将 use_refresh_token
设置为 true
。
配置角色映射
注意
除非启用了
skip_org_role_sync
选项,否则用户的角色将设置为用户登录时从认证提供商检索到的角色。
用户的角色是使用 role_attribute_path
配置选项中的 JMESPath 表达式,根据 api_url
(/userinfo
OIDC 端点)端点负载检索的。
如果未找到有效角色,则将用户分配给auto_assign_org_role
选项指定的角色。您可以通过设置 role_attribute_strict = true
来禁用此默认角色分配。如果评估 role_attribute_path
和 org_mapping
表达式后未返回角色或返回无效角色,则此设置会拒绝用户访问。有关用户角色映射的更多信息,请参阅配置角色映射。
您可以使用 org_attribute_path
和 org_mapping
配置选项将用户分配给组织并指定其角色。有关更多信息,请参阅组织角色映射示例。如果同时指定了组织角色映射 (org_mapping
) 和常规角色映射 (role_attribute_path
),则用户将获得两个映射角色中权限最高的角色。
要允许映射 Grafana 服务器管理员角色,请使用 allow_assign_grafana_admin
配置选项。有关更多信息,请参阅配置选项。
在创建 Okta 应用程序 中,您在 Okta 中创建了一个自定义属性来存储角色。您可以通过将 role_attribute_path
配置选项设置为自定义属性名称来将角色映射到 Grafana 角色:role_attribute_path = grafana_role
(使用配置)。
如果您想根据用户组映射角色,可以使用 user info 端点中的 groups
属性。示例为 role_attribute_path = contains(groups[*], 'Example::DevOps') && 'Admin' || 'None'
。您可以在 Generic OAuth 页面的JMESPath 示例 中找到更多 JMESPath 表达式示例。
要了解如何在 Okta 的 user info 中添加自定义 claims,请参阅添加自定义 claims。
组织角色映射示例
注意
在自托管 Grafana 安装中可用。
在此示例中,org_mapping
使用 groups
属性作为源 (org_attribute_path
) 将当前用户映射到不同的组织和角色。如果用户是 Group 1 组的成员,则在 org_foo
组织中被授予 Viewer 角色;如果用户是 Group 2 组的成员,则在 org_bar
组织中被授予 Editor 角色;并且在 org_baz
(OrgID=3) 组织中也被授予 Editor 角色。
配置
org_attribute_path = groups
org_mapping = ["Group 1:org_foo:Viewer", "Group 2:org_bar:Editor", "*:3:Editor"]
配置团队同步 (仅 Enterprise 版)
注意
可用版本
通过使用 Team Sync,您可以将您的 Okta 组链接到 Grafana 中的团队。这将自动将用户分配到相应的团队。
将您的 Okta 组映射到 Grafana 中的团队,以便您的用户自动添加到正确的团队。
Okta 组可以通过组名称引用,例如 Admins
或 Editors
。
要了解更多关于 Team Sync 的信息,请参阅配置团队同步。
配置选项
下表概述了各种 Okta OIDC 配置选项。您可以将这些选项作为环境变量应用,类似于 Grafana 中的任何其他配置。有关更多信息,请参阅使用环境变量覆盖配置。
注意
如果配置选项需要包含冒号的 JMESPath 表达式,请将整个表达式用引号括起来以防止解析错误。例如
role_attribute_path: "role:view"
设置 | 必需 | Cloud 版支持 | 描述 | 默认值 |
---|---|---|---|---|
enabled | 否 | 是 | 启用 Okta OIDC 认证。将此值设置为 true。 | false |
name | 否 | 是 | 从 Grafana 用户界面引用 Okta OIDC 认证的名称。 | Okta |
icon | 否 | 是 | 在 Grafana 用户界面中用于 Okta OIDC 认证的图标。 | okta |
client_id | 是 | 是 | 您的 Okta OIDC 应用程序提供的 Client ID。 | |
client_secret | 是 | 是 | 您的 Okta OIDC 应用程序提供的 Client secret。 | |
auth_url | 是 | 是 | 您的 Okta OIDC provider 的授权端点。 | |
token_url | 是 | 是 | 用于获取 Okta OIDC access token 的端点。 | |
api_url | 是 | 是 | 用于获取用户信息 的端点。 | |
scopes | 否 | 是 | 逗号或空格分隔的 Okta OIDC scope 列表。 | openid profile email groups |
allow_sign_up | 否 | 是 | 通过 Okta OIDC 登录控制 Grafana 用户创建。如果设置为 false,则只有现有 Grafana 用户才能使用 Okta OIDC 登录。 | true |
auto_login | 否 | 是 | 设置为 true 以允许用户绕过登录屏幕自动登录。如果您配置多个认证提供商使用自动登录,则忽略此设置。 | false |
role_attribute_path | 否 | 是 | 用于查找 Grafana 角色的 JMESPath 表达式。Grafana 将首先使用 Okta OIDC ID token 评估表达式。如果未找到角色,则将使用从 UserInfo 端点获取的用户信息评估表达式。评估结果应是有效的 Grafana 角色(None 、Viewer 、Editor 、Admin 或 GrafanaAdmin )。有关用户角色映射的更多信息,请参阅配置角色映射。 | |
role_attribute_strict | 否 | 是 | 设置为 true 以在无法使用 role_attribute_path 或 org_mapping 提取 Grafana 组织角色时拒绝用户登录。有关用户角色映射的更多信息,请参阅配置角色映射。 | false |
org_attribute_path | 否 | 否 | 用于查找 Grafana 组织到角色映射的 JMESPath 表达式。评估结果将根据 org_mapping 映射到组织角色。有关组织到角色映射的更多信息,请参阅组织角色映射示例。 | |
org_mapping | 否 | 否 | 逗号或空格分隔的 <ExternalOrgName>:<OrgIdOrName>:<Role> 映射列表。值可以是 * ,表示“所有用户”。Role 是可选的,可以有以下值:None 、Viewer 、Editor 或 Admin 。有关外部组织到角色映射的更多信息,请参阅组织角色映射示例。 | |
skip_org_role_sync | 否 | 是 | 设置为 true 以停止自动同步用户角色。这将允许您手动在 Grafana 中为用户设置组织角色。 | false |
allowed_groups | 否 | 是 | 逗号或空格分隔的组列表。用户必须至少属于一个组才能登录。 | |
allowed_domains | 否 | 是 | 逗号或空格分隔的域列表。用户必须至少属于一个域才能登录。 | |
use_pkce | 否 | 是 | 设置为 true 以使用 Proof Key for Code Exchange (PKCE)。Grafana 使用基于 SHA256 的 S256 challenge method 和 128 字节(base64url 编码)的 code verifier。 | true |
use_refresh_token | 否 | 是 | 设置为 true 以使用 refresh token 并检查 access token 是否过期。 | false |
signout_redirect_url | 否 | 是 | 用户注销后重定向到的 URL。 |