Keycloak 멀티테넌트 OAuth 인증 구성
Keycloak 멀티테넌트 OAuth 인증 구성 (Configure Keycloak multitenant authentication)
Keycloak을 사용해 여러 테넌트(조직, 클라이언트)의 사용자를 하나의 Grafana 배포에 로그인시킬 수 있어요. 이 멀티테넌트 설정은 여러 고객이나 부서의 사용자를 단일 Grafana 인스턴스에 매핑할 때 유용해요. 이 주제는 Keycloak 멀티테넌트 OAuth2/OIDC 연동을 구성하는 방법을 안내해요.
출처: 문서
본문
개요
멀티테넌트 설정에서 각 테넌트 사용자는 토큰의 고유 클레임(예: tenant, org, 또는 realm/issuer)으로 식별돼요. Grafana에서 org_mapping과 클레임 기반 JMESPath를 조합해, 테넌트별로 사용자를 올바른 조직과 역할에 자동 배치할 수 있어요.
구성 예
Generic OAuth 통합을 쓰고, 토큰에서 테넌트를 식별하는 클레임을 매핑해요. 예를 들어 Keycloak 토큰의 groups나 커스텀 클레임(tenant_access)이 테넌트를 나타낸다고 해요.
[auth.generic_oauth]
enabled = true
name = Keycloak (multitenant)
client_id = YOUR_KEYCLOAK_CLIENT_ID
client_secret = YOUR_KEYCLOAK_CLIENT_SECRET
scopes = openid profile email groups
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
# 테넌트 그룹/클레임을 조직과 역할로 매핑
org_attribute_path = tenant_access.roles
org_mapping = tenant1:org-tenant1:Admin tenant2:org-tenant2:Viewer *:org-default:Viewer
여기서:
org_attribute_path는 사용자에게 매핑할 조직·역할을 얻을 토큰 속성을 선택해요.org_mapping은<ExternalOrgValue>:<OrgIdOrName>:<Role>형식의 매핑 목록이에요.*는 "모든 사용자"를 뜻해요. 역할은None,Viewer,Editor,Admin중 하나예요.
테넌트 식별 클레임 설계
멀티테넌트 매핑을 하려면 토큰이 테넌트를 구분하는 신뢰할 수 있는 클레임을 담아야 해요. Keycloak에서:
- realm 기반: 각 테넌트를 별도 realm으로 두고 issuer(
iss)/realm 클레임으로 구분. - 그룹 기반: 각 테넌트 그룹을 Keycloak 그룹으로 두고
groups클레임 사용. - 커스텀 클레임: mapper로
tenant_access같은 커스텀 클레임을 토큰에 추가.
역할 매핑은 role_attribute_path로도 가능해요. 예를 들어 그룹 기반:
role_attribute_path = contains(groups[*], 'tenant1-admins') && 'Admin' || 'Viewer'
Note 여러 조건을 결합할 때는 JMESPath 표현식이 정확한지 JMESPath로 테스트하세요. 콜론이 포함된 표현식은 따옴표로 감싸 파싱 오류를 막아요.
Grafana Cloud에서의 고려 사항
Grafana Cloud에서는 일부 고급 역할 매핑 설정(org_attribute_path, org_mapping)이 셀프 매니지드에서만 지원돼요. Grafana Cloud에서 멀티테넌트 연동을 구성할 때는 지원되는 설정을 확인하세요.