Supabase Auth 怎么開啟 PasskeyWebAuthn無密碼登錄并配置 Relying Party【免費(fèi)下載鏈接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/supa/supabase如果你的項(xiàng)目想讓最終用戶用設(shè)備生物識(shí)別、PIN 或安全密鑰代替密碼登錄就需要在 Supabase Auth 上開啟 Passkey基于 WebAuthn 標(biāo)準(zhǔn)的無密碼憑證并正確配置 Relying PartyRP即你的應(yīng)用作為密鑰歸屬方。完整流程是先在服務(wù)端Dashboard、CLI 或 Management API 三選一開啟 Passkey 并填寫 RP 三要素再在客戶端顯式開啟實(shí)驗(yàn)性 API然后注冊(cè)一個(gè) passkey 并走一次無密碼登錄最后驗(yàn)證配置已生效。需要先把邊界說清楚Passkey 支持目前是實(shí)驗(yàn)性功能ExperimentalAPI 可能隨時(shí)變更且客戶端創(chuàng)建時(shí)必須顯式 opt-in?？蛻舳藥彀姹疽髎upabase/supabase-jsv2.105.0 及以上、supabase_flutterv2.15.0 及以上或supabase-swiftv2.48.0 及以上。前提條件與 RP 配置的規(guī)則在動(dòng)手之前先確認(rèn)這些約束它們是源文檔明確給出的注冊(cè) passkey 的前提用戶必須已登錄、郵箱或電話已驗(yàn)證confirmed且不是匿名用戶。登錄的前提用戶已注冊(cè)過 passkey郵箱或電話已驗(yàn)證且賬戶未被封禁banned。Supabase Auth 使用 discoverable credentials登錄時(shí)用戶無需提供郵箱、電話或用戶名認(rèn)證器直接從存儲(chǔ)的憑據(jù)解析出賬戶。Relying Party ID應(yīng)用的光板域名例如example.com不要帶 scheme、端口或路徑。它決定了哪些 passkey 可用。Relying Party Origins逗號(hào)分隔的允許來源列表例如https://example.com,https://app.example.com最多 5 個(gè)。除回環(huán)地址localhost、127.0.0.1、[::1]外必須使用 HTTPS每個(gè) origin 的主機(jī)名必須與 RP ID 相同或?yàn)槠渥佑蛎?。Android 原生應(yīng)用可以用形如android:apk-key-hash:簽名證書的 base64url SHA-256的 app origin。Relying Party Display Namepasskey 提示時(shí)展示給用戶的可讀名稱例如 My App。Admonition 等效提示RP ID 一旦變更所有已注冊(cè)的 passkey 全部失效因?yàn)?passkey 在密碼學(xué)上綁定到注冊(cè)時(shí)的 RP ID。用戶在開始注冊(cè)前就要想好 RP ID之后保持穩(wěn)定。服務(wù)端開啟 Passkey 并配置 Relying Party三種方式任選其一即可配置的是同一份服務(wù)端狀態(tài)。主路徑Dashboard在 Supabase 項(xiàng)目的Authentication → Passkeys設(shè)置頁中打開Enable Passkey authentication開關(guān)并填寫上面三個(gè) RP 字段。Dashboard 會(huì)用項(xiàng)目的 Site URL 和項(xiàng)目名預(yù)填這些值——如果生產(chǎn)環(huán)境應(yīng)用部署在不同域名下需要手動(dòng)改成生產(chǎn)域名。替代路徑CLI本地 Supabase 項(xiàng)目在supabase/config.toml中添加[auth.passkey] enabled true [auth.webauthn] rp_display_name My App rp_id example.com rp_origins [https://example.com, https://app.example.com]注意當(dāng)auth.passkey.enabled為true時(shí)[auth.webauthn]一節(jié)是必填的。把示例值換成你自己應(yīng)用的域名和名稱。替代路徑Management API適合程序化或跨項(xiàng)目批量配置。先從 Supabase Dashboard 的賬戶 tokens 頁拿到 Access Token下面兩條命令中的your-access-token和your-project-ref替換為你的實(shí)際值# Get your access token from https://supabase.com/dashboard/account/tokens export SUPABASE_ACCESS_TOKENyour-access-token export PROJECT_REFyour-project-ref # Read the current passkey configuration curl -X GET https://api.supabase.com/v1/projects/$PROJECT_REF/config/auth \ -H Authorization: Bearer $SUPABASE_ACCESS_TOKEN \ | jq {passkey_enabled, webauthn_rp_id, webauthn_rp_display_name, webauthn_rp_origins} # Enable passkeys and set the WebAuthn relying party curl -X PATCH https://api.supabase.com/v1/projects/$PROJECT_REF/config/auth \ -H Authorization: Bearer $SUPABASE_ACCESS_TOKEN \ -H Content-Type: application/json \ -d { passkey_enabled: true, webauthn_rp_display_name: My App, webauthn_rp_id: example.com, webauthn_rp_origins: https://example.com,https://app.example.com }GET 命令同時(shí)就是你配置后的核對(duì)手段返回的passkey_enabled、webauthn_rp_id、webauthn_rp_display_name、webauthn_rp_origins應(yīng)與預(yù)期一致?？蛻舳藛⒂?Passkey API服務(wù)端開啟之后客戶端還要顯式啟用或滿足各 SDK 的對(duì)應(yīng)條件。JavaScript主路徑supabase/supabase-jsv2.105.0import { createClient } from supabase/supabase-js const supabase createClient(supabaseUrl, supabaseKey, { auth: { experimental: { passkey: true }, }, })supabaseUrl、supabaseKey替換為你項(xiàng)目的 URL 和 anon key。Dartsupabase_flutterv2.15.0不需要 opt-in 標(biāo)志方法以experimental標(biāo)注analyzer 會(huì)按預(yù)覽 API 提示。但需要自己引入一個(gè) passkey 插件并提供 authenticator例如passkeys插件2.21.0起的PasskeyAuthenticator實(shí)現(xiàn)了這些方法期望的PasskeyAuthenticatorInterfaceimport package:passkeys/authenticator.dart; final authenticator PasskeyAuthenticator();Dart SDK 替你完成 WebAuthn 儀式的服務(wù)端部分把平臺(tái)彈窗FaceID/TouchID/安全密鑰委托給你提供的 authenticator。平臺(tái)側(cè)配置iOS/macOS 的 Associated Domains、Android 的 Digital Asset Links、Web 的index.html引入 passkeys web SDK需在應(yīng)用工程中自行完成。Swiftsupabase-swiftv2.48.0Passkey 能力在_spi(Experimental)后面在每個(gè)使用 passkey API 的文件頂部加_spi(Experimental) import SupabaseSupabaseClient本身無需額外配置。Associated Domains 權(quán)限和帶 HTTPS 的 RP 服務(wù)器需要在 Xcode 工程中自行配置。注冊(cè) passkey第一次無密碼憑證落地用戶必須先登錄才能注冊(cè) passkey典型調(diào)用位置是安全設(shè)置頁或注冊(cè)完成之后。JS 端const { data, error } await supabase.auth.registerPasskey() if (error) { // User cancelled, browser doesnt support WebAuthn, or verification failed console.error(error) } else { console.log(Registered passkey, data.id) }registerPasskey()會(huì)跑完整儀式向 Supabase Auth 取 challenge、調(diào)起平臺(tái) passkey API、把簽名響應(yīng)送回服務(wù)端驗(yàn)證。成功時(shí)返回新憑據(jù)的元數(shù)據(jù){ id: string // UUID — use this to update or delete the passkey friendly_name?: string // Derived from the authenticators AAGUID created_at: string }friendly_name自動(dòng)從認(rèn)證器的 AAGUID 派生例如iCloud Keychain、Google Password Manager、1Password之后用戶可以改名friendlyName限 120 字符。Dart 和 Swift 的一鍵調(diào)用final Passkey passkey await supabase.auth.registerPasskey(authenticator);let passkey try await supabase.auth.registerPasskey( presentationAnchor: view.window! )Swift 的registerPasskey/signInWithPasskey要求 iOS 16、macOS 13 或 visionOS 1。如果不需要 SDK 封裝好的儀式、要自定義 UI 或?qū)釉?WebAuthn 庫可以用底層兩步 API可選分支startRegistration()/verifyRegistration()、startAuthentication()/verifyAuthentication()start 方法返回的options與 WebAuthn 的PublicKeyCredentialCreationOptions/PublicKeyCredentialRequestOptions結(jié)構(gòu)一致ArrayBuffer字段以 base64url 編碼const { data: options } await supabase.auth.passkey.startRegistration() // Run the WebAuthn ceremony yourself (e.g.: using a native WebAuthn library) const credential await runRegistrationCeremony(options.options) await supabase.auth.passkey.verifyRegistration({ challengeId: options.challenge_id, credential, })用 passkey 登錄const { data, error } await supabase.auth.signInWithPasskey() if (error) { console.error(error) } else { // data.session and data.user are set; the client also dispatches a SIGNED_IN event console.log(Signed in as, data.user?.email) }登錄走 discoverable credential 流程用戶在認(rèn)證器的 UI 里選賬戶應(yīng)用不需要預(yù)先索要郵箱或電話。成功后data.session和data.user就緒客戶端同時(shí)派發(fā)SIGNED_IN事件。驗(yàn)證配置已生效按部署方式選擇對(duì)應(yīng)的驗(yàn)證手段Hosted 項(xiàng)目用上面的 Management API GET 命令回讀配置確認(rèn)passkey_enabled為true、三個(gè)webauthn_*字段與預(yù)期一致然后按“注冊(cè) → 登錄”各走一遍error為空、返回data.id/data.session即整條鏈路打通。自托管Self-hosted項(xiàng)目Passkey 通過docker-compose.yml中傳給 auth 服務(wù)的環(huán)境變量配置與 hosted 的 Dashboard/Management API 不是同一條路徑Management API 指向api.supabase.com自托管環(huán)境不可用。在auth服務(wù)下添加services: auth: environment: # ... existing variables ... GOTRUE_PASSKEY_ENABLED: true GOTRUE_PASSKEY_MAX_PASSKEYS_PER_USER: 10 # optional - default is 10 GOTRUE_WEBAUTHN_RP_ID: example.com GOTRUE_WEBAUTHN_RP_DISPLAY_NAME: my-app GOTRUE_WEBAUTHN_RP_ORIGINS: https://example.com,https://app.example.com GOTRUE_WEBAUTHN_CHALLENGE_EXPIRY_DURATION: 5m # optional - default is 5 minutes其中GOTRUE_WEBAUTHN_RP_ID、GOTRUE_WEBAUTHN_RP_DISPLAY_NAME、GOTRUE_WEBAUTHN_RP_ORIGINS在開啟 passkey 時(shí)必填規(guī)則與 hosted 一致。本地測試可用GOTRUE_WEBAUTHN_RP_ID: localhost配合 originhttp://localhost:3000。修改后需要重建 auth 容器使配置生效該命令會(huì)重建 auth 容器期間 auth 服務(wù)短暫中斷sh run.sh recreate auth驗(yàn)證請(qǐng)求一個(gè)認(rèn)證 challenge把your-domain和 publishable key 換成實(shí)際值curl -X POST http://your-domain/auth/v1/passkeys/authentication/options \ -H apikey: your-supabase-publishable-key返回200且響應(yīng)中含challenge_id說明 passkey 認(rèn)證已啟用返回passkey_disabled說明 auth 服務(wù)沒有讀到新配置。服務(wù)端管理側(cè)也可以用 admin API 查看/吊銷某個(gè)用戶的 passkey需要 secret key只能在可信服務(wù)端調(diào)用例如自托管下的列表接口curl http://your-domain/auth/v1/admin/users/{user_id}/passkeys \ -H apikey: your-supabase-secret-key常見錯(cuò)誤碼代碼含義passkey_disabled該項(xiàng)目未開啟 passkey 登錄too_many_passkeys用戶已達(dá)到每賬戶允許的 passkey 數(shù)量上限webauthn_credential_exists該認(rèn)證器已注冊(cè)到該賬戶webauthn_credential_not_foundassertion 中的憑據(jù)未在 Supabase Auth 注冊(cè)webauthn_challenge_not_foundchallenge ID 未知或已被消費(fèi)webauthn_challenge_expired客戶端返回憑據(jù)前 challenge 已過期webauthn_verification_failed簽名、attestation 或 assertion 未通過驗(yàn)證另外signInWithPasskey()還會(huì)返回常規(guī)登錄失敗模式email_not_confirmed、phone_not_confirmed、user_banned。限制與下一步SSO 用戶無法注冊(cè) passkey匿名用戶也無法注冊(cè)需要先關(guān)聯(lián)郵箱或電話。再次強(qiáng)調(diào) RP ID 變更會(huì)作廢所有存量 passkey用戶需要重新注冊(cè)。服務(wù)端開啟后客戶端側(cè)的注冊(cè)與登錄配置方式和 hosted 項(xiàng)目完全一致自托管場景亦如此。更多 API 細(xì)節(jié)可查倉庫中的兩篇源文檔Passkey authentication 指南 與 自托管 Passkey 配置指南?！久赓M(fèi)下載鏈接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/supa/supabase創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考