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)         +---------+
                        |                                   ^
                        |  書き込み時に関係タプルを同期        |
                        +-----------------------------------+