
# JWT リソースサーバー

ユーザーがアイデンティティプロバイダー (Keycloak、Auth0、Okta、Google など) でログインする API は、リクエストごとに `Authorization: Bearer` で JSON Web Token を受け取り、それをチェックしなければなりません。プロバイダーと API のオーディエンスを設定すると、すべてのリクエストに有効なトークンが必要になります。スコープはルールのための `SCOPE_x` 権限になります。

## 使う理由

トークンを使うと、API はセッションを保持せず、パスワードを見ることもありません。プロバイダーがユーザーをログインさせ、API は署名をチェックします。このチェックには多くの罠があります (`alg: none`、HMAC の秘密鍵として使われる RSA 鍵、自分の鍵を持ち込むトークン、アクセストークンとして使われる ID トークン)。スターターは Spring Security 7 と同じく、これを厳格に行います。

## 例

```properties
# lib/resources/application.properties
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://login.example.com/realms/shop
spring.security.oauth2.resourceserver.jwt.audiences=orders-api
```

これで十分です。デフォルトのチェーンはすべてのリクエストに有効な Bearer トークンを要求するようになり、デフォルトのユーザーはなくなります。または独自のチェーンで:

```dart
@Bean()
SecurityFilterChain api(HttpSecurity http) => http
    .authorizeHttpRequests((auth) => auth
        .requestMatchersFor(HttpMethod.get, ['/api/orders/**']).hasAuthority('SCOPE_orders.read')
        .requestMatchersFor(HttpMethod.post, ['/api/orders/**']).hasAuthority('SCOPE_orders.write')
        .anyRequest().authenticated())
    .oauth2ResourceServer((server) => server.jwt())
    .sessionManagement((s) => s.sessionCreationPolicy(SessionCreationPolicy.stateless))
    .build();

@RestController()
class OrderController {
  @GetMapping('/api/orders/mine')
  Future<List<Order>> mine(@AuthenticationPrincipal() Jwt jwt) =>
      orders.findByOwner(jwt.subject!);
}
```

```bash
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." localhost:8080/api/orders/mine
```

## プロパティ

| キー | デフォルト | 意味 |
|---|---|---|
| `spring.security.oauth2.resourceserver.jwt.issuer-uri` | なし | 受け入れるトークンの発行者。その鍵は発行者のメタデータ (`/.well-known/openid-configuration`) から来る。 |
| `spring.security.oauth2.resourceserver.jwt.jwk-set-uri` | なし | プロバイダーの公開鍵の URL。 |
| `spring.security.oauth2.resourceserver.jwt.secret-key` | なし | HS256、HS384、HS512 で署名するプロバイダーと共有するシークレット。UTF-8 のバイト列として使われる。下の「共有シークレット」を参照。Spring Boot にはない。 |
| `spring.security.oauth2.resourceserver.jwt.jws-algorithms` | `RS256`。`secret-key` があれば `HS256` | `jwk-set-uri` で受け入れる署名アルゴリズム: `RS256`、`RS384`、`RS512`、`PS256`、`PS384`、`PS512`、`ES256`、`ES384`、`ES512`。`secret-key` では、そのシークレットの一つのアルゴリズム: `HS256`、`HS384`、`HS512`。未知の名前は起動を失敗させる。 |
| `spring.security.oauth2.resourceserver.jwt.audiences` | なし | トークンは `aud` にこのいずれかを含まなければならない。空ならオーディエンスはチェックしない。 |
| `spring.security.oauth2.resourceserver.jwt.required-claims.<claim>` | なし | すべてのトークンのトップレベルのクレームが持たなければならない値。下の「必須のクレーム」を参照。Spring Boot にはない。 |
| `spring.security.oauth2.resourceserver.jwt.require-expiry` | `false` | `exp` クレームのないトークンを拒否するかどうか。オフでは、そのようなトークンは期限切れにならず、Spring Security と同じです。トークンが必ず期限切れになる発行者向けに設定してください。Spring Boot にはない。 |
| `spring.security.oauth2.resourceserver.jwt.authority-prefix` | `SCOPE_` | トークンから読んだ各権限の前に付ける。 |
| `spring.security.oauth2.resourceserver.jwt.authorities-claim-name` | `scope`、なければ `scp` | 値が権限になるクレーム。クレームの名前、または入れ子のオブジェクトへのパス (`realm_access.roles`)。 |
| `spring.security.oauth2.resourceserver.jwt.authorities-claim-delimiter` | スペース | テキストのクレームを権限に分割する。 |
| `spring.security.oauth2.resourceserver.jwt.principal-claim-name` | `sub` | ユーザーを表すクレーム (`Authentication.name`)。 |

