Документация Grafana Документация GlaberGraph Настройка Настройка управления доступом Настройка аутентификации GitLab OAuth

Настройка аутентификации GitLab OAuth

В этом разделе описано, как настроить аутентификацию GitLab OAuth.

Перед началом

Убедитесь, что вы знаете, как создать приложение GitLab OAuth. Дополнительную информацию смотрите в документации GitLab о создании приложения GitLab OAuth.

Создание приложения GitLab OAuth

1. Войдите в свою учётную запись GitLab и перейдите в Profile > Preferences > Applications.
2. Нажмите Add new application.
3. Заполните поля.
   • В поле Redirect URI введите следующее: https://<YOUR-GRAFANA-URL>/login/gitlab и отметьте openid, email, profile в списке Scopes.
   • Оставьте флажок Confidential отмеченным.
4. Нажмите Save application.
5. Запомните свой Application ID (это Client Id) и Secret (это Client Secret).

Настройка клиента аутентификации GitLab через интерфейс Grafana

Как администратор Grafana вы можете настроить клиент GitLab OAuth изнутри Grafana через интерфейс GitLab. Для этого перейдите на страницу Administration > Authentication > GitLab и заполните форму. Если у вас есть текущая конфигурация в файле конфигурации Grafana, форма будет предварительно заполнена этими значениями, в противном случае форма будет содержать значения по умолчанию.

После того как вы заполнили форму, нажмите Save, чтобы сохранить конфигурацию. Если сохранение прошло успешно, Grafana применит новые конфигурации.

Если вам нужно сбросить изменения, сделанные в интерфейсе, обратно к значениям по умолчанию, нажмите Reset. После сброса изменений Grafana применит конфигурацию из файла конфигурации Grafana (если есть какая-либо конфигурация) или значения по умолчанию.

Дополнительную информацию см. в разделе параметры конфигурации.

Настройка клиента аутентификации GitLab с помощью провайдера Terraform

terraform Copy

resource "grafana_sso_settings" "gitlab_sso_settings" {
  provider_name = "gitlab"
  oauth2_settings {
    name                  = "Gitlab"
    client_id             = "YOUR_GITLAB_APPLICATION_ID"
    client_secret         = "YOUR_GITLAB_APPLICATION_SECRET"
    allow_sign_up         = true
    auto_login            = false
    scopes                = "openid email profile"
    allowed_domains       = "mycompany.com mycompany.org"
    role_attribute_path   = "contains(groups[*], 'example-group') && 'Editor' || 'Viewer'"
    role_attribute_strict = false
    allowed_groups        = "[\"admins\", \"software engineers\", \"developers/frontend\"]"
    use_pkce              = true
    use_refresh_token     = true
  }
}

Полное справочное руководство по использованию ресурса grafana_sso_settings см. в Terraform Registry.

Настройка клиента аутентификации GitLab с помощью файла конфигурации Grafana

Убедитесь, что у вас есть доступ к файлу конфигурации Grafana.

Шаги

Чтобы настроить аутентификацию GitLab с Grafana, выполните следующие шаги:

1. Создайте приложение OAuth в GitLab.

   1. Установите redirect URI в http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/gitlab.

      Убедитесь, что Redirect URI — это полный HTTP-адрес, который вы используете для доступа к Grafana через браузер, но с добавленным путём /login/gitlab.

      Чтобы Redirect URI был корректным, может потребоваться установить параметр root_url в разделе [server] файла конфигурации Grafana. Например, если вы обслуживаете Grafana за прокси.

   2. Установите области OAuth2 в openid, email и profile.

2. Обратитесь к следующей таблице, чтобы обновить значения полей, расположенных в разделе [auth.gitlab] файла конфигурации Grafana:

   Expand table

   Поле	Описание
   client_id, client_secret	Эти значения должны совпадать с Application ID и Secret вашего приложения GitLab OAuth.
   enabled	Включает аутентификацию GitLab. Установите это значение в true.

   Просмотрите список других параметров конфигурации GitLab и заполните их по мере необходимости.

3. Необязательно: Настройте refresh-токен:

   a. Установите use_refresh_token в true в разделе [auth.gitlab] в файле конфигурации Grafana.

4. Настройте сопоставление ролей.

5. Необязательно: Настройте синхронизацию команд.

6. Перезапустите Grafana.

   Теперь вы должны увидеть кнопку входа GitLab на странице входа и иметь возможность войти или зарегистрироваться с помощью своих учётных записей GitLab.

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

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

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

По умолчанию GitLab предоставляет refresh-токен.

Получение refresh-токена и проверка истечения access-токена включены по умолчанию для провайдера GitLab начиная с Grafana v10.1.0. Если вы хотите отключить проверку истечения access-токена, установите значение конфигурации use_refresh_token в false.

Настройка валидации ID-токена JWT

По умолчанию Grafana извлекает информацию о пользователе из ID-токенов, не проверяя их криптографические подписи. Для повышения безопасности вы можете включить валидацию подписи JWT, чтобы гарантировать, что ID-токены подлинны и не были подделаны.

Чтобы включить валидацию ID-токена JWT:

1. Установите validate_id_token в true в разделе [auth.gitlab] файла конфигурации Grafana.

2. Настройте jwk_set_url с URL конечной точки JSON Web Key Set (JWKS) вашего экземпляра GitLab. Эта конечная точка предоставляет публичные ключи, используемые для проверки подписей JWT.

   Для GitLab.com конечная точка JWKS: https://gitlab.com/oauth/discovery/keys

   Для самостоятельно размещённых экземпляров GitLab конечная точка JWKS обычно: https://<your-gitlab-domain>/oauth/discovery/keys

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

