JWT リソースサーバー

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

使う理由

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

例

# 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 トークンを要求するようになり、デフォルトのユーザーはなくなります。または独自のチェーンで:

@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!);
}
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)。

チェックされること

順番に行われ、どの失敗も 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 を受け取ります。

プロバイダーの鍵

共有シークレット

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

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 アプリ) には決して入れず、リポジトリのファイルからではなく、環境変数から取ってください。

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

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

必須のクレーム

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

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

有効期限を必須にする

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

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

独自のバリデーター

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

@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)。途中の部分がない、またはオブジェクトでない場合、権限はありません。

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

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

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

JwtDecoder Bean

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

@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 を参照)。DPoP にバインドされたトークンも同じチェーンで受け入れられます (DPoP にバインドされたトークン を参照)。

Spring (Java) との対応

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 を実装します。まだないもの: オペークトークン、一つのチェーンでの複数の発行者 (JwtIssuerAuthenticationManagerResolver)、フォームボディの Bearer トークン、jwt.public-key-location、証明書にバインドされたトークン (Web スターターがクライアント証明書をフィルターに渡すようになるまで拒否されます)。

関連項目