- `jwk-set-uri` では、発行者 (`issuer-uri` も設定されている場合) とオーディエンスがチェックされます。
- `issuer-uri` だけの場合、`jws-algorithms` は使われません。アルゴリズムはプロバイダーの鍵が許すものです。
- `secret-key` では、一緒に設定した `issuer-uri` はトークンの `iss` と比較されるだけで、何も取得されません。
- 三つのどれかがあれば、デフォルトのチェーンはすべてのリクエストに有効な Bearer トークンを要求します。

## チェックされること

順番に行われ、どの失敗も `WWW-Authenticate: Bearer error="invalid_token"` 付きの `401` になります。

1. **解析**は厳格です。`alg: none` は決して受け入れず、`crit` ヘッダーも、入れ子や暗号化されたトークンも受け入れず、最大 64 KiB です。
2. **アルゴリズム**は受け入れるものの一つで、鍵に合っていなければなりません。そのため RSA の公開鍵が HMAC の秘密鍵として使われることはありません。
3. **署名**は、トークンの `kid` の鍵でチェックします (共有シークレットは鍵が一つなので、ヘッダーに `kid` があってもトークンを拒否する理由にならず、署名で決まります)。トークン自身が示す鍵 (`jku`、`jwk`、`x5u`) は無視されます。トークンが自分の鍵を持ち込むことはできません。
4. **タイプ:** Spring Security 7 と同じく、`typ` は `JWT` (大文字小文字を問わない) か、ないことが必要です。ログアウトトークン、セキュリティイベント、DPoP の証明、`at+jwt` は拒否されます。アクセストークンのタイプを `at+jwt` とするプロバイダーには、バリデーターが `JwtTypeValidator(['at+jwt', 'JWT'], allowEmpty: true)` で始まる `JwtDecoder` Bean を宣言してください。
5. **有効期間:** `exp` と `nbf` を、60 秒の時計のずれを許してチェックします (`exp` のないトークンは、`require-expiry` が `true` でない限り通ります)。次に、設定に従って発行者とオーディエンス、`required-claims`、アプリケーションの `OAuth2TokenValidator<Jwt>` の Bean をチェックします。
6. **証明書のバインドなし:** クライアント証明書にバインドされたトークン (`cnf.x5t#S256`、RFC 8705) は、ここではバインドをチェックできないため拒否されます。

ルールが求める権利を持たない有効なトークンは、`error="insufficient_scope"` 付きの `403` を受け取ります。

## プロバイダーの鍵

- 鍵は 5 分間キャッシュされます。
- 未知の `kid` を持つトークンは鍵を再取得させますが、30 秒に一回までです。そのため、でっち上げた ID でプロバイダーに大量のリクエストを送ることはできません。
- 失敗した取得も、発行者のメタデータの検索の失敗も数に入ります。プロバイダーが停止している間、トークンは `401` で失敗し (または以前に取得した鍵を使い続け)、プロバイダーへの試行は 30 秒に一回です。

## 共有シークレット

プロバイダーによっては、鍵ペアの代わりに、API と共有するシークレットでトークンに署名します (HS256)。`secret-key` はそのシークレットで、UTF-8 のバイト列として使われます。

```properties
spring.security.oauth2.resourceserver.jwt.secret-key=${JWT_SECRET}
# optional: only compared with the token's iss, nothing is fetched
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://login.example.com
```

シークレットを持つ人は、任意のユーザーのトークンに署名できます。サーバーだけに置くものです。クライアントアプリケーション (誰でも読める Flutter アプリや Web アプリ) には決して入れず、リポジトリのファイルからではなく、環境変数から取ってください。

次の場合、アプリケーションは起動しません。

