권한 평가 도구(Permission Evaluation) 사용
Keycloak에서 권한 부여(Authorization)를 구성했다면, 실제로 정책과 권한이 올바르게 동작하는지 확인해야 할 때가 있다. 이때 유용하게 활용할 수 있는 것이 권한 평가 도구(Permission Evaluation)이다. 권한 평가 도구를 사용하면, 특정 사용자(또는 액세스 토큰)가 특정 자원(Resource)나 범위(Scope)에 접근할 수 있는지에 대해 미리 시뮬레이션해볼 수 있으며, 왜 접근이 허용되었거나 거부되었는지에 대한 상세 정보도 확인할 수 있다.
개요
권한 평가 도구는 Keycloak 관리자 콘솔의 리소스 서버(예: 특정 Client) → Authorization → Evaluate 메뉴에서 제공된다. 이 기능은 다음과 같은 상황에서 특히 유용하다.
특정 권한 설정에 문제가 있어 보이는데, 어떤 정책이 충돌을 일으키는지 확인하고 싶을 때
사용자별로 자원 접근이 허용되는 근거(만족된 정책)와 거부되는 근거(충족되지 않은 정책)를 파악하고 싶을 때
정책, 퍼미션 설정을 변경한 직후에 올바르게 동작하는지 빠르게 검증하고 싶을 때
평가 흐름
Keycloak 권한 부여에서 권한 평가가 이뤄지는 흐름은 다음과 같은 과정을 거친다.
사용자 혹은 액세스 토큰 식별 평가 대상이 되는 특정 사용자를 지정하거나, 실제 발급된 액세스 토큰을 직접 입력할 수도 있다.
자원(Resource) 및 범위(Scope) 설정 사용자가 어느 자원에 대해 어떤 범위로 접근을 시도했는지 구성한다. 예를 들어 “문서” 자원에 대해 “write” 범위를 요청한다고 가정한다.
정책 및 퍼미션 평가 Keycloak이 내부적으로 설정된 정책 및 퍼미션을 순차적으로 확인하여, 해당 사용자가 요청한 자원/범위 조합을 허용할지 또는 거부할지를 결정한다.
결과 표시 평가 도구는 최종적으로 허용(Granted) 또는 거부(Denied) 상태를 보여주며, 어떤 정책이 허용을 이끌었고(또는 거부를 이끌었고) 어떤 정책이 충족되지 않았는지 상세한 정보를 제공한다.
설정 및 사용 방법
Keycloak 콘솔에서 권한 평가 도구를 사용하는 일반적인 방법은 다음과 같다.
리소스 서버(Client) 선택 관리자 콘솔에서 권한 부여가 활성화된 클라이언트를 선택한다.
Authorization 탭 이동 상단 탭 중에서 ‘Authorization’을 클릭한다.
Evaluate 메뉴 진입 왼쪽 사이드 메뉴에서 ‘Evaluate’를 선택하면 권한 평가 화면이 나타난다.
사용자 혹은 토큰 입력
User: Keycloak에 등록된 사용자를 선택하면 해당 사용자의 정보(할당된 역할, 그룹 등)를 바탕으로 평가를 진행한다.
Access Token: 실제 발급된 JWT 토큰을 직접 입력해 평가할 수도 있다. 이를 통해 토큰에 포함된 클레임 기반 평가도 가능하다.
자원 및 범위 설정
Resource: 평가할 리소스 이름(예: “document”)을 선택한다.
Scope: 평가할 범위(예: “read”, “write” 등)가 있다면 선택한다.
Evaluate 버튼 클릭 필요한 정보를 입력한 뒤 “Evaluate” 버튼을 누르면, Keycloak이 내부적으로 모든 정책과 퍼미션을 확인한 뒤 결과를 반환한다.
결과 해석
권한 평가 도구가 반환하는 결과는 크게 두 부분으로 나뉜다.
결과 요약(Effect)
GRANTED: 모든 관련 퍼미션을 충족하여 자원 접근이 허용됨
DENIED: 하나 이상의 필수 정책이 충족되지 않아 접근 거부됨
세부 정보(Policies 및 Permissions)
어떤 퍼미션이 평가 대상이었는지, 그리고 그 퍼미션에 연결된 정책들이 어떻게 평가되었는지를 목록 형태로 보여준다.
정책이 허용으로 평가되었는지(Policy Granted), 거부되었는지(Policy Denied), 또는 비적용(해당되지 않음)되었는지 등이 표시된다.
정책 구성에서 종합 로직(affirmative, consensus, unanimous 등)에 따라 최종 결과가 달라질 수 있으므로, 어떤 로직으로 정책이 결합되어 있는지도 함께 확인해야 한다.
주의사항
정책 충돌: 정책이 서로 충돌하는 경우, 어떤 정책 결합 전략을 사용하느냐에 따라 최종 결과가 달라진다. 예를 들어, ‘Unanimous(만장일치)’ 전략인 경우 모든 정책이 만족되어야 GRANTED가 된다.
캐시: Keycloak의 토큰 검증이나 권한 검증에는 캐시가 개입될 수 있다. 권한 평가 도구는 즉시적인 시뮬레이션 결과를 보여주지만, 실제 런타임 환경에서의 캐시 정책도 고려해야 한다.
정책 범위(Scope): 정책이 특정 범위에만 유효하도록 구성된 경우, 요청 범위와 일치하지 않는다면 그 정책은 평가 대상에서 제외된다.
활용 예시
예를 들어, “문서”라는 리소스에 대해 “read”와 “write” 범위를 정의해놓고, “write” 범위는 ‘문서 작성 권한’ 역할을 가진 사용자만 허용하도록 정책을 세웠다고 가정한다. 이때, 어떤 사용자가 “document:write” 권한을 요청했는데 접근 거부가 발생한다면, 권한 평가 도구를 통해 다음과 같은 점검이 가능하다.
사용자가 실제로 “문서 작성 권한” 역할을 가지고 있는지
해당 역할이 제대로 설정되어 있고, 퍼미션이 “write” 범위를 허용하도록 연결되어 있는지
사용자 토큰에 필요한 클레임이 누락되지 않았는지
평가 결과는 각 정책이 어떤 근거로 허용 또는 거부를 결정했는지 보여주므로, 문제를 빠르게 찾고 수정할 수 있다.
Keycloak 권한 부여 기능을 제대로 활용하려면, 권한 평가 도구를 사용하여 정책과 퍼미션이 의도대로 동작하는지를 정기적으로 점검하는 것이 필수적이다. 이 도구를 통해 정책 충돌, 범위 설정 오류, 사용자 역할 누락 같은 오류를 신속히 파악하고 해결할 수 있다. 결과적으로 이는 리소스 보호 수준을 높이는 동시에, 권한 부여 설정을 유지보수하기 쉽게 만들어준다.
Last updated