권한 승인(Grant) 흐름

Keycloak에서의 권한 승인(Grant) 흐름은 OAuth 2.0 및 OpenID Connect 표준을 바탕으로 동작하며, 사용자가 특정 리소스에 접근하기 위해 필요한 권한을 안전하게 할당받고 검증받는 과정을 의미한다. 이 흐름은 단순히 “인증(Authentication)을 거쳐 토큰을 발급받는다”로 끝나지 않고, 발급된 토큰이 실제로 어떠한 권한을 포함하며, 그 권한이 어떻게 구성되고 검증되는지까지 포함한다.

권한 승인 흐름의 개념적 구조

클라이언트 요청 사용자는 애플리케이션(클라이언트)을 통해 보호된 리소스에 접근을 시도한다. 이때 클라이언트는 Keycloak에 사용자를 인증하고 필요한 권한을 획득하기 위해 토큰 발급 또는 갱신을 요청한다.
인증 및 세션 생성 Keycloak은 사용자를 인증하고, 성공 시 내부적으로 세션 정보를 생성한다. 이 단계에서 사용자의 자격 증명(아이디/비밀번호 등)을 확인하고, Multi-Factor Authentication(MFA) 같은 추가 검증이 필요한 경우 해당 절차를 진행한다.
권한 평가(Authorization Evaluation) 사용자가 인증에 성공하면 Keycloak의 Authorization Services가 리소스 서버나 관리자에 의해 사전에 정의된 정책을 평가한다. 이 정책에는 역할(Role), 그룹(Group), 속성(Attribute), 사용자의 상태 등에 따른 복잡한 규칙이 포함될 수 있다. 정책이 허용하는 범위 내에서만 실제로 권한이 부여된다.
토큰 발급(Grant 발행) 정책 평가 결과가 허용(permit)으로 결정되면, 사용자의 액세스 토큰(Access Token)이나 요청자 파티 토큰(RPT, UMA 프로필 사용 시) 등 필요한 토큰이 발급된다. 이 토큰에는 사용자가 접근할 수 있는 리소스와 그 범위(scope)에 대한 정보가 포함된다.
리소스 요청 애플리케이션은 발급된 토큰을 사용하여 보호된 리소스에 접근한다. 리소스 서버(또는 Keycloak Adapter)는 토큰의 유효성 및 포함된 권한 정보를 검증하여 최종 접근 권한을 결정한다.

대표적인 권한 승인 시나리오

사용자 대 클라이언트(Authorization Code Flow)

사용자가 브라우저에서 애플리케이션에 접근.
애플리케이션은 Keycloak의 권한 승인 엔드포인트로 리다이렉트하여 로그인 요청.
인증에 성공하면 Keycloak은 콜백 URL로 코드를 전달.
애플리케이션은 해당 코드를 사용해 액세스 토큰과 리프레시 토큰을 교환.
Keycloak은 정책을 확인하여 적절한 권한을 토큰에 포함해 발급.
애플리케이션은 이 토큰을 이용해 보호된 API나 리소스에 접근.

클라이언트 인증(Client Credentials Flow)

신뢰할 수 있는 백엔드 애플리케이션(클라이언트)이 Keycloak에 직접 요청.
사전에 설정된 클라이언트 아이디와 시크릿을 사용해 인증.
정책 평가를 거쳐, 해당 클라이언트에게 부여되는 권한 범위를 토큰에 포함.
발급받은 토큰으로 보호된 리소스나 API에 접근.

자원 소유자 비밀번호 자격 증명(Resource Owner Password Credentials Flow)

사용자가 애플리케이션에 아이디와 비밀번호를 직접 제공.
애플리케이션이 Keycloak에 사용자 자격 증명을 전달하여 인증 요청.
인증이 성공하면 Keycloak이 정책 평가 후 토큰 발급.
토큰을 사용해 보호된 리소스에 접근.

UMA(User-Managed Access) 기반 권한 승인

Keycloak은 UMA 프로필을 지원하여, 사용자가 소유한 리소스에 대한 접근 요청 시 “Permission Ticket”을 발행하고 이를 검증함으로써 세분화된 권한 부여를 제공한다. UMA는 다음과 같은 단계가 추가된다.

Permission Ticket 발행 클라이언트가 특정 리소스에 대해 접근을 요청하면, Keycloak은 해당 요청을 기반으로 Permission Ticket을 발행한다.
권한 검증(Authorization Request) 클라이언트는 Permission Ticket과 함께 액세스 토큰을 이용해 Keycloak의 권한 승인 엔드포인트로 요청한다. 이때 Keycloak은 내부 정책을 기반으로 접근 권한을 최종 결정한다.
RPT(Requesting Party Token) 발급 접근이 허용되면, Keycloak은 RPT를 클라이언트에 반환한다. 이후부터 클라이언트는 이 RPT를 사용해 리소스 서버에 요청을 보내며, 리소스 서버는 RPT를 검증해 사용자의 접근을 허가한다.

권한 승인 흐름에서 주의사항

정책 정의 역할, 그룹, 속성, 사용자 상태 등 다양한 요소를 조합하여 정책을 체계적으로 설계해야 한다. 너무 단순하게 정책을 구성하면 세분화된 권한 부여가 어려워지고, 반대로 너무 복잡하면 유지보수가 힘들어진다.
토큰 유효기간 관리 발급된 토큰이 만료되면 다시 갱신하는 절차가 필요하다. 리프레시 토큰이 만료될 경우에는 다시 초기 인증 과정을 거쳐야 하므로, 운영 환경에 맞춰 적절한 토큰 만료 정책을 설정해야 한다.
Scope 구성 Keycloak의 스코프(Scope)는 리소스 접근 범위를 정의한다. 스코프를 너무 넓게 설정하면 최소 권한의 원칙(least privilege principle)에 위배될 수 있다. 필요한 스코프만 명확히 설정해야 한다.
감사 및 모니터링(Auditing & Monitoring) 누가 어떤 리소스에 접근했는지를 추적하기 위한 감사 로그를 활성화하고, 수상한 접근이 없는지 모니터링할 수 있는 환경을 구성하는 것이 중요하다.

권한 승인(Grant) 흐름은 Keycloak의 가장 핵심적인 기능 중 하나로, 다양한 시나리오에서 유연하고 세분화된 접근 제어를 구현할 수 있게 해준다. 이를 제대로 이해하고 활용하면, 단순 사용자 인증을 넘어 서비스나 애플리케이션 전반의 보안을 강화하고 관리 효율을 높일 수 있다.