From 1f9d7c809be70b523b0b6b562ecddd3592a6f2c3 Mon Sep 17 00:00:00 2001 From: Nico Kempe Date: Sat, 20 Sep 2025 21:21:57 +0200 Subject: [PATCH 1/4] chore(gitignore): add .idea --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index e3ca2170f..befba0d5c 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,7 @@ coverage.out .DS_Store .vscode +.idea www/dist/ www/.DS_Store www/node_modules From 97bd7176bc6f6f35087c1c492348c2a81cf1e585 Mon Sep 17 00:00:00 2001 From: Nico Kempe Date: Sat, 20 Sep 2025 21:22:48 +0200 Subject: [PATCH 2/4] chore(env): normalize example.env --- example.env | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/example.env b/example.env index b0c3670b1..352813b63 100644 --- a/example.env +++ b/example.env @@ -91,7 +91,7 @@ GOTRUE_EXTERNAL_FIGMA_CLIENT_ID="" GOTRUE_EXTERNAL_FIGMA_SECRET="" GOTRUE_EXTERNAL_FIGMA_REDIRECT_URI="https://localhost:9999/callback" -# Gitlab OAuth config +# GitLab OAuth config GOTRUE_EXTERNAL_GITLAB_ENABLED="false" GOTRUE_EXTERNAL_GITLAB_CLIENT_ID="" GOTRUE_EXTERNAL_GITLAB_SECRET="" @@ -103,7 +103,7 @@ GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID="" GOTRUE_EXTERNAL_GOOGLE_SECRET="" GOTRUE_EXTERNAL_GOOGLE_REDIRECT_URI="http://localhost:9999/callback" -# Github OAuth config +# GitHub OAuth config GOTRUE_EXTERNAL_GITHUB_ENABLED="false" GOTRUE_EXTERNAL_GITHUB_CLIENT_ID="" GOTRUE_EXTERNAL_GITHUB_SECRET="" @@ -121,7 +121,7 @@ GOTRUE_EXTERNAL_NOTION_CLIENT_ID="" GOTRUE_EXTERNAL_NOTION_SECRET="" GOTRUE_EXTERNAL_NOTION_REDIRECT_URI="https://localhost:9999/callback" -# Twitter OAuth1 config +# Twitter (X) OAuth1 config GOTRUE_EXTERNAL_TWITTER_ENABLED="false" GOTRUE_EXTERNAL_TWITTER_CLIENT_ID="" GOTRUE_EXTERNAL_TWITTER_SECRET="" @@ -146,7 +146,7 @@ GOTRUE_EXTERNAL_KEYCLOAK_SECRET="" GOTRUE_EXTERNAL_KEYCLOAK_REDIRECT_URI="http://localhost:9999/callback" GOTRUE_EXTERNAL_KEYCLOAK_URL="https://keycloak.example.com/auth/realms/myrealm" -# Linkedin OAuth config +# LinkedIn OAuth config GOTRUE_EXTERNAL_LINKEDIN_ENABLED="true" GOTRUE_EXTERNAL_LINKEDIN_CLIENT_ID="" GOTRUE_EXTERNAL_LINKEDIN_SECRET="" From 3b372dd89aec40ba4a4611f99fc76d5fc10a21b6 Mon Sep 17 00:00:00 2001 From: Nico Kempe Date: Sat, 20 Sep 2025 21:23:03 +0200 Subject: [PATCH 3/4] docs(readme): polish wording --- README.md | 64 +++++++++++++++++++++++++++---------------------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 1c2098ee6..006165bc0 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ It is originally based on the excellent If you wish to contribute to the project, please refer to the [contributing guide](/CONTRIBUTING.md). -## Table Of Contents +## Table of Contents - [Quick Start](#quick-start) - [Running in Production](#running-in-production) @@ -25,9 +25,9 @@ If you wish to contribute to the project, please refer to the [contributing guid ## Quick Start -Create a `.env` file to store your own custom env vars. See [`example.env`](example.env) +Create a `.env` file to store your own custom environment variables. See [`example.env`](example.env) -1. Start the local postgres database in a postgres container: `docker-compose -f docker-compose-dev.yml up postgres` +1. Start the local Postgres database in a Postgres container: `docker-compose -f docker-compose-dev.yml up postgres` 2. Build the auth binary: `make build` . You should see an output like this: ```bash @@ -37,14 +37,14 @@ GOOS=linux GOARCH=arm64 go build -ldflags "-X github.com/supabase/auth/cmd.Versi 3. Execute the auth binary: `./auth` -### If you have docker installed +### If you have Docker installed Create a `.env.docker` file to store your own custom env vars. See [`example.docker.env`](example.docker.env) 1. `make build` 2. `make dev` -3. `docker ps` should show 2 docker containers (`auth-auth-1` and `auth-postgres-1`) -4. That's it! Visit the [health checkendpoint](http://localhost:9999/health) to confirm that auth is running. +3. `docker ps` should show two Docker containers (`auth-auth-1` and `auth-postgres-1`) +4. That's it! Visit the [health check endpoint](http://localhost:9999/health) to confirm that auth is running. ## Running in production @@ -52,7 +52,7 @@ Running an authentication server in production is not an easy feat. We recommend using [Supabase Auth](https://supabase.com/auth) which gets regular security updates. -Otherwise, please make sure you setup a process to promptly update to the +Otherwise, please make sure you set up a process to promptly update to the latest version. You can do that by following this repository, specifically the [Releases](https://github.com/supabase/auth/releases) and [Security Advisories](https://github.com/supabase/auth/security/advisories) sections. @@ -65,8 +65,8 @@ further clarifications on backward compatibility guarantees: **Go API compatibility** Auth is not meant to be used as a Go library. There are no guarantees on -backward API compatibility when used this way regardless which version number -changes. +backward API compatibility when used this way regardless of which version +number changes. **Patch** @@ -145,7 +145,7 @@ comprehensive list of those features: 3. Super admin via the `is_super_admin` column. 4. Group information in JWTs via `GOTRUE_JWT_ADMIN_GROUP_NAME` and other configuration fields. -5. Symmetrics JWTs. In the future it is very likely that Auth will begin +5. Symmetric JWTs. In the future it is very likely that Auth will begin issuing asymmetric JWTs (subject to configuration), so do not rely on the assumption that only HS256 signed JWTs will be issued long term. @@ -158,7 +158,7 @@ compatibility with Auth: 1. Do not modify the schema managed by Auth. You can see all of the migrations in the `migrations` directory. -2. Do not rely on schema and structure of data in the database. Always use +2. Do not rely on the schema and the structure of data in the database. Always use Auth APIs and JWTs to infer information about users. 3. Always run Auth behind a TLS-capable proxy such as a load balancer, CDN, nginx or other similar software. @@ -180,7 +180,7 @@ The base URL your site is located at. Currently used in combination with other s `URI_ALLOW_LIST` - `string` -A comma separated list of URIs (e.g. `"https://foo.example.com,https://*.foo.example.com,https://bar.example.com"`) which are permitted as valid `redirect_to` destinations. Defaults to []. Supports wildcard matching through globbing. e.g. `https://*.foo.example.com` will allow `https://a.foo.example.com` and `https://b.foo.example.com` to be accepted. Globbing is also supported on subdomains. e.g. `https://foo.example.com/*` will allow `https://foo.example.com/page1` and `https://foo.example.com/page2` to be accepted. +A comma-separated list of URIs (e.g. `"https://foo.example.com,https://*.foo.example.com,https://bar.example.com"`) which are permitted as valid `redirect_to` destinations. Defaults to []. Supports wildcard matching through globbing. e.g. `https://*.foo.example.com` will allow `https://a.foo.example.com` and `https://b.foo.example.com` to be accepted. Globbing is also supported on subdomains. e.g. `https://foo.example.com/*` will allow `https://foo.example.com/page1` and `https://foo.example.com/page2` to be accepted. For more common glob patterns, check out the [following link](https://pkg.go.dev/github.com/gobwas/glob#Compile). @@ -195,11 +195,11 @@ When signup is disabled the only way to create new users is through invites. Def `GOTRUE_EXTERNAL_EMAIL_ENABLED` - `bool` -Use this to disable email signups (users can still use external oauth providers to sign up / sign in) +Use this to disable email signups (users can still use external OAuth providers to sign up / sign in) `GOTRUE_EXTERNAL_PHONE_ENABLED` - `bool` -Use this to disable phone signups (users can still use external oauth providers to sign up / sign in) +Use this to disable phone signups (users can still use external OAuth providers to sign up / sign in) `GOTRUE_RATE_LIMIT_HEADER` - `string` @@ -207,7 +207,7 @@ Header on which to rate limit the `/token` endpoint. `GOTRUE_RATE_LIMIT_EMAIL_SENT` - `string` -Rate limit the number of emails sent per hr on the following endpoints: `/signup`, `/invite`, `/magiclink`, `/recover`, `/otp`, & `/user`. +Rate limit the number of emails sent per hour on the following endpoints: `/signup`, `/invite`, `/magiclink`, `/recover`, `/otp`, & `/user`. `GOTRUE_PASSWORD_MIN_LENGTH` - `int` @@ -217,7 +217,7 @@ Minimum password length, defaults to 6. `GOTRUE_SECURITY_REFRESH_TOKEN_ROTATION_ENABLED` - `bool` -If refresh token rotation is enabled, auth will automatically detect malicious attempts to reuse a revoked refresh token. When a malicious attempt is detected, gotrue immediately revokes all tokens that descended from the offending token. +If refresh token rotation is enabled, auth will automatically detect malicious attempts to reuse a revoked refresh token. When a malicious attempt is detected, GoTrue immediately revokes all tokens that descended from the offending token. `GOTRUE_SECURITY_REFRESH_TOKEN_REUSE_INTERVAL` - `string` @@ -247,7 +247,7 @@ Controls what endpoint Netlify can access this API on. `API_EXTERNAL_URL` - `string` **required** -The URL on which Gotrue might be accessed at. +The URL on which GoTrue might be accessed at. `REQUEST_ID_HEADER` - `string` @@ -307,7 +307,7 @@ Auth has basic observability built in. It is able to export To enable tracing configure these variables: -`GOTRUE_TRACING_ENABLED` - `boolean` +`GOTRUE_TRACING_ENABLED` - `bool` `GOTRUE_TRACING_EXPORTER` - `string` only `opentelemetry` supported @@ -498,7 +498,7 @@ To try out external authentication with Apple locally, you will need to do the f 3. Generate the crt and key file. See [here](https://www.freecodecamp.org/news/how-to-get-https-working-on-your-local-development-environment-in-5-minutes-7af615770eec/) for more information. 4. Generate the `GOTRUE_EXTERNAL_APPLE_SECRET` by following this [post](https://medium.com/identity-beyond-borders/how-to-configure-sign-in-with-apple-77c61e336003)! -### E-Mail +### Email Sending email is not required, but highly recommended for password recovery. If enabled, you must provide the required values below. @@ -546,7 +546,7 @@ If you do not require email confirmation, you may set this to `true`. Defaults t `MAILER_OTP_EXP` - `number` -Controls the duration an email link or otp is valid for. +Controls the duration an email link or OTP is valid for. `MAILER_URLPATHS_INVITE` - `string` @@ -668,15 +668,15 @@ If you do not require phone confirmation, you may set this to `true`. Defaults t `SMS_MAX_FREQUENCY` - `number` -Controls the minimum amount of time that must pass before sending another sms otp. The value is the number of seconds. Defaults to 60 (1 minute)). +Controls the minimum amount of time that must pass before sending another SMS OTP. The value is the number of seconds. Defaults to 60 (1 minute). `SMS_OTP_EXP` - `number` -Controls the duration an sms otp is valid for. +Controls the duration an SMS OTP is valid for. `SMS_OTP_LENGTH` - `number` -Controls the number of digits of the sms otp sent. +Controls the number of digits of the SMS OTP sent. `SMS_PROVIDER` - `string` @@ -703,7 +703,7 @@ Whether captcha middleware is enabled `SECURITY_CAPTCHA_PROVIDER` - `string` -for now the only options supported are: `hcaptcha` and `turnstile` +for now the only options supported are: hCaptcha and Turnstile - `SECURITY_CAPTCHA_SECRET` - `string` - `SECURITY_CAPTCHA_TIMEOUT` - `string` @@ -746,7 +746,7 @@ Returns the publicly available settings for this auth instance. "linkedin": true, "notion": true, "slack": true, - "snapchat": true, + "snapchat": true, "spotify": true, "twitch": true, "twitter": true, @@ -958,7 +958,7 @@ Returns: } ``` -Verify a phone signup or sms otp. Type should be set to `sms`. +Verify a phone signup or SMS OTP. Type should be set to `sms`. ```json { @@ -1008,7 +1008,7 @@ or show an account confirmed/welcome message in the case of `signup`, or direct ### **POST /otp** -One-Time-Password. Will deliver a magiclink or sms otp to the user depending on whether the request body contains an "email" or "phone" key. +One-Time-Password. Will deliver a magic link or SMS OTP to the user depending on whether the request body contains an "email" or "phone" key. If `"create_user": true`, user will not be automatically signed up if the user doesn't exist. @@ -1054,7 +1054,7 @@ Returns: {} ``` -when clicked the magic link will redirect the user to `#access_token=x&refresh_token=y&expires_in=z&token_type=bearer&type=magiclink` (see `/verify` above) +When the magic link is clicked, it will redirect to `#access_token=x&refresh_token=y&expires_in=z&token_type=bearer&type=magiclink` (see `/verify` above) ### **POST /recover** @@ -1151,7 +1151,7 @@ Returns: ### **PUT /user** Update a user (Requires authentication). Apart from changing email/password, this -method can be used to set custom user data. Changing the email will result in a magiclink being sent out. +method can be used to set custom user data. Changing the email will result in a magic link being sent out. ```json { @@ -1204,7 +1204,7 @@ headers: { Logout a user (Requires authentication). This will revoke all refresh tokens for the user. Remember that the JWT tokens -will still be valid for stateless auth until they expires. +will still be valid for stateless auth until they expire. ### **GET /authorize** @@ -1220,11 +1220,11 @@ scopes= +For Apple-specific setup see: ### **GET /callback** -External provider should redirect to here +External provider should redirect to this endpoint Redirects to `#access_token=&refresh_token=&provider_token=&expires_in=3600&provider=` If additional scopes were requested then `provider_token` will be populated, you can use this to fetch additional data from the provider or interact with their services From 5c038decee777dd6c8981d1374a060c8e9b89a90 Mon Sep 17 00:00:00 2001 From: Nico Kempe Date: Sat, 20 Sep 2025 21:35:29 +0200 Subject: [PATCH 4/4] docs(readme): update inherited features with current JWT signing key support --- README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 006165bc0..13d298a27 100644 --- a/README.md +++ b/README.md @@ -145,9 +145,12 @@ comprehensive list of those features: 3. Super admin via the `is_super_admin` column. 4. Group information in JWTs via `GOTRUE_JWT_ADMIN_GROUP_NAME` and other configuration fields. -5. Symmetric JWTs. In the future it is very likely that Auth will begin - issuing asymmetric JWTs (subject to configuration), so do not rely on the - assumption that only HS256 signed JWTs will be issued long term. +5. JWT signing. Supabase Auth supports asymmetric keys (RS256 by default; + ECC/Ed25519 optional). HS256 is still supported for compatibility, but + migrating to asymmetric keys is recommended for easier validation and + rotation. Future deprecations will be announced in the changelog. See the + [JWT Signing Keys](https://supabase.com/docs/guides/auth/signing-keys) and + [JWTs guide](https://supabase.com/docs/guides/auth/jwts) for details. Note that this is not an exhaustive list and it may change.