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)。 |
jwk-set-uriでは、発行者 (issuer-uriも設定されている場合) とオーディエンスがチェックされます。issuer-uriだけの場合、jws-algorithmsは使われません。アルゴリズムはプロバイダーの鍵が許すものです。secret-keyでは、一緒に設定したissuer-uriはトークンのissと比較されるだけで、何も取得されません。- 三つのどれかがあれば、デフォルトのチェーンはすべてのリクエストに有効な Bearer トークンを要求します。
チェックされること
順番に行われ、どの失敗も WWW-Authenticate: Bearer error="invalid_token" 付きの 401 になります。
- 解析は厳格です。
alg: noneは決して受け入れず、critヘッダーも、入れ子や暗号化されたトークンも受け入れず、最大 64 KiB です。 - アルゴリズムは受け入れるものの一つで、鍵に合っていなければなりません。そのため RSA の公開鍵が HMAC の秘密鍵として使われることはありません。
- 署名は、トークンの
kidの鍵でチェックします (共有シークレットは鍵が一つなので、ヘッダーにkidがあってもトークンを拒否する理由にならず、署名で決まります)。トークン自身が示す鍵 (jku、jwk、x5u) は無視されます。トークンが自分の鍵を持ち込むことはできません。 - タイプ: Spring Security 7 と同じく、
typはJWT(大文字小文字を問わない) か、ないことが必要です。ログアウトトークン、セキュリティイベント、DPoP の証明、at+jwtは拒否されます。アクセストークンのタイプをat+jwtとするプロバイダーには、バリデーターがJwtTypeValidator(['at+jwt', 'JWT'], allowEmpty: true)で始まるJwtDecoderBean を宣言してください。 - 有効期間:
expとnbfを、60 秒の時計のずれを許してチェックします (expのないトークンは、require-expiryがtrueでない限り通ります)。次に、設定に従って発行者とオーディエンス、required-claims、アプリケーションのOAuth2TokenValidator<Jwt>の Bean をチェックします。 - 証明書のバインドなし: クライアント証明書にバインドされたトークン (
cnf.x5t#S256、RFC 8705) は、ここではバインドをチェックできないため拒否されます。
ルールが求める権利を持たない有効なトークンは、error="insufficient_scope" 付きの 403 を受け取ります。
プロバイダーの鍵
- 鍵は 5 分間キャッシュされます。
- 未知の
kidを持つトークンは鍵を再取得させますが、30 秒に一回までです。そのため、でっち上げた ID でプロバイダーに大量のリクエストを送ることはできません。 - 失敗した取得も、発行者のメタデータの検索の失敗も数に入ります。プロバイダーが停止している間、トークンは
401で失敗し (または以前に取得した鍵を使い続け)、プロバイダーへの試行は 30 秒に一回です。
共有シークレット
プロバイダーによっては、鍵ペアの代わりに、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 アプリ) には決して入れず、リポジトリのファイルからではなく、環境変数から取ってください。
次の場合、アプリケーションは起動しません。
jwk-set-uriも設定されている (鍵の出所が二つ)。jws-algorithmsが、HS256(デフォルト)、HS384、HS512のどれか一つ以外を示している。- シークレットがアルゴリズムのハッシュより短い: 32、48、64 バイト。
通るのは、その一つのアルゴリズムで、そのシークレットで署名されたトークンだけです。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
- クレームはトップレベルのもので、完全一致で比較されます。
- 数値や真偽値のクレームは、そのテキスト (
true、2) として比較されます。 - クレームのないトークン、別の値を持つトークン、そこにリストやオブジェクトを持つトークンは、他の無効なトークンと同じように拒否されます。
401のinvalid_tokenです。
有効期限を必須にする
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 スターターがクライアント証明書をフィルターに渡すようになるまで拒否されます)。