The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
docs(self-hosted): add passkeys guide (#48954)
Inder Singh90b7b34d7f3b
diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.tsindex 4c2982272ea..2bf96f10826 100644--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts@@ -3136,6 +3136,7 @@ export const self_hosting: NavMenuConstant = {{ name: 'Configure Phone Login & MFA', url: '/guides/self-hosting/self-hosted-phone-mfa' },{ name: 'Add Custom Email Templates', url: '/guides/self-hosting/custom-email-templates' },{ name: 'Configure Auth Hooks', url: '/guides/self-hosting/self-hosted-auth-hooks' },+ { name: 'Configure Passkeys', url: '/guides/self-hosting/self-hosted-passkeys' },{ name: 'Configure SAML 2.0 SSO', url: '/guides/self-hosting/self-hosted-saml-sso' },{name: 'Restore Project from Platform',diff --git a/apps/docs/content/guides/self-hosting/self-hosted-passkeys.mdx b/apps/docs/content/guides/self-hosting/self-hosted-passkeys.mdxnew file mode 100644index 00000000000..d0757f19805--- /dev/null+++ b/apps/docs/content/guides/self-hosting/self-hosted-passkeys.mdx@@ -0,0 +1,98 @@+---+title: 'Configure Passkey Authentication'+description: 'Set up passkey authentication for self-hosted Supabase.'+subtitle: 'Set up passkey authentication for self-hosted Supabase.'+---++## Overview++[Passkeys](https://fidoalliance.org/passkeys/) are passwordless, phishing-resistant credentials built on the [WebAuthn](https://www.w3.org/TR/webauthn-3/) standard. This guide covers the server-side configuration to enable passkey authentication in a self-hosted Supabase instance. For how passkeys work and how to use them from a client, see the [Passkey authentication](/docs/guides/auth/passkeys) guide.++## Enable passkey authentication++For self-hosted Supabase, passkey authentication is configured through environment variables passed to the auth service in `docker-compose.yml`. The variables below control passkey authentication and WebAuthn configuration.++| Variable | Description | Default |+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |+| `GOTRUE_PASSKEY_ENABLED` | Enables passkey authentication. | `false` |+| `GOTRUE_PASSKEY_MAX_PASSKEYS_PER_USER` | Maximum number of passkeys a single user can register. | `10` |+| `GOTRUE_WEBAUTHN_RP_ID` | The bare domain name for your application (the WebAuthn [relying party](https://www.w3.org/TR/webauthn-3/#relying-party) ID). Do not include a scheme, port, or path. This determines which passkeys can be used. **Required when passkey auth is enabled.** | - |+| `GOTRUE_WEBAUTHN_RP_DISPLAY_NAME` | A human-readable name for your application, shown during the passkey prompt. **Required when passkey auth is enabled.** | - |+| `GOTRUE_WEBAUTHN_RP_ORIGINS` | Comma-separated list of allowed origins (for example, `https://example.com,https://app.example.com`). **Required when passkey auth is enabled.** | - |+| `GOTRUE_WEBAUTHN_CHALLENGE_EXPIRY_DURATION` | How long a WebAuthn challenge remains valid. If the ceremony isn't completed within this window, the client must request a new challenge. | `5m` |++### Configure the Auth service++Add the environment variables to the `auth` service in your `docker-compose.yml`:++```yml name=docker-compose.yml+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+```++WebAuthn requires a secure context, so when setting `GOTRUE_WEBAUTHN_RP_ORIGINS`, keep the following requirements in mind:++- Origins must use HTTPS, except for loopback addresses (`localhost`, `127.0.0.1`, `[::1]`).+- Each origin's hostname must match or be a subdomain of `GOTRUE_WEBAUTHN_RP_ID`.+- Android native apps can use an app origin of the form `android:apk-key-hash:<base64url SHA-256 of the signing certificate>`.++For local testing, set `GOTRUE_WEBAUTHN_RP_ID` to `localhost` and use `http://localhost:3000` as the origin.++<Admonition type="caution" title="Changing the Relying Party ID invalidates existing passkeys">++Passkeys are cryptographically bound to the Relying Party (RP) ID they were registered against. Changing the RP ID makes every existing passkey unusable for sign-in, and users will need to register a new one. Pick the RP ID carefully before users start enrolling, and keep it stable once they do.++</Admonition>++### Relaunch the Auth service++After updating the environment variables, relaunch the auth service for the changes to take effect:++```bash+sh run.sh recreate auth+```++### Verify passkeys are enabled++Request an authentication challenge to confirm the auth service picked up the configuration:++```sh+curl -X POST 'http://<your-domain>/auth/v1/passkeys/authentication/options' \+ -H 'apikey: your-supabase-publishable-key'+```++A `200` response containing a `challenge_id` confirms that passkey authentication is enabled. A `passkey_disabled` error means the auth service did not pick up the configuration.++## Manage a user's passkeys++Use the Auth admin API to inspect or revoke a user's passkeys from a trusted server, for example to remove a lost device. These calls require your project's secret key, `SUPABASE_SECRET_KEY`, from your `.env` file and must never run in client code.++The [Management API](/docs/guides/auth/passkeys#management-api) covered in the client guide targets `api.supabase.com` and isn't available for self-hosted deployments. Configure passkeys with the environment variables above, and manage individual passkeys with the admin endpoints below.++### List a user's passkeys++```sh+curl 'http://<your-domain>/auth/v1/admin/users/{user_id}/passkeys' \+ -H 'apikey: your-supabase-secret-key'+```++### Delete a user's passkey++```sh+curl -X DELETE 'http://<your-domain>/auth/v1/admin/users/{user_id}/passkeys/{passkey_id}' \+ -H 'apikey: your-supabase-secret-key'+```++Deleting a user's last passkey removes their ability to sign in with a passkey until they register a new one.++## Next steps++After you enable passkeys in your self-hosted Auth service, configure the client exactly as you would for a hosted project: opt in when you create the Supabase client, register a passkey, and sign in. See [Enable in the client](/docs/guides/auth/passkeys#enable-in-the-client).