
# シングルサインオン

`oauth2Login()` を使うと、ユーザーはアプリケーションのパスワードではなく、アイデンティティプロバイダー (Keycloak、Google、GitHub、Auth0、Okta、Apple など) でログインします。ブラウザーはプロバイダーのログインページに送られ、ログインした状態で戻ってきます。これは PKCE を使う OAuth 2.0 の認可コードフローで、プロバイダーが対応していれば OpenID Connect も使います。サーバーがクライアントであり、トークンを保持します。

## 使う理由

パスワード、多要素ログイン、アカウントの復旧はプロバイダーが扱い、アプリケーションはパスワードを見ることがありません。サーバーが描画するページと Flutter Web アプリに使ってください。サーバーはアプリのバックエンド (BFF) としてトークンを保持し、ブラウザーは `HttpOnly` のセッション Cookie だけを持ちます。これは注入されたスクリプトからも読めません。Web ページにはトークンを安全に置く場所がないため、トークンは決して渡されません。ネイティブアプリは自分でログインしてアクセストークンを送ります。チェーンは両方を受け入れられます。

## 例

Spring Boot と同じく登録を設定すると、デフォルトのチェーンがそれを通じてブラウザーをログインさせます。

```properties
spring.security.oauth2.client.registration.keycloak.client-id=neon-web
spring.security.oauth2.client.registration.keycloak.client-secret=${KEYCLOAK_SECRET}
spring.security.oauth2.client.registration.keycloak.scope=openid,profile,email
spring.security.oauth2.client.provider.keycloak.issuer-uri=http://localhost:8180/realms/neon
```

プロバイダーはリダイレクト URI `{baseUrl}/login/oauth2/code/{registrationId}` (`http://localhost:8080/login/oauth2/code/keycloak`) を受け入れなければなりません。登録のプロパティは [spring_boot_starter_oauth2_client](../spring-boot-starter-oauth2-client/index.md) のものです。

または独自のチェーンで:

```dart
@Bean()
SecurityFilterChain web(HttpSecurity http, ClientRegistrationRepository registrations) => http
    .authorizeHttpRequests((auth) => auth
        .requestMatchers('/', '/public/**').permitAll()
        .anyRequest().authenticated())
    .oauth2Login((login) => login
        // 同じサイトの別のポートから配信される Flutter Web アプリ。
        .defaultSuccessUrl('http://localhost:5050/', alwaysUse: true))
    // ネイティブアプリはプロバイダーのアクセストークンを送る。
    .oauth2ResourceServer((server) => server.jwt())
    // ログアウトするとプロバイダーでのセッションも終了する。
    .logout((logout) => logout.logoutSuccessHandler(
        OidcClientInitiatedLogoutSuccessHandler(
          registrations,
          postLogoutRedirectUri: '{baseUrl}/',
        )))
    .build();

@RestController()
class MeController {
  @GetMapping('/api/me')
  Map<String, Object?> me(@AuthenticationPrincipal() OidcUser user) =>
      {'name': user.fullName, 'email': user.email};
}
```

## 何が起きるか

1. **ログインが必要なブラウザー**は、登録を列挙する生成されたログインページに向かいます。登録がちょうど一つで (フォームログインがない) 場合は、直接 `/oauth2/authorization/{registrationId}` に向かいます。`oauth2ResourceServer` もある場合、JSON を求めるプログラムは代わりに `401` を受け取り、Flutter Web アプリはそれを `/oauth2/authorization/keycloak` へのナビゲーションに変えます。
2. **`/oauth2/authorization/{registrationId}`** は新しい認可リクエスト (ランダムな `state`、PKCE の verifier、OpenID Connect の `nonce`) を署名付きの Cookie に保持し、プロバイダーにリダイレクトします。未知の登録は `400` です。
3. **プロバイダーは** `/login/oauth2/code/{registrationId}` に**リダイレクトして戻します**。保存されたリクエストはその `state` で取り出されて取り除かれます (コールバックは一度だけ動きます)。リクエストがない、`state` が異なる、または別の登録のコールバックは失敗します。プロバイダーからの `error` も、別の発行者の `iss` パラメーター (RFC 9207) も失敗します。
4. **コードはトークンエンドポイントで交換されます**。PKCE の verifier と正確なリダイレクト URI を使います。ID トークンの署名はプロバイダーの鍵でチェックされ、次に発行者、オーディエンス、`azp`、有効期限、`nonce` がチェックされます。ユーザー情報が読み込まれ、その `sub` は ID トークンのものと一致しなければなりません。権限 (`OIDC_USER`、`SCOPE_*`) は、`GrantedAuthoritiesMapper` Bean があればそれを通ります。
5. **セッション**は新しい ID を得て、ユーザーとトークン (`OAuth2AuthorizedClientRepository`) を保持し、ブラウザーは求めていたページ、なければ `defaultSuccessUrl` (`/`) に戻ります。その URL は設定です。リクエストの中の何物も、ブラウザーを別の場所に送ることはできません。失敗すると、理由なしで `/login?error` に向かいます。

