フォームログインと HTTP Basic
formLogin() はブラウザーをフォームでログインさせます。フォームは /login に生成されるページか、独自のページです。httpBasic() はプログラムを Authorization: Basic ヘッダーでログインさせます。どちらも spring_security_core の AuthenticationManager で名前とパスワードをチェックするため、ユーザーは UserDetailsService Bean から来ます。
使う理由
人が使う Web アプリケーションには、ログインページ、ログイン後のセッション、ログアウトが必要です。スクリプトが使う API には、リクエストごとのログインが必要です。この二つの仕組みは、細部を正しく処理しながら両方に対応します。ログイン時にセッション ID が変わり、失敗の理由は決して表示されず、ログアウトは CSRF トークン付きの POST です。
例
@Bean()
SecurityFilterChain filterChain(HttpSecurity http) => http
.authorizeHttpRequests((auth) => auth
.requestMatchers('/sign-in', '/assets/**').permitAll()
.anyRequest().authenticated())
.formLogin((form) => form
.loginPage('/sign-in') // 独自のページ: 生成されるページはなくなる
.defaultSuccessUrl('/dashboard')
.failureUrl('/sign-in?error'))
.httpBasic((basic) => basic.realmName('Library'))
.logout((logout) => logout
.logoutSuccessUrl('/sign-in?bye')
.deleteCookies('SHOPSESSION'))
.build();
独自のページは、username、password、CSRF トークンを同じパスに POST します。
@GetMapping('/sign-in')
String signIn(ServerHttpRequest request) {
final csrf = csrfTokenOf(request)!;
return '''<form method="post" action="/sign-in">
<input name="username"> <input name="password" type="password">
<input type="hidden" name="${csrf.parameterName}" value="${csrf.token}">
<button>Sign in</button></form>''';
}
フォームログイン
| オプション | デフォルト | 意味 |
|---|---|---|
loginPage(url) |
/login に生成されるページ |
コントローラーが提供し、全員が到達できる独自のページ。 |
loginProcessingUrl(url) |
ログインページのパス | フォームの POST 先。 |
usernameParameter(name) |
username |
ユーザー名のフィールド。 |
passwordParameter(name) |
password |
パスワードのフィールド。 |
defaultSuccessUrl(url, alwaysUse:) |
/ |
ログイン前に保存されたページがないときに、ログイン後にブラウザーが向かう先。alwaysUse: true なら常にここへ向かう。 |
failureUrl(url) |
?error 付きのログインページ |
ログインに失敗した後にブラウザーが向かう先。 |
successHandler(handler) |
リダイレクト | ログインに別の方法で応答する。例えばスクリプト向けに JSON で。 |
failureHandler(handler) |
リダイレクト | 失敗したログインに別の方法で応答する。 |
何が起きるか:
- ログインが必要なブラウザーはログインページにリダイレクトされ、求めていたページが保存されます (署名付きの Cookie
REDIRECT_URIに)。 - フォームは CSRF トークンとともに処理 URL に POST されます。トークンなしで POST されたフォームは
403で拒否されます。 - 成功すると、セッションは新しい ID を得て (セッション固定攻撃の対策)、ユーザーを保持し、ブラウザーは保存されたページ、なければ
defaultSuccessUrlに戻ります。保存されたページは、このサイトのパスである場合にだけ使われます。 - 失敗すると、ブラウザーは
failureUrlに向かいます。ページは理由を決して示しません。「Bad credentials」は、未知のユーザー、誤ったパスワード、ロックされたアカウントのすべてを同じように表します。
生成されるページには、ユーザー名とパスワードのフィールド、CSRF トークン、そして oauth2Login() がある場合は登録ごとのリンクがあります。?error では「Bad credentials」、?logout では「You have been signed out」と表示します。
アプリケーションにユーザーが一人もいないままフォームログインや Basic ログインを使うと、起動が失敗します。
HTTP Basic
| オプション | デフォルト | 意味 |
|---|---|---|
realmName(realm) |
Realm |
WWW-Authenticate チャレンジのレルム。ブラウザーが表示することがある。 |
authenticationEntryPoint(entryPoint) |
Basic のチャレンジ | ログインが必要なクライアントが受け取るもの。 |
- ログインが必要な、クレデンシャルのないリクエストは
WWW-Authenticate: Basic realm="Realm"付きの401を受け取ります。スクリプト (X-Requested-With: XMLHttpRequest) は単なる401を受け取るため、ブラウザーのダイアログは表示されません。 - 8 192 文字より長い
Authorization: Basicヘッダー、または二度送られたヘッダーは、誤ったクレデンシャルとして失敗します。 - 失敗した Basic ログインはセッションを作りません。
- Basic を使う API には
statelessのセッションポリシーを使い、呼び出しの間にセッションが保持されないようにしてください。
ログアウト
| オプション | デフォルト | 意味 |
|---|---|---|
logoutUrl(url) |
/logout |
ログアウトのパス。 |
logoutSuccessUrl(url) |
?logout 付きのログインページ |
ログアウト後にブラウザーが向かう先。 |
logoutSuccessHandler(handler) |
リダイレクト | ログアウトに別の方法で応答する (例えば OidcClientInitiatedLogoutSuccessHandler)。 |
invalidateHttpSession(invalidate:) |
true |
セッションを、その中身ごと終了するかどうか。 |
deleteCookies(name, ...) |
なし | 最大三つの Cookie を期限切れにする。 |
addLogoutHandler(handler) |
組み込みのハンドラーより前に実行される。 | |
disable() |
ログアウトのエンドポイントを取り除く。 |
CSRF 保護が有効な間は、POST だけがログアウトさせます。GET は他のサイトのリンクや画像から引き起こされうるためです。フォームログインが生成されるページを使う場合、GET /logout は CSRF トークン付きでログアウトを POST するボタンのある確認ページを表示します。CSRF が無効なら、GET、POST、PUT、DELETE のいずれでもログアウトします。ログアウトは、ログインしていたユーザーについて LogoutSuccessEvent を発行します。
デフォルトのユーザー
独自のユーザーがなければ、スターターがプロパティから一人作ります。
| プロパティ | デフォルト | 意味 |
|---|---|---|
spring.security.user.name |
user |
名前。 |
spring.security.user.password |
起動時にログに出るランダムなもの | パスワード。開発専用。 |
spring.security.user.roles |
なし | ロール。ROLE_ なしで書く。 |
- パスワードは、すでに
{id}で始まっていない限り{noop}として保存されます。PasswordEncoderBean がある場合は与えられたまま保存されるため、すでにエンコードされている必要があり、生成されたパスワードではログインできません。 - アプリケーションが
UserDetailsService、AuthenticationProvider、AuthenticationManager、JwtDecoderの Bean、JWT のプロパティ、または OAuth2 クライアントの登録を持った時点で、デフォルトのユーザーは消えます (spring.security.user.nameか.passwordが設定されている場合を除きます)。
一つのチェーンだけのユーザー
http.userDetailsService(service) や http.authenticationManager(manager) は、チェーンに独自のユーザーを与えます。そうしたユーザーは、ログイン時に古いパスワードハッシュがアップグレードされることはありません。UserDetailsService Bean のユーザーはアップグレードされます。
Spring (Java) との対応
http.formLogin(form -> form.loginPage("/sign-in").defaultSuccessUrl("/dashboard"))
.httpBasic(basic -> basic.realmName("Library"));
オプションは Spring のものです。まだないもの: rememberMe()、oneTimeTokenLogin()、パスキー、x509()、ユーザーの切り替え。