Keycloak OAuth 인증 구성

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

Keycloak은 오픈 소스 ID·접근 관리 솔루션이에요. Keycloak OAuth를 Grafana의 인증 공급자로 구성하면, Keycloak으로 사용자 인증과 권한을 중앙 집중화할 수 있어요. 이 주제는 Grafana 구성에서 Keycloak OAuth2/OIDC 클라이언트를 설정하는 단계를 안내해요.

출처: 문서

본문

시작하기 전에

Keycloak 관리자 콘솔 접근 권한과, Grafana에 사용할 Keycloak 클라이언트를 만들어야 해요.

Keycloak 클라이언트 만들기

Keycloak 관리자 콘솔에 로그인.
원하는 Realm을 선택하고 Clients로 이동.
Create client 클릭.
Client ID 입력(예: grafana). Client authentication을 켜고, Valid redirect URIs에 http://<YOUR-GRAFANA-URL>/login/grafana-cloud(또는 설정에 맞는 경로)를 추가.
사용할 OIDC/OAuth2 설정(grant types 등)을 완료.

Grafana 구성 파일로 클라이언트 구성

Keycloak OAuth 활성화

[auth.grafana_com]
# Keycloak을 OIDC로 사용하려면 grafana_com 대신 [auth.generic_oauth]를 쓰는 경우가 많아요.

Keycloak은 완전한 OIDC 공급자이므로 Grafana의 Generic OAuth 통합을 쓰는 것이 가장 일반적이에요:

[auth.generic_oauth]
enabled = true
name = Keycloak
allow_sign_up = true
client_id = YOUR_KEYCLOAK_CLIENT_ID
client_secret = YOUR_KEYCLOAK_CLIENT_SECRET
scopes = openid profile email
auth_url = https://<KEYCLOAK_URL>/realms/<REALM>/protocol/openid-connect/auth
token_url = https://<KEYCLOAK_URL>/realms/<REALM>/protocol/openid-connect/token
api_url = https://<KEYCLOAK_URL>/realms/<REALM>/protocol/openid-connect/userinfo

여기서 <KEYCLOAK_URL>은 Keycloak 서버 주소, <REALM>은 사용하는 realm 이름이에요. auth_url, token_url, api_url은 Keycloak realm의 OIDC 엔드포인트로, Keycloak Admin Console의 Realm settings > Endpoints에서 정확한 URL을 확인할 수 있어요.

PKCE

OAuth 2.1과 보안 모범 사례에 따라 use_pkce = true를 설정해 Proof Key for Code Exchange를 활성화하는 것이 좋아요.

클레임·역할 매핑

사용자 역할을 매핑하려면 role_attribute_path에 JMESPath 표현식을 설정해요. 예를 들어 Keycloak이 토큰에 realm_access.roles 배열을 주면:

role_attribute_path = contains(realm_access.roles[*], 'grafana-admin') && 'Admin' || contains(realm_access.roles[*], 'grafana-editor') && 'Editor' || 'Viewer'

그룹 기반 역할 매핑이라면 groups 배열을 사용할 수 있어요. 조직 간 역할·조직 매핑은 org_mapping으로 지정해요.

Grafana UI로 클라이언트 구성

Grafana Admin으로 Administration > Authentication > OAuth 페이지(또는 사용 중인 통합 페이지)에서 양식을 채워 구성할 수 있어요. 구성 파일에 현재 설정이 있으면 양식이 미리 채워져요. Save 후, Reset으로 되돌릴 수 있어요.

Terraform provider로 구성

grafana_sso_settings 리소스로 구성할 수 있어요:

resource "grafana_sso_settings" "keycloak_sso_settings" {
  provider_name = "generic_oauth"
  oauth2_settings {
    name      = "Keycloak"
    auth_url  = "https://<KEYCLOAK_URL>/realms/<REALM>/protocol/openid-connect/auth"
    token_url = "https://<KEYCLOAK_URL>/realms/<REALM>/protocol/openid-connect/token"
    api_url   = "https://<KEYCLOAK_URL>/realms/<REALM>/protocol/openid-connect/userinfo"
    client_id = "YOUR_KEYCLOAK_CLIENT_ID"
    client_secret = "YOUR_KEYCLOAK_CLIENT_SECRET"
    allow_sign_up = true
    scopes = "openid profile email"
    use_pkce = true
  }
}

Team Sync

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

Team Sync로 Keycloak 그룹을 Grafana 팀에 매핑할 수 있어요. Grafana 팀의 External group sync 탭에서 외부 그룹 ID를 설정해요. Keycloak을 Generic OAuth로 쓸 때 그룹 클레임을 얻으려면 groups 스코프를 추가하고, Keycloak 쪽에서 토큰에 그룹 클레임이 포함되도록 mapper를 설정해야 해요.

Keycloak OAuth 인증 구성