ini Copy

[auth.gitlab]
enabled = true
validate_id_token = true
jwk_set_url = https://gitlab.com/oauth/discovery/keys
client_id = <client id>
client_secret = <client secret>
scopes = openid email profile

Настройка разрешённых групп

Чтобы ограничить доступ аутентифицированных пользователей, которые являются членами одной или нескольких групп GitLab, установите allowed_groups в список групп, разделённых запятыми или пробелами.

Группы GitLab указываются по имени группы. Например, developers. Чтобы указать подгруппу frontend, используйте developers/frontend. Обратите внимание, что в GitLab имя группы или подгруппы не всегда совпадает с её отображаемым именем, особенно если отображаемое имя содержит пробелы или специальные символы. Убедитесь, что вы всегда используете имя группы или подгруппы так, как оно указано в URL группы или подгруппы.

Настройка сопоставления ролей

Если только не включён параметр skip_org_role_sync, роль пользователя будет установлена в роль, полученную от GitLab при входе пользователя.

Роль пользователя извлекается с помощью выражения JMESPath из параметра конфигурации role_attribute_path. Чтобы сопоставить роль администратора сервера, используйте параметр конфигурации allow_assign_grafana_admin. Дополнительную информацию см. в разделе параметры конфигурации.

Вы можете использовать параметр конфигурации org_mapping для назначения пользователя нескольким организациям и указания его роли на основе его членства в группах GitLab. Дополнительную информацию см. в разделе Пример сопоставления ролей организации. Если сопоставление роли организации (org_mapping) указано и Entra ID возвращает допустимую роль, то пользователь получит более высокую из двух ролей.

Если допустимая роль не найдена, пользователю назначается роль, указанная параметром auto_assign_org_role. Вы можете отключить это назначение роли по умолчанию, установив role_attribute_strict = true. Этот параметр запрещает доступ пользователю, если не возвращена роль или возвращена недопустимая роль после вычисления выражений role_attribute_path и org_mapping.

Чтобы упростить настройку правильного выражения JMESPath, перейдите на JMESPath, чтобы протестировать и оценить выражения с пользовательскими полезными нагрузками.

Примеры сопоставления ролей

В этом разделе приведены примеры выражений JMESPath, используемых для сопоставления ролей.

Пример сопоставления ролей организации

Интеграция GitLab использует группы внешних пользователей в конфигурации org_mapping для сопоставления организаций и ролей на основе их членства в группах GitLab.

В этом примере пользователю предоставлена роль Viewer в организации org_foo и роль Editor в организациях org_bar и org_baz.

Внешний пользователь является частью следующих групп GitLab: groupd-1 и group-2.

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

ini Copy

org_mapping = group-1:org_foo:Viewer groupd-1:org_bar:Editor *:org_baz:Editor

Сопоставление ролей с использованием информации о пользователе из токена OAuth

В этом примере пользователю с электронной почтой admin@company.com предоставлена роль Admin. Всем остальным пользователям предоставляется роль Viewer.

ini Copy

role_attribute_path = email=='admin@company.com' && 'Admin' || 'Viewer'

Сопоставление ролей с использованием групп

В этом примере пользователю из группы GitLab ’example-group’ предоставлена роль Editor. Всем остальным пользователям предоставляется роль Viewer.

ini Copy

role_attribute_path = contains(groups[*], 'example-group') && 'Editor' || 'Viewer'

Сопоставление роли администратора сервера

В этом примере пользователю с электронной почтой admin@company.com предоставлена роль организации Admin, а также роль администратора сервера Grafana. Всем остальным пользователям предоставляется роль Viewer.

Bash Copy

role_attribute_path = email=='admin@company.com' && 'GrafanaAdmin' || 'Viewer'

Сопоставление одной роли всем пользователям

В этом примере всем пользователям будет назначена роль Viewer независимо от информации о пользователе, полученной от провайдера идентификации.

ini Copy

role_attribute_path = "'Viewer'"
skip_org_role_sync = false

Пример конфигурации GitLab в Grafana

В этом разделе приведён пример конфигурации GitLab в файле конфигурации Grafana.

Bash Copy

[auth.gitlab]
enabled = true
allow_sign_up = true
auto_login = false
client_id = YOUR_GITLAB_APPLICATION_ID
client_secret = YOUR_GITLAB_APPLICATION_SECRET
scopes = openid email profile
auth_url = https://gitlab.com/oauth/authorize
token_url = https://gitlab.com/oauth/token
api_url = https://gitlab.com/api/v4
role_attribute_path = contains(groups[*], 'example-group') && 'Editor' || 'Viewer'
role_attribute_strict = false
allow_assign_grafana_admin = false
allowed_groups = ["admins", "software engineers", "developers/frontend"]
allowed_domains = mycompany.com mycompany.org
tls_skip_verify_insecure = false
use_pkce = true
use_refresh_token = true

Настройка синхронизации команд

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

Группы GitLab указываются по имени группы. Например, developers. Чтобы указать подгруппу frontend, используйте developers/frontend. Обратите внимание, что в GitLab имя группы или подгруппы не всегда совпадает с её отображаемым именем, особенно если отображаемое имя содержит пробелы или специальные символы. Убедитесь, что вы всегда используете имя группы или подгруппы так, как оно указано в URL группы или подгруппы.

Чтобы узнать больше о синхронизации команд, см. Настройка синхронизации команд.

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

В следующей таблице описаны все параметры конфигурации GitLab OAuth. Вы можете применять эти параметры как переменные среды, как и любую другую конфигурацию в Grafana. Дополнительную информацию см. в разделе Переопределение конфигурации с помощью переменных среды.