Auth - Authentication and User Management by Supabase

Auth is a user management and authentication server written in Go that powers Supabase's features such as:

• Issuing JWTs
• Row Level Security with PostgREST
• User management
• Sign in with email, password, magic link, phone number
• Sign in with external providers (Google, Apple, Facebook, Discord, ...)

It is originally based on the excellent GoTrue codebase by Netlify, however both have diverged significantly in features and capabilities.

If you wish to contribute to the project, please refer to the contributing guide.

Table of Contents

• Quick Start
• Running in Production
• Configuration
• Endpoints

Quick Start

Create a .env file to store your own custom environment variables. See example.env

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:

go build -ldflags "-X github.com/supabase/auth/cmd.Version=`git rev-parse HEAD`"
GOOS=linux GOARCH=arm64 go build -ldflags "-X github.com/supabase/auth/cmd.Version=`git rev-parse HEAD`" -o gotrue-arm64

1. Execute the auth binary: ./auth

If you have Docker installed

Create a .env.docker file to store your own custom env vars. See example.docker.env

1. make build
2. make dev
3. docker ps should show two Docker containers (auth-auth-1 and auth-postgres-1)
4. That's it! Visit the health check endpoint to confirm that auth is running.

Running in production

Running an authentication server in production is not an easy feat. We recommend using Supabase Auth which gets regular security updates.

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 and Security Advisories sections.

Backward compatibility

Auth uses the Semantic Versioning scheme. Here are some 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 of which version number changes.

Patch

Changes to the patch version guarantees backward compatibility with:

• Database objects (tables, columns, indexes, functions).
• REST API
• JWT structure
• Configuration

Guaranteed examples:

• A column won't change its type.
• A table won't change its primary key.
• An index will not be removed.
• A uniqueness constraint will not be removed.
• A REST API will not be removed.
• Parameters to REST APIs will work equivalently as before (or better, if a bug has been fixed).
• Configuration will not change.

Not guaranteed examples:

• A table may add new columns.
• Columns in a table may be reordered.
• Non-unique constraints may be removed (database level checks, null, default values).
• JWT may add new properties.

Minor

Changes to minor version guarantees backward compatibility with:

• REST API
• JWT structure
• Configuration

Exceptions to these guarantees will be made only when serious security issues are found that can't be remedied in any other way.

Guaranteed examples:

• Existing APIs may be deprecated but continue working for the next few minor version releases.
• Configuration changes may become deprecated but continue working for the next few minor version releases.
• Already issued JWTs will be accepted, but new JWTs may be with a different structure (but usually similar).

Not guaranteed examples:

• Removal of JWT fields after a deprecation notice.
• Removal of certain APIs after a deprecation notice.
• Removal of sign-in with external providers, after a deprecation notice.
• Deletion, truncation, significant schema changes to tables, indexes, views, functions.

We aim to provide a deprecation notice in execution logs for at least two major version releases or two weeks if multiple releases go out. Compatibility will be guaranteed while the notice is live.

Major

Changes to the major version do not guarantee any backward compatibility with previous versions.

Inherited features

Certain inherited features from the Netlify codebase are not supported by Supabase and they may be removed without prior notice in the future. This is a comprehensive list of those features:

1. Multi-tenancy via the instances table i.e. GOTRUE_MULTI_INSTANCE_MODE configuration parameter.
2. System user (zero UUID user).
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. 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 and JWTs guide for details.

Note that this is not an exhaustive list and it may change.

Best practices when self-hosting

These are some best practices to follow when self-hosting to ensure backward 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 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.

Configuration

You may configure Auth using either a configuration file named .env, environment variables, or a combination of both. Environment variables are prefixed with GOTRUE_, and will always have precedence over values provided via file.

Top-Level

GOTRUE_SITE_URL=https://example.netlify.com/

SITE_URL - string required

The base URL your site is located at. Currently used in combination with other settings to construct URLs used in emails. Any URI that shares a host with SITE_URL is a permitted value for redirect_to params (see /authorize etc.).

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.

For more common glob patterns, check out the following link.

OPERATOR_TOKEN - string Multi-instance mode only

The shared secret with an operator (usually Netlify) for this microservice. Used to verify requests have been proxied through the operator and the payload values can be trusted.

DISABLE_SIGNUP - bool

When signup is disabled the only way to create new users is through invites. Defaults to false, all signups enabled.

GOTRUE_EXTERNAL_EMAIL_ENABLED - bool

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)

GOTRUE_RATE_LIMIT_HEADER - string

