すべてのプロパティ
spring_boot_starter_security が読むすべてのプロパティを、プレフィックスごとにまとめています。各行には、キー、その型、デフォルト、働きを示します。スターターのメタデータ (lib/spring_gen/spring_metadata.json) にも同じ 15 個のキーが列挙されているため、補完機能のあるエディターでも候補に出ます。セキュリティのほとんどはコード (SecurityFilterChain Bean) で設定します。これらのプロパティは、Spring Boot がプロパティで設定するものと、いくつかの追加分を扱います。
使う理由
開発用のデフォルトのユーザー、API のアイデンティティプロバイダー、Cookie に署名する鍵は、環境ごとに変わります。これらがプロパティであるため、同じビルドを、ファイルや環境変数からの異なる値でどこでも実行できます。
例
ロードバランサーの背後にある本番の API です。Keycloak からのトークン、共有の Cookie の鍵、そのページ向けにユーザーごとに三つのセッション。
# lib/resources/application.yml
spring:
security:
cookie:
secret: ${SECURITY_COOKIE_SECRET} # 32 文字以上、すべてのインスタンスで同じ値
session:
maximum-sessions: 3
max-sessions-prevents-login: false
password-checks:
max-concurrent: 2
max-queued: 32
oauth2:
resourceserver:
jwt:
issuer-uri: https://login.example.com/realms/shop
audiences: orders-api
authorities-claim-name: roles
authority-prefix: ROLE_
principal-claim-name: preferred_username
同じ内容を .properties で:
# lib/resources/application.properties
spring.security.cookie.secret=${SECURITY_COOKIE_SECRET}
spring.security.session.maximum-sessions=3
spring.security.session.max-sessions-prevents-login=false
spring.security.password-checks.max-concurrent=2
spring.security.password-checks.max-queued=32
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://login.example.com/realms/shop
spring.security.oauth2.resourceserver.jwt.audiences=orders-api
spring.security.oauth2.resourceserver.jwt.authorities-claim-name=roles
spring.security.oauth2.resourceserver.jwt.authority-prefix=ROLE_
spring.security.oauth2.resourceserver.jwt.principal-claim-name=preferred_username
そして開発用:
# lib/resources/application-dev.properties
spring.security.user.name=admin
spring.security.user.password=change-me
spring.security.user.roles=ADMIN,USER
テキストの値は前後の空白が取り除かれ、空の値は未設定とみなされます。
spring.security.user: デフォルトのユーザー
アプリケーションが独自のユーザーを持たないときにスターターが作るユーザーです (フォームログインと HTTP Basic を参照)。
| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
spring.security.user.name |
String |
user |
デフォルトのユーザーの名前。 |
spring.security.user.password |
String |
なし: 起動時にログに出るランダムなもの | デフォルトのユーザーのパスワード。開発専用。{id} で始まらない限り {noop} として保存される。PasswordEncoder Bean がある場合は与えられたまま保存される (そのためすでにエンコードされている必要がある)。 |
spring.security.user.roles |
List<String> |
なし | デフォルトのユーザーのロール。ROLE_ プレフィックスなしで書く。 |
アプリケーションが UserDetailsService、AuthenticationProvider、AuthenticationManager、JwtDecoder の Bean を持つか、issuer-uri、jwk-set-uri、secret-key のどれかを設定するか、OAuth2 クライアントの登録を持つ場合、name か password が設定されていない限り、デフォルトのユーザーは作られません。
spring.security.filter
| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
spring.security.filter.order |
int |
-100 |
Web スターターのフィルターの中でのセキュリティフィルターの位置。順序の値が小さいものが先に実行される。 |
spring.security.session: ユーザーごとのセッション
Spring Boot にはなく、そこでは maximumSessions はコードでしか設定できません。ログインをセッションに保持するチェーン (フォームログイン、oauth2Login()) に適用されます。チェーン自身の sessionManagement((s) => s.maximumSessions(...)) が優先されます。セッション を参照してください。
| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
spring.security.session.maximum-sessions |
int |
10 |
ユーザーごとのセッションの最大数。-1 で上限なし。0 と -1 未満の値は起動を失敗させる。 |
spring.security.session.max-sessions-prevents-login |
bool |
false |
上限を超えるログインを、ユーザーの最も長く使われていないセッションを終了する代わりに拒否するかどうか。 |
spring.security.cookie
| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
spring.security.cookie.secret |
String |
プロセスのランダムな鍵 | セキュリティの Cookie (ログイン後に戻るページ、OAuth 2.0 の認可リクエスト) に署名する鍵。32 文字以上で、プロキシの背後のすべてのインスタンスで同じ値にする。再起動やサーバーをまたいでそれらの Cookie を有効に保つには設定する。 |
spring.security.oauth2.resourceserver.jwt: Bearer トークン
issuer-uri、jwk-set-uri、secret-key のどれかが設定されていると、デフォルトのチェーンはすべてのリクエストに有効な Bearer トークンを要求し、デフォルトのユーザーはなくなります。JWT リソースサーバー を参照してください。
| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
spring.security.oauth2.resourceserver.jwt.issuer-uri |
String |
なし | 受け入れる Bearer トークンの発行者。鍵はそのメタデータから来る。 |
spring.security.oauth2.resourceserver.jwt.jwk-set-uri |
String |
なし | 受け入れる Bearer トークンに署名する鍵のアドレス。 |
spring.security.oauth2.resourceserver.jwt.secret-key |
String、32 バイト以上 |
なし | HS256、HS384、HS512 で署名するプロバイダーと共有するシークレット。UTF-8 のバイト列として使われる。jwk-set-uri とは併用できない。一緒に設定した issuer-uri は iss と比較されるだけ。サーバー専用。 |
spring.security.oauth2.resourceserver.jwt.jws-algorithms |
List<String>: RS256、RS384、RS512、PS256、PS384、PS512、ES256、ES384、ES512、HS256、HS384、HS512 |
RS256。secret-key があれば HS256 |
jwk-set-uri で受け入れる署名アルゴリズム、または secret-key の一つの HMAC アルゴリズム (HS256、HS384、HS512)。issuer-uri だけの場合は使われない。未知の名前は起動を失敗させる。 |
spring.security.oauth2.resourceserver.jwt.audiences |
List<String> |
なし | Bearer トークンがそのいずれかを持たなければならないオーディエンス。空ならオーディエンスはチェックしない。 |
spring.security.oauth2.resourceserver.jwt.required-claims.<claim> |
String |
なし | すべての Bearer トークンのトップレベルのクレームが持たなければならない値 (数値や真偽値はそのテキスト)。そうでなければ 401。 |
spring.security.oauth2.resourceserver.jwt.require-expiry |
bool |
false |
exp クレームのない Bearer トークンを拒否するかどうか (401)。拒否しない場合、そのようなトークンは期限切れにならず、Spring Security と同じです。 |
spring.security.oauth2.resourceserver.jwt.authority-prefix |
String |
SCOPE_ |
トークンから読んだ各権限の前に付ける。 |
spring.security.oauth2.resourceserver.jwt.authorities-claim-name |
String |
なし: scope、なければ scp |
値がユーザーの権限になるクレーム。ちょうどその名前のクレームがなければ、ドットを含む名前は入れ子のオブジェクトへのパスになる (realm_access.roles)。 |
spring.security.oauth2.resourceserver.jwt.authorities-claim-delimiter |
String |
スペース | テキストのクレームを権限に分割する文字。 |
spring.security.oauth2.resourceserver.jwt.principal-claim-name |
String |
sub |
Bearer トークンのユーザーを表すクレーム。 |
他のパッケージから読むもの
| キー | パッケージ | デフォルト | 意味 |
|---|---|---|---|
spring.security.password-checks.max-concurrent |
spring_security_core | プロセッサー数の半分 | 同時に行うパスワードハッシュのチェックの最大数。 |
spring.security.password-checks.max-queued |
spring_security_core | max-concurrent の 8 倍 |
待機するチェックの最大数。超えると 503。 |
spring.security.oauth2.client.registration.*、.provider.* |
spring_boot_starter_oauth2_client | シングルサインオンの登録。 | |
server.session.max-sessions |
spring_boot_starter_web | 10000 |
全体のセッションの最大数。 |
server.session.cookie.same-site |
spring_boot_starter_web | lax |
シングルサインオンでは lax のままにする。 |
server.forward-headers-strategy |
spring_boot_starter_web | TLS プロキシの背後で、HSTS と DPoP の htu に必要。 |
Spring (Java) との対応
spring.security.user.*、spring.security.filter.order、spring.security.oauth2.resourceserver.jwt.* は Spring Boot の名前と意味を保っています。spring.security.session.*、spring.security.cookie.secret、spring.security.password-checks.*、そしてリソースサーバーの secret-key、required-claims、require-expiry、authorities-claim-name のパスは追加されたものです。まだないもの: spring.security.oauth2.resourceserver.jwt.public-key-location とオペークトークンのキー。