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 diff --git a/README.md b/README.md index 1c2098ee6..13d298a27 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,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. Symmetrics 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. @@ -158,7 +161,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 +183,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 +198,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 +210,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 +220,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 +250,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 +310,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 +501,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 +549,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 +671,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 +706,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 +749,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 +961,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 +1011,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 +1057,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 +1154,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 +1207,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 +1223,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 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=""