Header on which to rate limit the /token endpoint. This header is expected to be set by a trusted upstream proxy (such as Kong or Envoy). Headers such as x-forwarded-for are spoofable and can not be trusted for rate limiting when supplied directly by the client.

GOTRUE_RATE_LIMIT_EMAIL_SENT - string

Rate limit the number of emails sent per hour on the following endpoints: /signup, /invite, /magiclink, /recover, /otp, & /user.

GOTRUE_PASSWORD_MIN_LENGTH - int

Minimum password length, defaults to 6.

GOTRUE_PASSWORD_REQUIRED_CHARACTERS - a string of character sets separated by :. A password must contain at least one character of each set to be accepted. To use the : character escape it with \.

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.

GOTRUE_SECURITY_REFRESH_TOKEN_REUSE_INTERVAL - string

This setting is only applicable if GOTRUE_SECURITY_REFRESH_TOKEN_ROTATION_ENABLED is enabled. The reuse interval for a refresh token allows for exchanging the refresh token multiple times during the interval to support concurrency or offline issues. During the reuse interval, auth will not consider using a revoked token as a malicious attempt and will simply return the child refresh token.

Only the previous revoked token can be reused. Using an old refresh token way before the current valid refresh token will trigger the reuse detection.

API

GOTRUE_API_HOST=localhost
PORT=9999
API_EXTERNAL_URL=http://localhost:9999

API_HOST - string

Hostname to listen on.

PORT (no prefix) / API_PORT - number

Port number to listen on. Defaults to 8081.

API_ENDPOINT - string Multi-instance mode only

Controls what endpoint Netlify can access this API on.

API_EXTERNAL_URL - string required

The URL on which GoTrue might be accessed at.

REQUEST_ID_HEADER - string

If you wish to inherit a request ID from the incoming request, specify the name in this value.

Database

GOTRUE_DB_DRIVER=postgres
DATABASE_URL=root@localhost/auth

DB_DRIVER - string required

Chooses what dialect of database you want. Must be postgres.

DATABASE_URL (no prefix) / DB_DATABASE_URL - string required

Connection string for the database.

GOTRUE_DB_MAX_POOL_SIZE - int

Sets the maximum number of open connections to the database. Defaults to 0 which is equivalent to an "unlimited" number of connections.

DB_NAMESPACE - string

Adds a prefix to all table names.

Migrations Note

Migrations are applied automatically when you run ./auth. However, you also have the option to rerun the migrations via the following methods:

• If built locally: ./auth migrate
• Using Docker: docker run --rm auth gotrue migrate

Logging

LOG_LEVEL=debug # available without GOTRUE prefix (exception)
GOTRUE_LOG_FILE=/var/log/go/auth.log

LOG_LEVEL - string

Controls what log levels are output. Choose from panic, fatal, error, warn, info, or debug. Defaults to info.

LOG_FILE - string

If you wish logs to be written to a file, set log_file to a valid file path.

Observability

Auth has basic observability built in. It is able to export OpenTelemetry metrics and traces to a collector.

Tracing

To enable tracing configure these variables:

GOTRUE_TRACING_ENABLED - bool

GOTRUE_TRACING_EXPORTER - string only opentelemetry supported

Make sure you also configure the OpenTelemetry Exporter configuration for your collector or service.

For example, if you use Honeycomb.io you should set these standard OpenTelemetry OTLP variables:

OTEL_SERVICE_NAME=auth
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io:443
OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=<API-KEY>,x-honeycomb-dataset=auth"

Metrics

To enable metrics configure these variables:

GOTRUE_METRICS_ENABLED - boolean

GOTRUE_METRICS_EXPORTER - string only opentelemetry and prometheus supported

Make sure you also configure the OpenTelemetry Exporter configuration for your collector or service.

If you use the prometheus exporter, the server host and port can be configured using these standard OpenTelemetry variables:

OTEL_EXPORTER_PROMETHEUS_HOST - IP address, default 0.0.0.0

OTEL_EXPORTER_PROMETHEUS_PORT - port number, default 9100

The metrics are exported on the / path on the server.

If you use the opentelemetry exporter, the metrics are pushed to the collector.

For example, if you use Honeycomb.io you should set these standard OpenTelemetry OTLP variables:

OTEL_SERVICE_NAME=auth
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io:443
OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=<API-KEY>,x-honeycomb-dataset=auth"

Note that Honeycomb.io requires a paid plan to ingest metrics.

If you need to debug an issue with traces or metrics not being pushed, you can set DEBUG=true to get more insights from the OpenTelemetry SDK.

Custom resource attributes

When using the OpenTelemetry tracin