
# アプリのログイン

`OAuth2LoginService` はアプリのログインです。スマートフォンやデスクトップでは `NativeOAuth2LoginService` で、OAuth 2.0 for Native Apps (RFC 8252) の認可コードフローと PKCE を使うパブリッククライアントであり、OAuth2 クライアントの登録 (`spring.security.oauth2.client.*`) の上に組み立てられています。三つの呼び出し `login`、`restore`、`logout` が、ログインの一生を担います。

## 使う理由

Spring Security は、サーバー上でブラウザーをログインさせます。その `oauth2Login()` はコンフィデンシャルクライアントで、トークンをセッションに保持します。アプリはシークレットを保持できない (誰でもバイナリーから取り出せる) ので、PKCE で保護されたパブリッククライアントとして自分でログインし、トークンをデバイスに保持します。このサービスは、Spring のサーバー側のログインのすべてのチェックとともにそれを行うので、アプリのコードは三行のままです。

## 例

```dart
@Service()
class Account {
  Account(this._login);

  final OAuth2LoginService _login;

  // 起動時: 前回のユーザーを、新しいトークンとともに。
  Future<Authentication?> start() => _login.restore();

  // システムのログインウィンドウ。ユーザー、または例外。
  Future<Authentication?> signIn() => _login.login('keycloak');

  // トークンを取り消して忘れる。プロバイダーのセッションは残る。
  Future<void> signOut() => _login.logout();

  // 「アカウントの切り替え」: プロバイダーのセッションも終わらせる。
  Future<void> switchAccount() => _login.logout(endSession: true);
}
```

```yaml
spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: neon-app
            scope: openid,profile,email
            redirect-uri: dev.neon.books:/oauth2/callback
        provider:
          keycloak:
            issuer-uri: https://id.neon.books/realms/neon
```

`client-secret` は省略してください。そうすると登録はパブリッククライアント (`client-authentication-method=none`) になり、PKCE がそのコードを保護します。

## プラットフォームごと

| プラットフォーム | ログインウィンドウ | リダイレクト URI | トークン |
|---|---|---|---|
| iOS、macOS | `ASWebAuthenticationSession` (Safari のシート)。`native-sign-in=apple` では Sign in with Apple 独自のシート | アプリのスキーム (`neonbooks:/oauth2/callback`)、または関連付けられたドメインを使う `https` (iOS 17.4、macOS 14.4) | キーチェーン |
| Android | Custom Tab。リダイレクトはパッケージのアクティビティが受け取る | アプリのスキーム、または `https` の App Link | Android Keystore |
| Windows、Linux | デフォルトのブラウザー。リダイレクトは `127.0.0.1` 上の一回限りのサーバーで受け取る (RFC 8252 §7.3) | `http://127.0.0.1/callback` (任意の空いているポート) | DPAPI、Secret Service |
| Web | なし: ページはサーバーのログインへ行く | サーバーのもの | なし: サーバーが保持する ([Web: サーバーがログインする](web-server-mode.md) を参照) |

Windows と Linux では、プロバイダーは任意のポートのループバックのリダイレクトを受け付けなければなりません (Keycloak: `http://127.0.0.1/*`、Google: デスクトップのクライアント)。ポート付きのリダイレクト URI (`http://127.0.0.1:8400/callback`) はそれを保ちます。各プラットフォームのセットアップは [トークンとログインウィンドウ](tokens-and-login-window.md) にあります。

## login

`login('keycloak')`:

1. 認可リクエストを組み立てます。ランダムな `state` (`Random.secure()` の 32 バイト)、PKCE のベリファイア (64 バイト) とその `S256` のチャレンジ、そして `openid` ではランダムな `nonce` (その SHA-256 ハッシュが送られます) です。
2. `AuthorizationWindow` でプロバイダーのログインページを開き、戻ってくるリダイレクトを待ちます。
3. リダイレクトをチェックします。リダイレクト URI に戻ってきたこと、送った `state` (そうでなければ `invalid_state_parameter`)、存在するか告知されている場合は `iss` パラメーター (RFC 9207、そうでなければ `invalid_issuer`)、そして `error` (`access_denied` など) または `code` です。
4. ベリファイアと実際に使ったリダイレクト URI でコードを交換します。
5. OpenID Connect では、ID トークン (issuer、audience、`azp`、60 秒のずれを許した有効期限と発行時刻、nonce) をチェックし、ユーザー情報を読み込みます。その `sub` は ID トークンのものと一致しなければなりません。
6. 権限を対応付け (`OIDC_USER` または `OAUTH2_USER`、`SCOPE_<scope>`、次に `GrantedAuthoritiesMapper` Bean)、`OAuth2AuthenticationToken` を `SecurityContextHolder` に置き、トークンを `OAuth2AuthorizedClientService` に保存し、`AuthenticationSuccessEvent` を発行します。