## オプション

| `oauth2Login` のオプション | デフォルト |
|---|---|
| `loginPage(url)` | `/login` に生成されるページ |
| `defaultSuccessUrl(url, alwaysUse:)` | `/`。保存されたページが優先 |
| `failureUrl(url)`、`successHandler(h)`、`failureHandler(h)` | `/login?error`。リダイレクト |
| `authorizationEndpoint`: `baseUri`、`authorizationRequestRepository`、`authorizationRequestResolver` | `/oauth2/authorization`、署名付きの Cookie、`DefaultOAuth2AuthorizationRequestResolver` |
| `redirectionEndpoint`: `baseUri` (または `loginProcessingUrl`) | `/login/oauth2/code/*` |
| `tokenEndpoint`: `accessTokenResponseClient` | Bean、なければ `HttpTransport` を使うもの |
| `userInfoEndpoint`: `userService`、`oidcUserService`、`userAuthoritiesMapper` | Bean、なければ `DefaultOAuth2UserService`、`OidcUserService`、なし |
| `clientRegistrationRepository`、`authorizedClientRepository`、`authorizedClientService` | Bean |
| `idTokenDecoder` | `OidcIdTokenDecoder` Bean、なければ `OidcIdTokenDecoderFactory` (署名をチェックする) |

コントローラーはユーザーを `@AuthenticationPrincipal() OAuth2User user` (OpenID Connect では `OidcUser`) として受け取り、トークンを `OAuth2AuthorizedClientRepository` Bean から受け取ります。

## Cookie とサイト

- セッション Cookie は、プロバイダーからのトップレベルのリダイレクトであるコールバックに届かなければなりません。`Strict` ではなく `SameSite=Lax` (デフォルト) のままにしてください。
- Flutter Web アプリとサーバーは同じサイト (二つのポートを持つ `localhost`、`app.example.com` と `api.example.com`) になければならず、アプリのリクエストは Cookie (`credentials: 'include'`) を送り、`POST`、`PUT`、`DELETE` では CSRF トークンを送らなければなりません。

## フォーム POST での応答

登録に `response-mode=form_post` を指定すると (`apple` プロバイダーのデフォルト)、プロバイダーのページは `code` と `state` をフォームとしてコールバックに POST します。そのため、それらが URL、ログ、履歴に現れることはありません。

```properties
spring.security.oauth2.client.registration.keycloak.response-mode=form_post
```

- コールバックは、同じチェックで `POST` のボディ (最大 64 KB) から応答を受け取ります。フォーム POST のログインへの `GET`、クエリのログインへの `POST`、クエリとボディに分かれた応答は失敗し (`invalid_request`)、進行中のログインには手を触れません。
- コールバックの `POST` は CSRF から除外されます。署名付きの Cookie でブラウザーに結び付いた `state` が保護します。
- プロバイダーの POST はクロスサイトであり、`SameSite=None; Secure` の Cookie しか運びません。認可リクエストの Cookie は HTTPS ではそのように作られます。平文の HTTP ではログインは安全側に失敗し、ログに警告が出ます。フォーム POST でログインした後、ユーザーはデフォルトのページに到達します。

## Google でのログイン

```properties
spring.security.oauth2.client.registration.google.client-id=123-abc.apps.googleusercontent.com
spring.security.oauth2.client.registration.google.client-secret=${GOOGLE_SECRET}
```

`google` の登録は、そのエンドポイントを `CommonOAuth2Provider` から得ます (スコープは `openid profile email`)。Google Cloud で、リダイレクト URI `https://<your server>/login/oauth2/code/google` を持つ **Web アプリケーション**のクライアントを作成してください。

