
# クライアントアプリケーションでのサインイン

`SupabaseAuth` (Bean 名は `supabaseAuth`) は、Supabase Auth によるクライアントアプリケーションのログインです。ユーザーをサインアップ、サインインさせ、セッションを新しく保ち、再起動をまたいで保持し、サインアウトさせます。アプリケーションの [`LoginSession`](../spring-security-core/login-session.md) でもあります。

## 使う理由

ログインは、一つのリクエストでは終わりません。トークンは実行と実行の間で安全に保管し、期限が切れる前に更新し (待っている呼び出し元が何人いてもリクエストは一つ)、サーバーがセッションを終わらせたら捨てなければなりません。戻ってきたリダイレクトは、要求したものでなければなりません。そしてアプリケーションの他の部分は、すでに見ている場所、つまりセキュリティコンテキストでユーザーを見られるべきです。`SupabaseAuth` はこれらを一か所で行うので、Supabase へのすべての呼び出しとすべての `@PreAuthorize` が同じユーザーを見ます。

## 例

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

  final SupabaseAuth auth;

  Future<void> signIn(String email, String password) async {
    try {
      await auth.signInWithPassword(email: email, password: password);
    } on BadCredentialsException {
      showError('Wrong email or password');
    } on AuthenticationException catch (e) {
      if (e case SupabaseAuthFailure(errorCode: 'email_not_confirmed')) {
        showError('Confirm your email address first');
      }
    }
  }

  String? get email => auth.user?.email;

  Future<void> signOut() => auth.logout();
}
```

`signInWithPassword` の後は、Supabase へのすべての呼び出しがそのユーザーとして行われ、`@PreAuthorize` とセキュリティコンテキストもそのユーザーを見ます。

## サインアップとサインイン

| メソッド | すること |
|---|---|
| `signUp(password:, email:, phone:, data:, redirectTo:)` | メールアドレスまたは電話番号とパスワードでユーザーを作る。`data` はそのユーザーの `user_metadata`。プロジェクトが新しいユーザーを自動で確認する場合はサインインしたユーザーで完了し、そうでなければ `null` で完了する。アドレスが確認されるまで、誰もサインインしていない。 |
| `signInWithPassword(password:, email:, phone:)` | メールアドレスまたは電話番号とパスワードでサインインする。資格情報が間違っていれば `BadCredentialsException`。Auth はどの部分が間違っていたかを言わない。 |
| `signInWithOtp(email:, phone:, createUser:, redirectTo:)` | メールにワンタイムコードかマジックリンクを、電話にコードを送る。まだ誰もサインインしていない。`createUser` (デフォルト) があると、未知のアドレスは新しいユーザーになる。 |
| `verifyOtp(token:, type:, email:, phone:)` | コードでサインインする。`type` (`SupabaseOtpType`) は、そのコードが何のために送られたかを示す: `email`、`sms`、`signup`、`invite`、`magiclink`、`recovery`、`emailChange`、`phoneChange`。 |
| `signInWithIdToken(provider:, idToken:, accessToken:, nonce:)` | プロバイダー自身の SDK が渡した ID トークンでサインインする (ネイティブの Google や Apple のサインイン)。 |
| `signInWithProvider(provider, scopes:, redirectTo:, queryParameters:)` | アプリケーションの `AuthorizationWindow` でプロバイダーのページ (`google`、`github`、`apple` など) を開き、戻ってきたコードを交換する。 |
| `authorizationUrl(provider, scopes:, redirectTo:, queryParameters:)` | プロバイダーのページのアドレス。ブラウザーを自分で開くアプリケーションのため。 |
| `completeSignIn(redirect)` | リダイレクトを待っているログインを完了する。プロバイダーの応答、マジックリンク、サインアップの確認、パスワードのリセット。 |
| `exchangeCode(code)` | 待っているログインの認可コードを交換する。`completeSignIn` は、コードがどこから来たかも検査する。 |
| `resetPassword(email, redirectTo:)` | ユーザーが新しいパスワードを設定できるメールを送る。 |

メールアドレスか電話番号のどちらか一方を渡します。それ以外は、リクエストを送る前に `ArgumentError` になります。Auth は、すでに使われているアドレス (サインアップ) にも未知のアドレス (パスワードのリセット) にも同じ応答を返すので、誰がアカウントを持っているかは誰にも分かりません。

```dart
await auth.signInWithOtp(email: email);
// The user types the code of the email:
await auth.verifyOtp(email: email, token: code, type: SupabaseOtpType.email);
```

## サインインしたユーザー

| メンバー | 意味 |
|---|---|
| `user` | `SupabaseUser`、または `null`。`id`、`email`、`phone`、`role`、`appMetadata`、`userMetadata`、`roles`、`createdAt`、`emailConfirmedAt`、`lastSignInAt`、`isAnonymous` など。 |
| `authentication` | セキュリティコンテキストにある `SupabaseAuthenticationToken`。`name` はユーザーの ID、`principal` は `SupabaseUser`、`credentials` はアクセストークン。 |
| `isLoggedIn` | ユーザーがサインインしているかどうか。 |
| `authenticationChanges` | 変更のたびのユーザーのストリーム。ログアウトの後は `null`。 |
| `updateUser(email:, password:, data:)` | ユーザーを変更する。メールアドレス (Auth が先に新しいアドレスを確認する)、パスワード、または `user_metadata` にマージされる `data`。 |
| `reloadUser()` | アドレスが確認された後や、プロジェクトがロールを変更した後に、Auth からユーザーを読み直す。 |

- **ログインは一つ。** ユーザーは Spring Security のものです。`Authentication` は `SecurityContextHolder` にあり、ログインと復元のたびに `AuthenticationSuccessEvent` が、`logout` のときに `LogoutSuccessEvent` が発行されます。
- **ロール**は、`app_metadata.roles` の各文字列についての `ROLE_<role>` で、[サーバー](security.md)と同じです。`user_metadata` は何の権限も与えません。ユーザーが書けるためです。

```dart
@PreAuthorize("hasRole('editor')")
Future<void> publish(Post post) async { ... }
```

## セッション

- **再起動をまたいで保持。** `spring.supabase.auth.persist-session` が `true` (デフォルト) のとき、セッション (二つのトークンとユーザー) はアプリケーションの `SecretStore` に保存されます。`SecretStore` の Bean がなければ、メモリ上に保持されます。[spring_boot_starter_flutter_security](../spring-boot-starter-flutter-security/tokens-and-login-window.md) は、プラットフォームの安全なストレージ (Keychain、Keystore) の上のストアを宣言します。
- **起動時に復元。** `restore()` はアプリケーションの起動時に自動で実行され、起動を失敗させることはありません。アクセストークンの期限が切れているセッションは、先に更新されます。ネットワークがなくてもユーザーは復元され、トークンは次に使うときに更新されます。読めない保存値は削除されます。
- **更新。** `accessToken()` は、期限切れが近くないトークンを返します。`refresh-margin` (30 秒) 以内に期限が切れるトークンは先に更新され、待っている呼び出し元が何人いてもリクエストは一つです。`auto-refresh` (デフォルト) では、期限の前にタイマーが更新します。`refreshSession()` は今すぐ更新します。
- **リフレッシュトークンは一度だけ使われます。** 新しいものがすぐにそれを置き換えます。
- **Auth がリフレッシュトークンを拒否したとき** (`refresh_token_not_found`、`refresh_token_already_used`、`session_not_found`、`session_expired`、`user_not_found`、`user_banned`、`invalid_grant`: `SupabaseAuth.sessionEndingCodes`)、ユーザーはここでサインアウトされます。そのとき `refreshSession()` は `SupabaseSessionExpiredException` を投げ、`accessToken()` は `null` を返します。
- **Auth に届かないとき**、またはレート制限や Auth 自身の障害が返ったときは、セッションは残り、呼び出しが失敗します。

## サインアウト

```dart
await auth.logout();                                   // this session
await auth.logout(scope: SupabaseLogoutScope.global);  // every device
await auth.logout(scope: SupabaseLogoutScope.others);  // every session but this one
```

セッションはまずここで忘れられ (メモリ、`SecretStore`、セキュリティコンテキスト、更新のタイマー)、それから Auth で取り消されます。Auth に届かなくても、ユーザーはここでサインアウトされます。ログアウトがネットワークに左右されることはありません。`others` では、ユーザーはここではサインインしたままで、失敗は例外として投げられます。

## リダイレクトと PKCE

プロバイダー経由のログイン、マジックリンク、サインアップの確認、パスワードのリセットは、あるアドレスでアプリケーションに戻ってきます。そのアドレスは一覧にしておき、それ以外は受け入れられません。

```yaml
spring:
  supabase:
    auth:
      redirect-urls:
        - com.example.app://login
        - https://app.example.com/login
