[Keycloak] 어드민 API 호출 권한, 사용자에게 직접 부여하기

이번 글에서는 Keycloak의 Admin API 호출 권한을 클라이언트가 아닌 개별 사용자에게 직접 부여하는 방법을 정리합니다. 일반적으로 권한은 클라이언트에 설정되지만, 특정 사용자만 API 호출 권한을 갖게 하려면 직접 사용자에게 역할을 부여해야 합니다.

목표 시나리오

• 특정 사용자가 Keycloak Admin API 호출에 필요한 권한을 직접 갖도록 설정
• 예를 들어, 특정 관리자가 직접 사용자 정보 조회 및 그룹 조회 등의 API를 호출할 수 있게 설정

왜 사용자에게 직접 역할을 부여하는가?

장점	설명
세부 권한 관리	특정 사용자에게만 정교하게 권한 부여
임시 권한 부여 가능	긴급 상황 등 일시적으로 API 호출 권한 부여 가능
최소 권한 원칙 준수	클라이언트 전체가 아닌 특정 사용자에게만 제한적으로 권한 부여

Keycloak 설정 방법

1. 필요한 역할 확인

Keycloak Admin API 호출에 필요한 역할 확인:

• query-groups
• view-users
• 필요 시 추가 역할 (예: manage-users, manage-groups 등)

2. 사용자에게 직접 역할 부여하기

• Keycloak Admin Console → Users → 사용자 선택 → Role Mappings
• Client Roles 탭에서 realm-management 선택
• 사용자에게 다음과 같은 역할을 부여:
  • query-groups
  • view-users
  • 필요한 기타 역할 추가

3. 토큰 발급 시 포함되는 권한 확인하기

사용자가 로그인하면 발급되는 Access Token에 다음과 같은 권한이 포함됩니다:

"realm_access": {
  "roles": ["offline_access", "uma_authorization", "query-groups", "view-users"]
}