- **ロール:** Google はロールを送りません。`GrantedAuthoritiesMapper` Bean で与えてください。

```dart
@Component()
class Admins implements GrantedAuthoritiesMapper {
  Admins(this._users);
  final UserRepository _users;

  @override
  List<GrantedAuthority> mapAuthorities(Iterable<GrantedAuthority> authorities) => [
        ...authorities,
        for (final authority in authorities)
          if (authority is OidcUserAuthority && _users.isAdmin(authority.idToken.subject))
            SimpleGrantedAuthority('ROLE_ADMIN'),
      ];
}
```

- **ユーザーは `sub` で保持し**、メールアドレスでは決して保持しないでください。アドレスは持ち主が変わることがあり、別のプロバイダーは検証していないアドレスを送ることがあります。メールアドレスは `email_verified=true` の場合にだけ使ってください。
- **リフレッシュトークンはローテーションされません:** 安全に保管し、ユーザーがログアウトするかアカウントを削除したときに失効させてください。

## Apple でサインイン

```properties
spring.security.oauth2.client.registration.apple.client-id=books.neon.web
spring.security.oauth2.client.registration.apple.client-authentication-method=client_secret_post
spring.security.oauth2.client.registration.apple.client-secret-jwt.issuer=ABCDE12345
spring.security.oauth2.client.registration.apple.client-secret-jwt.key-id=XYZ987KEY1
spring.security.oauth2.client.registration.apple.client-secret-jwt.private-key-location=file:/run/secrets/AuthKey_XYZ987KEY1.p8
```

`apple` の登録 (追加されたもので、Spring にはありません) は、Apple のエンドポイント、スコープ `openid name email`、`client_secret_post`、ユーザー情報エンドポイントなし、`response-mode=form_post` を持ちます。Apple Developer アカウントでは、戻り URL `https://<your server>/login/oauth2/code/apple` を持つ **Services ID** (クライアント ID。Apple は `localhost` も IP も受け入れません)、Sign in with Apple を有効にした**鍵** (`.p8` ファイルとその鍵 ID)、そして **チーム ID** が必要です。

- **クライアントシークレット**は、その鍵で ES256 署名した JWT で、`client-secret-jwt.*` プロパティからリクエストごとに作られます (デフォルトは 1 時間、残りが 10 分の 1 になるまでキャッシュされます)。鍵がログに出ることはありません。
- **名前とメールアドレスは一度だけ**、最初のログインで、POST された `user` (`OidcUserService` の `userRequest.additionalParameters['user']`) で届きます。そのときに保存してください。これは署名されていません。これでユーザーが誰かを決めてはいけません。
- **HTTPS でのみ:** Apple は応答を POST で返します (フォーム POST)。
- App Store が求めるとおり、ユーザーがアカウントを削除したときはそのトークンを失効させてください。

## プロバイダーでのログアウト

`OidcClientInitiatedLogoutSuccessHandler(registrations, postLogoutRedirectUri: '{baseUrl}/')` はここでのセッションを終了し、次にブラウザーを ID トークンとともにプロバイダーの `end_session_endpoint` に送ります。そのためユーザーはそこでもログアウトされます。

## Spring (Java) との対応

```java
http.oauth2Login(login -> login.defaultSuccessUrl("http://localhost:5050/", true));
```

差分テスト (同じ偽のプロバイダーに対する同じブラウザーの手順) で Spring Security 7.1 と比較すると、結果は一致します。ただし、このスターターがより厳格な点は例外です。`iss` が発行者でないリダイレクトや、別の登録のコールバックへのリダイレクトは、ここでは失敗します (Spring はユーザーをログインさせます)。未知の登録は `400` です (Spring: `500`)。失敗したログインはセッションを作りません。ID トークンの署名は常にチェックされます。`apple` プロバイダー、`response-mode`、JWT のクライアントシークレットは追加されたものです。まだないもの: `oauth2Client()`、`@RegisteredOAuth2AuthorizedClient`、バックチャネルログアウト (`oidcLogout()`)。

## 関連項目

- [spring_boot_starter_oauth2_client](../spring-boot-starter-oauth2-client/index.md)
- [セッション](sessions.md)
- [JWT リソースサーバー](jwt.md)
