GitLab OAuth 인증 구성

GitLab OAuth 인증 구성 (Configure GitLab OAuth authentication)

Grafana는 사용자 ID를 검증하는 여러 인증 방법을 제공하며, 인증 구성은 어떤 사용자가 Grafana에 접근하고 어떤 로그인 방법을 쓸 수 있는지 결정해요. auth provider 통합이 반환한 정보에 기반해 사용자 역할과 팀 멤버십을 자동 업데이트하도록 구성할 수도 있어요. 이 주제는 GitLab OAuth 인증을 구성하는 방법을 설명해요.

출처: 문서

본문

Note GitLab과 다른 인증 공급자에서 같은 이메일 주소를 쓰면 사용자가 올바르게 매칭되도록 추가 구성이 필요해요.

시작하기 전에

GitLab OAuth 애플리케이션을 만드는 방법을 알아야 해요.

GitLab OAuth 애플리케이션 만들기

1. GitLab 계정에 로그인하고 Profile > Preferences > Applications로 이동.
2. Add new application 클릭.
3. 필드를 채워요. Redirect URI에 https://<YOUR-GRAFANA-URL>/login/gitlab 입력하고 Scopes 목록에서 openid, email, profile을 체크. Confidential 체크박스는 그대로 둠.
4. Save application 클릭.
5. Application ID(Client Id)와 Secret(Client Secret)을 기록.

Grafana UI로 클라이언트 구성

Grafana Admin으로 Administration > Authentication > GitLab 페이지에서 양식을 채워 구성할 수 있어요. Save 후 성공하면 적용돼요. Reset으로 기본값으로 되돌릴 수 있어요.

Terraform provider로 클라이언트 구성

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 구성 파일로 클라이언트 구성

1. GitLab에 OAuth 애플리케이션을 만들어요. Redirect URI를 http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/gitlab로 설정. OAuth2 스코프를 openid, email, profile로 설정.
2. [auth.gitlab] 섹션의 client_id, client_secret(GitLab OAuth 앱과 일치), enabled = true를 설정.
3. 선택: refresh token 구성 — [auth.gitlab]에서 use_refresh_token을 true로 설정.
4. 역할 매핑 구성.
5. 선택: 팀 동기화 구성.
6. Grafana 재시작.

refresh token 구성

GitLab은 기본적으로 refresh token을 제공해요. Grafana v10.1.0부터 refresh token 가져오기와 액세스 토큰 만료 확인이 기본 활성화돼요. 끄려면 use_refresh_token을 false로 설정. (전용 accessTokenExpirationCheck 피처 토글은 v10.3.0에서 제거.)

JWT ID 토큰 검증 구성

기본적으로 Grafana는 암호화 서명을 검증하지 않고 ID 토큰에서 사용자 정보를 추출해요. 보안 강화를 위해 JWT 서명 검증을 활성화할 수 있어요.

• [auth.gitlab]에서 validate_id_token을 true로 설정.
• jwk_set_url을 GitLab 인스턴스의 JWKS 엔드포인트 URL로 설정. GitLab.com: https://gitlab.com/oauth/discovery/keys, 셀프 호스팅: https://<your-gitlab-domain>/oauth/discovery/keys.

[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

Caution validate_id_token이 true면 jwk_set_url을 반드시 구성해야 해요. JWK Set URL이 없거나 ID 토큰 서명을 검증할 수 없으면 인증이 실패해요.

allowed groups 구성

한 개 이상 GitLab 그룹의 멤버로 접근을 제한하려면 allowed_groups를 그룹 목록으로 설정해요. GitLab 그룹은 그룹 이름으로 참조해요. 서브그룹 frontend를 참조하려면 developers/frontend를 사용. 그룹·서브그룹 이름은 URL에 나타나는 그대로 항상 사용하세요.

역할 매핑 구성

skip_org_role_sync가 활성화되지 않았다면 사용자 역할은 GitLab에서 가져온 역할로 설정돼요. role_attribute_path의 JMESPath 표현식으로 가져와요. 서버 관리자 역할은 allow_assign_grafana_admin으로 매핑. 유효한 역할이 없으면 auto_assign_org_role이 지정한 역할을 할당하고, role_attribute_strict = true로 기본 할당을 비활성화. org_mapping으로 GitLab 그룹 멤버십에 따라 조직·역할을 지정할 수 있어요.

Org roles 매핑 예제:

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

OAuth 토큰 사용자 정보로 역할 매핑 — email이 [email protected]이면 Admin, 나머지 Viewer:

role_attribute_path = email=='[email protected]' && 'Admin' || 'Viewer'

그룹으로 역할 매핑 — example-group 멤버는 Editor, 나머지 Viewer:

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

서버 관리자 역할 매핑:

role_attribute_path = email=='[email protected]' && 'GrafanaAdmin' || 'Viewer'

모든 사용자에게 한 역할 매핑:

role_attribute_path = "'Viewer'"
skip_org_role_sync = false

Grafana에서 GitLab 구성 예제

[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

팀 동기화 구성

Note Grafana Enterprise와 Grafana Cloud에서 사용 가능.

Team Sync로 GitLab 그룹을 Grafana 팀에 매핑할 수 있어요. 자체 GitLab 인스턴스를 쓰면 auth_url, token_url, api_url의 gitlab.com 호스트명을 자신의 것으로 바꾸세요. 그룹·서브그룹 이름은 URL에 나타나는 그대로 사용하세요.

주요 구성 옵션

더 알아보기 (Learn more)

• Configure authentication
• GitLab OAuth 앱 만들기
• Configure team sync
• Generic OAuth - JMESPath 예제