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

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

使う理由

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

例

@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 は、すでに使われているアドレス (サインアップ) にも未知のアドレス (パスワードのリセット) にも同じ応答を返すので、誰がアカウントを持っているかは誰にも分かりません。

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 からユーザーを読み直す。
@PreAuthorize("hasRole('editor')")
Future<void> publish(Post post) async { ... }

セッション

サインアウト

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

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

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

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

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

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

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

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

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

@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 で失敗します。

final user = await admin.createUser(
  email: '[email protected]',
  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 のものです。

関連項目