すべてのプロパティ

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 とオペークトークンのキー。

関連項目