クライアントアプリケーションでのサインイン
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 からユーザーを読み直す。 |
- ログインは一つ。 ユーザーは Spring Security のものです。
AuthenticationはSecurityContextHolderにあり、ログインと復元のたびにAuthenticationSuccessEventが、logoutのときにLogoutSuccessEventが発行されます。 - ロールは、
app_metadata.rolesの各文字列についてのROLE_<role>で、サーバーと同じです。user_metadataは何の権限も与えません。ユーザーが書けるためです。
@PreAuthorize("hasRole('editor')")
Future<void> publish(Post post) async { ... }
セッション
- 再起動をまたいで保持。
spring.supabase.auth.persist-sessionがtrue(デフォルト) のとき、セッション (二つのトークンとユーザー) はアプリケーションのSecretStoreに保存されます。SecretStoreの Bean がなければ、メモリ上に保持されます。spring_boot_starter_flutter_security は、プラットフォームの安全なストレージ (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 自身の障害が返ったときは、セッションは残り、呼び出しが失敗します。
サインアウト
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
- リクエストの前:
redirectToは、一覧にあるものと、書かれているとおりに完全に一致しなければなりません。指定しなければ最初のものが使われます。それ以外はArgumentErrorで、リクエストは送られません。同じアドレスが、プロジェクト自身のリダイレクト URL の一覧にもなければなりません。 - 戻ってきたとき: リダイレクトは、ログインが要求したアドレス (同じスキーム、ホスト、ポート、パス) で、
codeを持っていなければなりません。別のアドレスや、errorを持つものは、AuthenticationExceptionです。 - PKCE (S256)。 Auth が受け取るのは、ログインの開始時に作られた verifier の SHA-256 だけです。戻ってきたコードは、verifier がなければ何の価値もありません。verifier は、一度だけ Auth 自身に送られる以外、アプリケーションの外に出ません。
ログインウィンドウを使う場合:
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 |
- 応答がまったくない場合は
SupabaseUnavailableExceptionです (タイムアウトならisTimeout)。 - ユーザーを必要とするメソッドを、誰もサインインしていないときに呼び出すと、
AuthenticationCredentialsNotFoundExceptionを投げます。 - トークン、パスワード、コードが、メッセージやログに出ることはありません。応答がそれを繰り返していても、
[PROTECTED]に置き換えられます。
プロジェクト独自のエラーコード (ログインを拒否するフック) には、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 のものです。