# 리소스 서버(Resource Server) 설정

Keycloak에서 리소스 서버(Resource Server)란 보호해야 할 자원(리소스)과 그에 따른 접근 제어 로직(스코프·퍼미션·폴리시 등)을 정의하고 관리하는 주체다. 일반적으로 애플리케이션 서버나 API 서버가 이에 해당하며, Keycloak에 “클라이언트(Client)”로 등록되어 자원 보호와 권한 부여 로직을 구성한다.

리소스 서버는 다음과 같은 과정으로 설정한다.

1. 클라이언트 생성 Keycloak 관리자 콘솔에서 새로운 클라이언트를 생성한다. 이때 “Client Type”을 “OpenID Connect”로 선택하고, “Access Type”을 “Confidential” 또는 “Bearer-only”로 지정할 수 있다.

* Confidential: 인증 후 토큰 교환이 필요한 일반적인 서버 사이드 애플리케이션에 사용한다.
* Bearer-only: 자체적으로 로그인 화면을 갖지 않고, 단지 Keycloak이 발행한 토큰만 신뢰하는 API 서버 등에 사용한다.

클라이언트 생성 후, “Settings” 화면 하단에 위치한 “Authorization Enabled” 옵션을 활성화하면 해당 클라이언트는 Keycloak에서 리소스 서버로 동작하게 된다.

1. 리소스 정의 리소스 서버로 등록된 클라이언트는 “Authorization” 탭에서 리소스(자원)을 정의할 수 있다. 리소스는 일반적으로 보호할 API 엔드포인트, URL 패턴, 특정 기능, 파일 등으로 구성된다.

* Name: 리소스 식별을 위한 이름이다.
* URI: 리소스가 실제로 제공되는 엔드포인트(URL) 혹은 식별자다.
* Scopes: 이 리소스가 지원하거나 보호해야 하는 행위(읽기, 쓰기, 삭제 등)에 해당한다.

스코프를 통해 리소스에 대한 구체적 접근 방식(예: read, write)을 구분할 수 있으며, 리소스 정의 시 필요한 경우 “Owner”나 “Type” 등을 설정해 관리할 수도 있다.

1. 폴리시(Policy) 구성 폴리시는 권한 부여 판단 로직을 정의한다. 예를 들어 특정 역할(Role)을 가진 사용자만 접근이 가능하도록 하거나, 사용자 속성(User Attribute)에 따라 접근을 제한할 수 있다. Keycloak은 다음과 같은 다양한 폴리시 유형을 제공한다.

* Role-based Policy: 특정 Realm 혹은 클라이언트 단위에서 부여된 역할을 기반으로 접근 권한을 결정한다.
* User-based Policy: 특정 사용자 혹은 사용자 그룹(그룹)에 따라 접근을 제어한다.
* Client-based Policy: 특정 클라이언트나 클라이언트 역할에 따른 접근을 제어한다.
* Time-based Policy: 시간대(요일, 시간 등)에 따라 접근을 허용 혹은 제한한다.
* User Attribute Policy: 사용자 프로필에 설정된 속성(조직, 나이, 직급 등)을 활용해 접근을 제한한다.

1. 퍼미션(Permission) 설정 퍼미션은 “어떤 리소스(또는 스코프)에 대해 어떤 폴리시 로직을 적용할 것인가”를 결정한다. Keycloak에서는 크게 “Resource-based Permission”과 “Scope-based Permission”을 제공한다.

* Resource-based Permission: 지정된 리소스 전체에 대해 하나 이상의 폴리시를 결합해 접근 권한을 정의한다.
* Scope-based Permission: 리소스에 설정된 개별 스코프(read, write 등)에 대해 세부적으로 폴리시를 적용한다.

퍼미션 생성 시 정책을 결합할 수 있고, 여러 폴리시가 적용될 경우 AND/OR 조건을 통해 접속 허용 여부를 결정한다.

1. 정책 집행 모드(Policy Enforcement Mode) Authorization 탭의 “Settings”에서 정책 집행 모드를 설정한다.

* Enforcing: 모든 리소스 요청은 정의된 퍼미션을 통과해야 한다.
* Permissive: 정의되지 않은 리소스나 스코프 요청에 대해서는 기본적으로 허용한다.
* Disabled: 권한 부여 기능을 비활성화한다.

일반적으로 Enforcing 모드를 사용해 엄격하게 리소스 보호를 수행하며, 개발 혹은 점진적 마이그레이션 환경에서는 Permissive 모드를 활용해 점차 정책 적용 범위를 넓힐 수 있다.

1. 애플리케이션 연동 리소스 서버로 동작하는 애플리케이션에서는 Keycloak이 발행한 액세스 토큰에 포함된 권한 정보를 바탕으로 접근을 제어한다.

* Bearer-only 형태의 리소스 서버라면, 클라이언트 애플리케이션(프론트엔드 등)에서 Keycloak으로부터 발급받은 토큰을 헤더에 실어 API 요청을 보내고, 리소스 서버는 해당 토큰을 Keycloak에 검증 요청한다.
* Confidential 클라이언트라면, 서버 측에서 Keycloak 라이브러리(adapters 또는 OAuth 라이브러리)를 사용해 로그인, 토큰 교환 등을 수행할 수 있다.

실제 요청을 처리하기 전에 Keycloak이 제공하는 권한 부여 엔드포인트 또는 라이브러리를 통해 “이 토큰이 특정 리소스·스코프에 대한 접근 권한을 갖는지”를 검사하고 적절히 대응한다.

1. UMA(User-Managed Access) 활용 더 세밀한 자원 접근 제어와 사용자 주도형 공유 모델이 필요하다면 UMA를 활성화할 수 있다. UMA는 자원 소유자가 제3자에게 자신의 자원을 직접 공유할 수 있게 하는 프로토콜로, Keycloak은 UMA 2.0을 지원한다. UMA를 사용하려면 “Authorization Settings”에서 “User-Managed Access” 기능을 활성화하고 정책과 퍼미션을 UMA 기반으로 정의한다.

Keycloak에서 리소스 서버를 설정하면, 애플리케이션이 보호해야 하는 엔드포인트 및 자원에 대한 접근 로직을 통합적으로 관리할 수 있다. 리소스·스코프·폴리시·퍼미션의 조합을 통해 다양한 조건을 세밀하게 정의할 수 있으며, 정책 집행 모드를 적절히 선택해 운영 환경에 맞춘 권한 부여 전략을 수립할 수 있다.