- `jwk-set-uri` も設定されている (鍵の出所が二つ)。
- `jws-algorithms` が、`HS256` (デフォルト)、`HS384`、`HS512` のどれか一つ以外を示している。
- シークレットがアルゴリズムのハッシュより短い: 32、48、64 バイト。

通るのは、その一つのアルゴリズムで、そのシークレットで署名されたトークンだけです。RS256 や ES256 のトークンは、署名が何であっても拒否されます。クレームのチェックは、鍵セットの場合と同じです。

## 必須のクレーム

`required-claims` は、すべてのトークンが持たなければならないクレームと、それぞれが等しくなければならない値を示します。鍵を設定する三つの方法のどれとでも使えます。

```properties
spring.security.oauth2.resourceserver.jwt.required-claims.role=authenticated
spring.security.oauth2.resourceserver.jwt.required-claims[https://example.com/tenant]=shop
```

- クレームはトップレベルのもので、完全一致で比較されます。
- 数値や真偽値のクレームは、そのテキスト (`true`、`2`) として比較されます。
- クレームのないトークン、別の値を持つトークン、そこにリストやオブジェクトを持つトークンは、他の無効なトークンと同じように拒否されます。`401` の `invalid_token` です。

## 有効期限を必須にする

`exp` のないトークンは期限切れにならず、デフォルトでは Spring Security と同じく受け入れられます。`require-expiry=true` にすると、ほかの無効なトークンと同じように拒否されます (`401` の `invalid_token`)。鍵を設定する三つの方法のどれとでも使えます。

```properties
spring.security.oauth2.resourceserver.jwt.require-expiry=true
```

## 独自のバリデーター

すべての `OAuth2TokenValidator<Jwt>` の Bean は、Spring Boot と同じく、自動構成されたデコーダーのチェックに加えられます。上のチェックが置き換えられることはありません。

```dart
@Component()
class TenantValidator implements OAuth2TokenValidator<Jwt> {
  @override
  OAuth2TokenValidatorResult validate(Jwt token) =>
      token.claims['tenant'] == 'shop'
      ? OAuth2TokenValidatorResult.success
      : OAuth2TokenValidatorResult.failure(
          const OAuth2Error('invalid_token', 'The tenant is not shop'),
        );
}
```

## 権限とプリンシパル

スコープは `SCOPE_x` 権限になります。ルールは `hasAuthority('SCOPE_orders.read')` のように書きます。`Authentication` は `JwtAuthenticationToken` で、そのプリンシパルは `Jwt` です。

| `Jwt` のメンバー | 意味 |
|---|---|
| `tokenValue`、`headers`、`claims` | トークン。 |
| `subject`、`issuer`、`audience`、`id`、`expiresAt` | 標準のクレーム。 |
| `getClaimAsString(name)`、`getClaimAsStringList(name)`、`getClaimAsInstant(name)` | 型付きでのクレームの読み取り。 |

メソッドセキュリティの式は `principal.claims['tenant']` を読めます。

別のクレームからロールを読むには、その名前を指定します。トークンにちょうどその名前のクレームがないとき、ドットを含む名前は入れ子のオブジェクトへのパスになります。`realm_access.roles` は `realm_access` の中の `roles` を読み (Keycloak)、`app_metadata.roles` は `app_metadata` の中の `roles` を読みます (Supabase)。途中の部分がない、またはオブジェクトでない場合、権限はありません。

```properties
spring.security.oauth2.resourceserver.jwt.authorities-claim-name=realm_access.roles
spring.security.oauth2.resourceserver.jwt.authority-prefix=ROLE_
```

コードで同じことをするには、`JwtAuthenticationConverter` Bean を宣言するか、チェーンに設定します。

```dart
.oauth2ResourceServer((s) => s.jwt((j) => j.jwtAuthenticationConverter(
    const JwtAuthenticationConverter(
      authoritiesConverter: JwtGrantedAuthoritiesConverter(
        authoritiesClaimName: 'roles',
        authorityPrefix: 'ROLE_',
      ),
    ))))
```

## JwtDecoder Bean

`JwtDecoder` Bean は、プロパティから組み立てられるものを置き換えます。

