フォームログインと 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) リダイレクト 失敗したログインに別の方法で応答する。

何が起きるか:

  1. ログインが必要なブラウザーはログインページにリダイレクトされ、求めていたページが保存されます (署名付きの Cookie REDIRECT_URI に)。
  2. フォームは CSRF トークンとともに処理 URL に POST されます。トークンなしで POST されたフォームは 403 で拒否されます。
  3. 成功すると、セッションは新しい ID を得て (セッション固定攻撃の対策)、ユーザーを保持し、ブラウザーは保存されたページ、なければ defaultSuccessUrl に戻ります。保存されたページは、このサイトのパスである場合にだけ使われます。
  4. 失敗すると、ブラウザーは 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 のチャレンジ ログインが必要なクライアントが受け取るもの。

ログアウト

オプション デフォルト 意味
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_ なしで書く。

一つのチェーンだけのユーザー

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()、ユーザーの切り替え。

関連項目