```

- **リクエストの前:** `redirectTo` は、一覧にあるものと、書かれているとおりに完全に一致しなければなりません。指定しなければ最初のものが使われます。それ以外は `ArgumentError` で、リクエストは送られません。同じアドレスが、プロジェクト自身のリダイレクト URL の一覧にもなければなりません。
- **戻ってきたとき:** リダイレクトは、ログインが要求したアドレス (同じスキーム、ホスト、ポート、パス) で、`code` を持っていなければなりません。別のアドレスや、`error` を持つものは、`AuthenticationException` です。
- **PKCE (S256)。** Auth が受け取るのは、ログインの開始時に作られた verifier の SHA-256 だけです。戻ってきたコードは、verifier がなければ何の価値もありません。verifier は、一度だけ Auth 自身に送られる以外、アプリケーションの外に出ません。

ログインウィンドウを使う場合:

```dart
await auth.signInWithProvider('github', scopes: ['read:user']);
```

これには `AuthorizationWindow` の Bean が必要です ([spring_boot_starter_flutter_security](../spring-boot-starter-flutter-security/tokens-and-login-window.md) が宣言します)。なければ `StateError` を投げます。ユーザーが閉じたウィンドウは `AuthorizationCancelledException` です。デスクトップのウィンドウは、ループバックアドレスの空いているポートを使うことがあります。アドレスのそれ以外の部分は変わってはなりません。

ウィンドウがない場合は、アプリケーションが自分でブラウザーを開きます。

```dart
final url = await auth.authorizationUrl('google');
await launchUrl(url);
// Later, from the application's deep link:
await auth.completeSignIn(link);
```

そのようなログインの verifier と、メールのリンクの verifier は、`SecretStore` で待ちます。そのため、途中でアプリケーションを再起動してもかまいません。別のログインを始めると置き換えられます。待てるログインは一度に一つです。verifier は一度だけ使われます。

パスワードのリセットも同じ流れです。`resetPassword(email)` の後、`completeSignIn(link)` がユーザーをサインインさせ、`updateUser(password: …)` がパスワードを設定します。

## エラー

失敗したログインは、Spring Security の `AuthenticationException` のどれかです。そのため、Spring の型に対して書いたコードは変わりません。それぞれ、Auth のエラーコードと HTTP ステータスも持っています (`SupabaseAuthFailure.errorCode`、`statusCode`)。

| Auth のコード | 例外 | Spring の型 |
|---|---|---|
| `invalid_credentials`、`invalid_grant`、`otp_expired`、`bad_code_verifier`、`flow_state_*` | `SupabaseBadCredentialsException` | `BadCredentialsException` |
| `email_not_confirmed`、`phone_not_confirmed`、`provider_email_needs_verification` | `SupabaseAccountDisabledException` | `DisabledException` |
| `user_banned` | `SupabaseAccountLockedException` | `LockedException` |
| `refresh_token_not_found`、`refresh_token_already_used`、`session_not_found`、`session_expired` | `SupabaseSessionExpiredException` | `CredentialsExpiredException` |
| `user_not_found` | `SupabaseUserNotFoundException` | `UsernameNotFoundException` |
| `weak_password` | `SupabaseWeakPasswordException` (`reasons`: `length`、`characters`、`pwned`) | `AuthenticationException` |
| ステータス 500 以上 | `SupabaseAuthServiceException` | `AuthenticationServiceException` |
| それ以外 (レート制限、Auth が受け付けられなかったリクエスト) | `SupabaseAuthenticationException` | `AuthenticationException` |

- 応答がまったくない場合は `SupabaseUnavailableException` です (タイムアウトなら `isTimeout`)。
- ユーザーを必要とするメソッドを、誰もサインインしていないときに呼び出すと、`AuthenticationCredentialsNotFoundException` を投げます。
- トークン、パスワード、コードが、メッセージやログに出ることはありません。応答がそれを繰り返していても、`[PROTECTED]` に置き換えられます。

プロジェクト独自のエラーコード (ログインを拒否するフック) には、`SupabaseAuthErrorTranslator` の Bean が独自の例外を与えます。この Bean は、スターター自身のものより先に尋ねられます。

```dart
@Component()
class TrialEnded implements SupabaseAuthErrorTranslator {
  @override
  AuthenticationException? translate(SupabaseAuthError error) =>
      error.code == 'trial_ended'
          ? AccountExpiredException(error.message)
          : null;
}
```

## 管理 API

`SupabaseAuthAdmin` (Bean 名は `supabaseAuthAdmin`) は、サービスロールとして、プロジェクトのユーザーを作成、取得、変更、削除します。サーバーにだけあります。そのモジュールは `ModulePlatform.server` (Dart VM または AOT 実行ファイル) なので、Flutter アプリ (スマートフォン、デスクトップ、Web) とブラウザービルドにはそのコードがなく、アプリからそれを呼ばせることはできません。`-DSPRING_ALL_PLATFORMS=true` でコンパイルされるエッジ関数にはあります。`spring.supabase.service-role-key` がなければ、呼び出しはリクエストを送る前に `StateError` で失敗します。

```dart
final user = await admin.createUser(
  email: 'ada@example.com',
  password: password,
  emailConfirm: true,
  appMetadata: {'roles': ['editor']},
);
await admin.updateUser(user.id, appMetadata: {'roles': ['admin']});
await admin.deleteUser(user.id);
```

| メソッド | すること |
|---|---|
| `createUser(email:, phone:, password:, emailConfirm:, phoneConfirm:, appMetadata:, userMetadata:)` | ユーザーを作る。`emailConfirm` があると、アドレスは確認済みとして扱われ、ユーザーはすぐにサインインできる。 |
| `user(id)` | ユーザー、または `null`。 |
| `users(page:, perPage:)` | ユーザーの一ページ。`page` は 1 から始まり、`perPage` のデフォルトは 50。 |
| `updateUser(id, …, banDuration:)` | 渡したものだけを変更する。`appMetadata` と `userMetadata` はマージされる (値が `null` のキーは削除される)。`banDuration: '24h'` は利用を停止し、`'none'` は停止を解除する。 |
| `deleteUser(id, softDelete:)` | ユーザーをそのセッションとともに削除する。 |

ロールは `appMetadata` (`roles`) に入れます。それを書くのはこの API だけです。UUID でない ID は `ArgumentError` です。

## 対応していないもの

匿名サインイン、多要素認証、ID の連携、SSO (SAML)、確認メールの再送。管理 API では、招待とリンクの生成。

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.supabase.auth.enabled` | `bool` | `true` | `false` にすると、`supabaseAuth` も `supabaseAuthAdmin` も宣言されない (`supabaseAuthAdmin` はサーバーにだけある)。 |
| `spring.supabase.auth.redirect-urls` | `List<String>` | 空 | ログインが戻ってきてよいアドレス。最初のものがデフォルト。 |
| `spring.supabase.auth.persist-session` | `bool` | `true` | セッションを `SecretStore` に保存するかどうか。 |
| `spring.supabase.auth.auto-refresh` | `bool` | `true` | 期限が切れる前に、タイマーがアクセストークンを更新するかどうか。 |
| `spring.supabase.auth.refresh-margin` | `Duration` | `30s` | 期限のどれだけ前から、アクセストークンを期限切れとみなすか。 |

## Spring (Java) との対応

対応するものはありません。Spring Security がログインさせるのは、サーバーのユーザーです。最も近いのは `oauth2Login()` と `OAuth2AuthorizedClientManager` です。例外とイベントは Spring Security のものです。

## 関連項目

- [LoginSession と共有インターフェース](../spring-security-core/login-session.md)
- [サーバーのセキュリティ](security.md)
- [誰として呼び出すか](credentials.md)
- [メソッドセキュリティ](../spring-security-core/method-security.md)
- [spring_boot_starter_flutter_security](../spring-boot-starter-flutter-security/index.md)