```dart
@Bean()
JwtDecoder jwtDecoder() => NimbusJwtDecoder.withJwkSetUri(
      Uri.parse('https://login.example.com/jwks'),
      jwsAlgorithms: {JwsAlgorithm.rs256, JwsAlgorithm.es256},
      validator: DelegatingOAuth2TokenValidator([
        JwtValidators.createDefaultWithIssuer('https://login.example.com'),
        JwtAudienceValidator(['orders-api']),
      ]),
    );
```

| ファクトリー | 鍵 |
|---|---|
| `NimbusJwtDecoder.withJwkSetUri(uri, jwsAlgorithms:, validator:)` | プロバイダーの JWK Set。デフォルトは RS256。HMAC はなし。 |
| `NimbusJwtDecoder.withPublicKey(key, ...)` | 一つの RSA 公開鍵。 |
| `NimbusJwtDecoder.withSecretKey(secret, macAlgorithm:, ...)` | 共有の秘密鍵。HS256 から HS512。秘密鍵はハッシュと少なくとも同じビット数を持たなければならない。 |
| `NimbusJwtDecoder.withJwkSource(source, ...)` | 独自のソースの鍵。 |
| `NimbusJwtDecoder.fromIssuerLocation(issuer)` | 発行者のメタデータから。 |

バリデーターがなければ、タイプと有効期間だけがチェックされます (`JwtValidators.createDefault()`)。発行者とオーディエンスのチェックは自分で追加してください。バリデーター: `JwtTimestampValidator`、`JwtIssuerValidator`、`JwtAudienceValidator`、`JwtClaimValidator`、`JwtTypeValidator`。`DelegatingOAuth2TokenValidator` で組み合わせます。

## リソースサーバーのオプション

| オプション | 意味 |
|---|---|
| `jwt((j) => ...)` | 必須。`j.decoder(decoder)`、`j.jwtAuthenticationConverter(converter)`、`j.authenticationManager(manager)`。 |
| `authenticationEntryPoint(entryPoint)` | 有効なトークンを持たないクライアントが、`401` の代わりに受け取るもの。 |
| `accessDeniedHandler(handler)` | 拒否されたトークン保持者が、`403` の代わりに受け取るもの。 |
| `bearerTokenResolver(DefaultBearerTokenResolver(allowUriQueryParameter: true))` | ブラウザーからのサーバー送信イベントのために、`GET` リクエストのクエリからも `access_token` を読む。そうしたトークンがリクエストを CSRF から除外することはない。 |

`jwt()` が呼ばれていないか、`JwtDecoder` がない場合、`build()` は失敗します。ヘッダーにトークンを持つリクエストには CSRF トークンが不要です ([CSRF](csrf.md) を参照)。DPoP にバインドされたトークンも同じチェーンで受け入れられます ([DPoP にバインドされたトークン](dpop.md) を参照)。

## Spring (Java) との対応

```properties
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://login.example.com/realms/shop
spring.security.oauth2.resourceserver.jwt.audiences=orders-api
```

プロパティとクラスは Spring Boot と Spring Security のものです。四つは追加されたものです。`secret-key` (Spring Boot では、共有シークレットには `JwtDecoder` Bean が必要です)、`required-claims`、`require-expiry`、そして `authorities-claim-name` での入れ子のオブジェクトへのパス (Spring の `JwtGrantedAuthoritiesConverter` はトップレベルのクレームしか読みません)。`Jwt` は `spring_security_core` の [`OAuth2Token`](../spring-security-core/login-session.md) を実装します。まだないもの: オペークトークン、一つのチェーンでの複数の発行者 (`JwtIssuerAuthenticationManagerResolver`)、フォームボディの Bearer トークン、`jwt.public-key-location`、証明書にバインドされたトークン (Web スターターがクライアント証明書をフィルターに渡すようになるまで拒否されます)。

## 関連項目

- [DPoP にバインドされたトークン](dpop.md)
- [すべてのプロパティ](properties.md)
- [spring_boot_starter_oauth2_client](../spring-boot-starter-oauth2-client/index.md)
- [Supabase: サーバーのセキュリティ](../spring-boot-starter-supabase/security.md)
