Документацияbreadcrumb arrow Grafanabreadcrumb arrow Документация GlaberGraphbreadcrumb arrow Настройкаbreadcrumb arrow Настройка управления доступомbreadcrumb arrow Настройка аутентификацииbreadcrumb arrow Keycloak OAuth2

Настройка аутентификации Keycloak OAuth2

Аутентификация Keycloak OAuth2 позволяет пользователям входить в Grafana, используя свои учётные данные Keycloak. В этом руководстве объясняется, как настроить Keycloak в качестве провайдера аутентификации в Grafana.

Дополнительные параметры конфигурации, доступные для этого провайдера, см. в разделе Аутентификация Generic OAuth.

Note

Если вы используете одинаковый адрес электронной почты в Keycloak и в других провайдерах аутентификации (например, Grafana.com), вам нужно выполнить дополнительную настройку, чтобы гарантировать правильное сопоставление пользователей. Дополнительную информацию см. в документации Использование одного и того же адреса электронной почты для входа через разных провайдеров идентификации.

Возможно, вам придётся установить параметр root_url в [server], чтобы callback URL был корректным. Например, если вы обслуживаете Grafana за прокси.

Пример конфигурации:

ini 
[auth.generic_oauth]
enabled = true
name = Keycloak-OAuth
allow_sign_up = true
client_id = YOUR_APP_CLIENT_ID
client_secret = YOUR_APP_CLIENT_SECRET
scopes = openid email profile offline_access roles
email_attribute_path = email
login_attribute_path = username
name_attribute_path = full_name
auth_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/auth
token_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/token
api_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/userinfo
role_attribute_path = contains(roles[*], 'admin') && 'Admin' || contains(roles[*], 'editor') && 'Editor' || 'Viewer'

В качестве примера <PROVIDER_DOMAIN> может быть keycloak-demo.grafana.org, а <REALM_NAME> может быть grafana.

Чтобы настроить параметр kc_idp_hint для Keycloak, вам нужно изменить конфигурацию auth_url, чтобы включить параметр kc_idp_hint. Например, если вы хотите подсказать провайдера идентификации Google:

ini 
auth_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/auth?kc_idp_hint=google

Note

api_url не требуется, если id_token содержит всю необходимую информацию о пользователе, и он может добавить задержку в процесс входа. Он полезен как запасной вариант или если у пользователя более 150 членств в группах.

Конфигурация Keycloak

  1. Создайте клиента в Keycloak со следующими настройками:
  • Client ID: grafana-oauth
  • Enabled: ON
  • Client Protocol: openid-connect
  • Access Type: confidential
  • Standard Flow Enabled: ON
  • Implicit Flow Enabled: OFF
  • Direct Access Grants Enabled: ON
  • Root URL: <grafana_root_url>
  • Valid Redirect URIs: <grafana_root_url>/login/generic_oauth
  • Web Origins: <grafana_root_url>
  • Admin URL: <grafana_root_url>
  • Base URL: <grafana_root_url>

В качестве примера <grafana_root_url> может быть https://play.grafana.org. Не перечисленные параметры конфигурации можно оставить со значениями по умолчанию.

  1. В конфигурации областей клиента Assigned Default Client Scopes должны соответствовать:
email
offline_access
profile
roles

Warning

Эти области не добавляют утверждения групп в id_token. Без утверждений групп teamsync работать не будет. Teamsync рассматривается далее в этом документе.

  1. Чтобы сопоставление ролей работало с приведённой выше примерной конфигурацией, вам нужно создать следующие роли и назначить их пользователям:
admin
editor
viewer

Синхронизация команд

Note

Доступно в Grafana Enterprise и Grafana Cloud.

Синхронизация команд — это функция, которая позволяет сопоставлять группы из вашего провайдера идентификации с командами Grafana. Это полезно, если вы хотите предоставить своим пользователям доступ к определённым дашбордам или папкам на основе их членства в группах.

Чтобы включить teamsync, вам нужно добавить маппер groups в конфигурацию клиента в Keycloak. Это добавит утверждение groups в id_token. Затем вы можете использовать утверждение groups для сопоставления групп с командами в Grafana.

  1. В конфигурации клиента перейдите в Mappers и создайте маппер со следующими настройками:
  • Name: Group Mapper
  • Mapper Type: Group Membership
  • Token Claim Name: groups
  • Full group path: OFF
  • Add to ID token: ON
  • Add to access token: OFF
  • Add to userinfo: ON
  1. В конфигурации Grafana добавьте следующий параметр:
ini 
[auth.generic_oauth]
groups_attribute_path = groups

Если вы используете вложенные группы, содержащие специальные символы, такие как кавычки или двоеточия, парсер JMESPath может выполнить безвредную обратную функцию, чтобы Grafana могла правильно вычислить вложенные группы. Следующий пример показывает родительскую группу с именем Global с вложенной группой department, которая содержит список групп:

ini 
[auth.generic_oauth]
groups_attribute_path = reverse("Global:department")

Включение единого выхода

Чтобы включить единый выход (Single Logout), вам нужно добавить следующий параметр в конфигурацию Grafana:

ini 
[auth.generic_oauth]
signout_redirect_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/logout?post_logout_redirect_uri=https%3A%2F%2F<GRAFANA_DOMAIN>%2Flogin

В качестве примера <PROVIDER_DOMAIN> может быть keycloak-demo.grafana.org, <REALM_NAME> может быть grafana, а <GRAFANA_DOMAIN> может быть play.grafana.org.

Note

Grafana поддерживает подсказки ID-токена для единого выхода. Grafana автоматически добавляет параметр id_token_hint к запросу на выход, если она обнаруживает OAuth в качестве метода аутентификации.

Разрешение назначения администратора Grafana

Если роль приложения, полученная Grafana, — GrafanaAdmin, Grafana предоставляет пользователю привилегии администратора сервера.

Это полезно, если вы хотите предоставить привилегии администратора сервера подмножеству пользователей. Grafana также назначает пользователю роль Admin организации по умолчанию.

ini 
role_attribute_path = contains(roles[*], 'grafanaadmin') && 'GrafanaAdmin' || contains(roles[*], 'admin') && 'Admin' || contains(roles[*], 'editor') && 'Editor' || 'Viewer'
allow_assign_grafana_admin = true

Настройка refresh-токена

Когда пользователь входит в систему с помощью провайдера OAuth, Grafana проверяет, что access-токен не истёк. Когда access-токен истекает, Grafana использует предоставленный refresh-токен (если он есть) для получения нового access-токена.

Grafana использует refresh-токен для получения нового access-токена без необходимости для пользователя входить в систему снова. Если refresh-токен не существует, Grafana выполняет выход пользователя из системы после истечения access-токена.

Чтобы включить refresh-токен для Keycloak, сделайте следующее:

  1. Расширьте scopes в [auth.generic_oauth] с помощью offline_access.

  2. Добавьте use_refresh_token = true в конфигурацию [auth.generic_oauth].