Keycloak Authorization Services — UMA 2.0 기반 세밀한 권한 제어

+------------------------------------------------------------+
|                Resource Server (client)                    |
|                                                            |
|  +-----------+     +---------+                             |
|  | Resource  |---->| Scope   |   "무엇을" (document:123)    |
|  | (문서,API) |     | (view,  |   "어떤 행위" (view, edit)   |
|  +-----------+     |  edit)  |                             |
|        ^           +---------+                             |
|        |                ^                                  |
|  +-----+----------------+-----+                            |
|  |       Permission           |  "리소스/스코프와 정책을 연결" |
|  | (resource-based /          |                            |
|  |  scope-based)              |                            |
|  +-------------+--------------+                            |
|                |                                           |
|  +-------------v--------------+                            |
|  |          Policy            |  "누가/어떤 조건에" (role,   |
|  | (role, user, group, time,  |   group, time, regex ...)  |
|  |  regex, aggregated ...)    |                            |
|  +----------------------------+                            |
+------------------------------------------------------------+

   +----------------+      (1) 요청       +---------------------+
   |    Client      +-------------------->+   Application       |
   | (브라우저/앱)    |                     |   = PEP             |
   +----------------+                     | (Policy Enforcement |
                                          |       Point)        |
                                          +----------+----------+
                                                     | (2) 결정 요청
                                                     |  (token / ticket)
                                          +----------v----------+
                                          |     Keycloak        |
                                          |   = PDP + PAP       |
                                          | (Policy Decision /  |
                                          |  Administration)    |
                                          +----------+----------+
                                                     | (3) Permit/Deny
                                                     |  (RPT 발급)
                                          +----------v----------+
                                          |   보호된 리소스       |
                                          +---------------------+

 Client                Resource Server (PEP)            Keycloak (PDP)
   |                          |                              |
   | (1) GET /api/doc/123     |                              |
   |  (access token, RPT없음) |                              |
   +------------------------->|                              |
   |                          | (2) permission ticket 요청    |
   |                          +----------------------------->|
   |                          |    POST /authz/protection/   |
   |                          |         permission           |
   |                          |<-----------------------------+
   | (3) 401 + WWW-Authenticate: UMA                         |
   |     (as_uri, ticket)     |                              |
   |<-------------------------+                              |
   |                          |                              |
   | (4) POST /token                                         |
   |     grant_type=uma-ticket, ticket=...                   |
   +-------------------------------------------------------->|
   |                          |        (5) 정책 평가          |
   | (6) RPT (권한 내장 토큰)   |                              |
   |<--------------------------------------------------------+
   |                          |                              |
   | (7) GET /api/doc/123 (RPT)                              |
   +------------------------->| (8) RPT 검증 후 응답          |
   |<-------------------------+                              |

POST /realms/myrealm/protocol/openid-connect/token HTTP/1.1
Host: sso.example.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:uma-ticket
&ticket=PERMISSION_TICKET_VALUE
&submit_request=false

POST /realms/myrealm/protocol/openid-connect/token HTTP/1.1
Host: sso.example.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:uma-ticket
&audience=document-service
&permission=document-resource#view
&response_mode=decision

{
  "result": true
}

{
  "authorization": {
    "permissions": [
      {
        "rsid": "8f4d2e1a-resource-uuid",
        "rsname": "document-123",
        "scopes": ["view", "comment"]
      }
    ]
  },
  "aud": "document-service",
  "exp": 1781234567
}

# 문서 생성 시 리소스 동적 등록
curl -X POST "https://sso.example.com/realms/myrealm/authz/protection/resource_set" \
  -H "Authorization: Bearer PAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "document-123",
    "type": "urn:document-service:resources:document",
    "owner": "jdoe",
    "ownerManagedAccess": true,
    "resource_scopes": ["view", "edit", "delete", "share"],
    "uris": ["/api/documents/123"]
  }'

<!-- pom.xml -->
<dependency>
  <groupId>org.keycloak</groupId>
  <artifactId>keycloak-policy-enforcer</artifactId>
  <version>26.0.0</version>
</dependency>

{
  "realm": "myrealm",
  "auth-server-url": "https://sso.example.com",
  "resource": "document-service",
  "credentials": {
    "secret": "CLIENT_SECRET_FROM_VAULT"
  },
  "http-method-as-scope": true,
  "lazy-load-paths": true,
  "enforcement-mode": "ENFORCING",
  "paths": [
    {
      "path": "/api/documents/*",
      "claim-information-point": {
        "claims": {
          "request.ip": "{request.remoteAddr}"
        }
      }
    },
    {
      "path": "/api/health",
      "enforcement-mode": "DISABLED"
    }
  ]
}

@Configuration
@EnableWebSecurity
public class SecurityConfig {

  @Bean
  public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
      .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
      .authorizeHttpRequests(authz -> authz.anyRequest().authenticated())
      .addFilterAfter(createPolicyEnforcerFilter(), BearerTokenAuthenticationFilter.class);
    return http.build();
  }

  private ServletPolicyEnforcerFilter createPolicyEnforcerFilter() {
    return new ServletPolicyEnforcerFilter(request -> {
      try (InputStream is = getClass().getResourceAsStream("/policy-enforcer.json")) {
        return JsonSerialization.readValue(is, PolicyEnforcerConfig.class);
      } catch (IOException e) {
        throw new UncheckedIOException(e);
      }
    });
  }
}

경험적 가이드라인
------------------------------------------------------
리소스 수 < 1만, 평가 QPS < 수백   → Keycloak authz 단독으로 충분
리소스 수 10만+, 관계 기반 판단    → 외부 ReBAC (OpenFGA) 병행 검토
정책이 코드/데이터 중심 (배포 파이프라인 정책 등) → OPA 병행 검토

패턴 A: Keycloak(인증+coarse) + OPA(fine-grained, 인프라 정책)
+--------+   JWT   +-------------+  input(JWT claims,  +-----+
| Client +-------->+ API Gateway +-------------------->+ OPA |
+--------+         |  / Service  |   resource attrs)   +-----+
                   +-------------+<--------------------+
                                     allow / deny

패턴 B: Keycloak(인증) + OpenFGA(관계 기반 인가)
+--------+   JWT   +----------+  check(user, relation, +---------+
| Client +-------->+ Service  +----------------------->+ OpenFGA |
+--------+         +----------+        object)         +---------+
                        |                                   ^
                        |  쓰기 시 관계 튜플 동기화            |
                        +-----------------------------------+