どの失敗も、`error.errorCode` が理由を示す `OAuth2AuthenticationException` です。閉じられたページは `AuthorizationCancelledException` です。追加のパラメーター (`prompt=login`) は `additionalParameters` に入れます。

ID トークンの署名はチェックされません。TLS 上でトークンエンドポイントから直接来るもので、OpenID Connect Core §3.1.3.7 がそれを許しているからです。それでも `alg: none` のトークンは拒否されます。署名もチェックするには、`OidcIdTokenDecoder` Bean を宣言してください。

## restore

起動時の `restore()` は、保存されたトークンからユーザーを呼び戻し、一分以内に期限が切れる場合はトークンを更新します。

- プロバイダーが拒否したリフレッシュトークン (`invalid_grant`) はユーザーをログアウトさせます。到達できないプロバイダーはそうしません (アプリはオフラインで起動します)。
- ユーザーは、アプリケーション独自の `OAuth2UserService` が加えたものも含め、ログイン時の権限とともに戻ってきます (ログインの記録に保持されます。Spring のセッションがログイン時の認証を保持するのと同じく、ユーザーサービスは再び呼ばれません)。`SCOPE_` のものは現在のアクセストークンに従います。
- 設定から取り除かれた登録のログインの記録は、そのトークンとともに取り除かれます。

## logout

`logout()` は、リフレッシュトークンとアクセストークンを取り消し (RFC 7009。プロバイダーが `revocation_endpoint` を持つ場合)、それらを忘れ、コンテキストをクリアし、`LogoutSuccessEvent` を発行します。すべてウィンドウなしでです。ユーザーはシステムのブラウザーではプロバイダーにログインしたままなので、次のログインではパスワードが不要な場合があります。これがモバイルアプリの通常のログアウトです。

- `logout(endSession: true)` は、ログインウィンドウでプロバイダーのセッションも終わらせます (OpenID Connect の RP-initiated logout。ID トークンを `id_token_hint` として使います)。「アカウントの切り替え」のためです。iOS と macOS は、そのウィンドウを独自の「... wants to use ... to Sign In」のプロンプトで告知します。
- 安全なストレージが保存されたログインを削除できない場合でも、`logout()` は実行中のアプリからユーザーをログアウトさせ、その後ストレージのエラーを投げます。そのため、アプリはデバイスがまだログインを保持していることをユーザーに伝えられます。

## Bean

ブラウザーの外で、`spring.security.oauth2.client.registration.*` プロパティがあると、パッケージは次のものを宣言します。

| Bean | 型 | 意味 |
|---|---|---|
| `oauth2LoginService` | `NativeOAuth2LoginService` | ログイン |
| `authorizedClientService` | `SecretStoreOAuth2AuthorizedClientService` | 各認可済みのクライアントを JSON として `SecretStore` に書き込む (`oauth2.authorized-client.<registration>.<principal>` の下に。ログインは `restore` が必要とするものを `oauth2.login` の下に保持する)。OAuth2 クライアントのインメモリーのものを置き換える |
| `appleIdSignIn` | `AppleIdSignIn` | iOS と macOS での Sign in with Apple のシート ([プロバイダー](providers.md) を参照) |
| `platformDPoPKey` | `PlatformDPoPKey` | アプリの DPoP の鍵 ([DPoP](dpop.md) を参照) |

パッケージのすべての Bean は、アプリケーションがその型のものを宣言すると身を引きます。`SecretStore`、`SecretTemplate`、`AuthorizationWindow`、`AppleIdSignIn`、`OAuth2AuthorizedClientService`、`OAuth2LoginService`、`PrincipalNotifier`、`DPoPKey`、そして Web では `BrowserPage` と `HttpTransport` です。パッケージの中で、トークン、コード、ベリファイア、シークレットをログに出すものはありません。

## トークンで API を呼ぶ

OAuth2 クライアントの Feign のインターセプターは、Feign クライアントと同じ名前の登録 (または `spring.feign.oauth2.client-registration-id`) のアクセストークンを送り、必要なら更新し、トークンが結び付けられていれば DPoP のプルーフも付けます。Feign クライアントには `spring_boot_starter_feign` を列挙してください。

## Spring (Java) との対応

Spring には対応するものがありません。その `oauth2Login()` はサーバー上でブラウザーをログインさせます。チェックは、その `OAuth2LoginAuthenticationFilter`、`OidcAuthorizationCodeAuthenticationProvider`、`OidcUserService` のものです。

## 関連項目

- [トークンとログインウィンドウ](tokens-and-login-window.md)
- [Web: サーバーがログインする](web-server-mode.md)
- [すべてのプロパティ](properties.md)
