
# フォームログインと HTTP Basic

`formLogin()` はブラウザーをフォームでログインさせます。フォームは `/login` に生成されるページか、独自のページです。`httpBasic()` はプログラムを `Authorization: Basic` ヘッダーでログインさせます。どちらも `spring_security_core` の `AuthenticationManager` で名前とパスワードをチェックするため、ユーザーは `UserDetailsService` Bean から来ます。

## 使う理由

人が使う Web アプリケーションには、ログインページ、ログイン後のセッション、ログアウトが必要です。スクリプトが使う API には、リクエストごとのログインが必要です。この二つの仕組みは、細部を正しく処理しながら両方に対応します。ログイン時にセッション ID が変わり、失敗の理由は決して表示されず、ログアウトは CSRF トークン付きの `POST` です。

## 例

```dart
@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 します。

```dart
@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 のチャレンジ | ログインが必要なクライアントが受け取るもの。 |

- ログインが必要な、クレデンシャルのないリクエストは `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}` として保存されます。`PasswordEncoder` Bean がある場合は与えられたまま保存されるため、すでにエンコードされている必要があり、生成されたパスワードではログインできません。
- アプリケーションが `UserDetailsService`、`AuthenticationProvider`、`AuthenticationManager`、`JwtDecoder` の Bean、JWT のプロパティ、または OAuth2 クライアントの登録を持った時点で、デフォルトのユーザーは消えます (`spring.security.user.name` か `.password` が設定されている場合を除きます)。

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

`http.userDetailsService(service)` や `http.authenticationManager(manager)` は、チェーンに独自のユーザーを与えます。そうしたユーザーは、ログイン時に古いパスワードハッシュがアップグレードされることはありません。`UserDetailsService` Bean のユーザーはアップグレードされます。

## Spring (Java) との対応

```java
http.formLogin(form -> form.loginPage("/sign-in").defaultSuccessUrl("/dashboard"))
    .httpBasic(basic -> basic.realmName("Library"));
```

オプションは Spring のものです。まだないもの: `rememberMe()`、`oneTimeTokenLogin()`、パスキー、`x509()`、ユーザーの切り替え。

## 関連項目

- [認証](../spring-security-core/authentication.md)
- [CSRF](csrf.md)
- [セッション](sessions.md)
