524 lines
16 KiB
Markdown
524 lines
16 KiB
Markdown
# CONTRIBUTING
|
|
|
|
We would love to have contributions from each and every one of you in the community be it big or small and you are the ones who motivate us to do better than what we do today.
|
|
|
|
## Code Of Conduct
|
|
|
|
Please help us keep all our projects open and inclusive. Kindly follow our [Code of Conduct](CODE_OF_CONDUCT.md) to keep the ecosystem healthy and friendly for all.
|
|
|
|
## Quick Start
|
|
|
|
Auth has a development container setup that makes it easy to get started contributing. This setup only requires that [Docker](https://www.docker.com/get-started) is setup on your system. The development container setup includes a PostgreSQL container with migrations already applied and a container running GoTrue that will perform a hot reload when changes to the source code are detected.
|
|
|
|
If you would like to run Auth locally or learn more about what these containers are doing for you, continue reading the [Setup and Tooling](#setup-and-tooling) section below. Otherwise, you can skip ahead to the [How To Verify that GoTrue is Available](#how-to-verify-that-auth-is-available) section to learn about working with and developing GoTrue.
|
|
|
|
Before using the containers, you will need to make sure an `.env.docker` file exists by making a copy of `example.docker.env` and configuring it for your needs. The set of env vars in `example.docker.env` only contain the necessary env vars for auth to start in a docker environment. For the full list of env vars, please refer to `example.env` and copy over the necessary ones into your `.env.docker` file.
|
|
|
|
The following are some basic commands. A full and up to date list of commands can be found in the project's `Makefile` or by running `make help`.
|
|
|
|
### Starting the containers
|
|
|
|
Start the containers as described above in an attached state with log output.
|
|
|
|
```bash
|
|
make dev
|
|
```
|
|
|
|
### Running tests in the containers
|
|
|
|
Start the containers with a fresh database and run the project's tests.
|
|
|
|
```bash
|
|
make docker-test
|
|
```
|
|
|
|
### Removing the containers
|
|
|
|
Remove both containers and their volumes. This removes any data associated with the containers.
|
|
|
|
```bash
|
|
make docker-clean
|
|
```
|
|
|
|
### Rebuild the containers
|
|
|
|
Fully rebuild the containers without using any cached layers.
|
|
|
|
```bash
|
|
make docker-build
|
|
```
|
|
|
|
## Setup and Tooling
|
|
|
|
Auth -- as the name implies -- is a user registration and authentication API developed in [Go](https://go.dev).
|
|
|
|
It connects to a [PostgreSQL](https://www.postgresql.org) database in order to store authentication data, [Soda CLI](https://gobuffalo.io/en/docs/db/toolbox) to manage database schema and migrations,
|
|
and runs inside a [Docker](https://www.docker.com/get-started) container.
|
|
|
|
Therefore, to contribute to Auth you will need to install these tools.
|
|
|
|
### Install Tools
|
|
|
|
- Install [Go](https://go.dev) 1.22
|
|
|
|
```zsh
|
|
# Via Homebrew on macOS
|
|
brew install go@1.22
|
|
|
|
# Set the environment variable in the ~/.zshrc file
|
|
echo 'export PATH="/opt/homebrew/opt/go@1.22/bin:$PATH"' >> ~/.zshrc
|
|
```
|
|
|
|
- Install [Docker](https://www.docker.com/get-started)
|
|
|
|
```zsh
|
|
# Via Homebrew on macOS
|
|
brew install docker
|
|
```
|
|
|
|
Or, if you prefer, download [Docker Desktop](https://www.docker.com/get-started).
|
|
|
|
- Install [Soda CLI](https://gobuffalo.io/en/docs/db/toolbox)
|
|
|
|
```zsh
|
|
# Via Homebrew on macOS
|
|
brew install gobuffalo/tap/pop
|
|
```
|
|
|
|
If you are on macOS Catalina you may [run into issues installing Soda with Brew](https://github.com/gobuffalo/homebrew-tap/issues/5). Do check your `GOPATH` and run
|
|
|
|
`go build -o /bin/soda github.com/gobuffalo/pop/soda` to resolve.
|
|
|
|
- Clone the Auth [repository](https://github.com/supabase/auth)
|
|
|
|
```zsh
|
|
git clone https://github.com/supabase/auth
|
|
```
|
|
|
|
### Install Auth
|
|
|
|
To begin installation, be sure to start from the root directory.
|
|
|
|
- `cd auth`
|
|
|
|
To complete installation, you will:
|
|
|
|
- Install the PostgreSQL Docker image
|
|
- Create the DB Schema and Migrations
|
|
- Setup a local `.env` for environment variables
|
|
- Compile Auth
|
|
- Run the Auth binary executable
|
|
|
|
#### Installation Steps
|
|
|
|
1. Start Docker
|
|
2. To install the PostgreSQL Docker image, run:
|
|
|
|
```zsh
|
|
# Builds the postgres image
|
|
docker-compose -f docker-compose-dev.yml build postgres
|
|
|
|
# Runs the postgres container
|
|
docker-compose -f docker-compose-dev.yml up postgres
|
|
```
|
|
|
|
You should then see in Docker that `auth_postgresql` is running on `port: 5432`.
|
|
|
|
> **Important** If you happen to already have a local running instance of Postgres running on the port `5432` because you
|
|
> may have installed via [homebrew on macOS](https://formulae.brew.sh/formula/postgresql) then be certain to stop the process using:
|
|
>
|
|
> - `brew services stop postgresql`
|
|
>
|
|
> If you need to run the test environment on another port, you will need to modify several configuration files to use a different custom port.
|
|
|
|
3. Next compile the Auth binary:
|
|
|
|
When you fork a repository, GitHub does not automatically copy all the tags (tags are not included by default). To ensure the correct tag is set before building the binary, you need to fetch the tags from the upstream repository and push them to your fork. Follow these steps:
|
|
|
|
```zsh
|
|
# Fetch the tags from the upstream repository
|
|
git fetch upstream --tags
|
|
|
|
# Push the tags to your fork
|
|
git push origin --tags
|
|
```
|
|
|
|
Then build the binary by running:
|
|
|
|
```zsh
|
|
make build
|
|
```
|
|
|
|
4. To setup the database schema via Soda, run:
|
|
|
|
```zsh
|
|
make migrate_test
|
|
```
|
|
|
|
You should see log messages that indicate that the Auth migrations were applied successfully:
|
|
|
|
```terminal
|
|
INFO[0000] Auth migrations applied successfully
|
|
DEBU[0000] after status
|
|
[POP] 2021/12/15 10:44:36 sql - SELECT EXISTS (SELECT schema_migrations.* FROM schema_migrations AS schema_migrations WHERE version = $1) | ["20210710035447"]
|
|
[POP] 2021/12/15 10:44:36 sql - SELECT EXISTS (SELECT schema_migrations.* FROM schema_migrations AS schema_migrations WHERE version = $1) | ["20210722035447"]
|
|
[POP] 2021/12/15 10:44:36 sql - SELECT EXISTS (SELECT schema_migrations.* FROM schema_migrations AS schema_migrations WHERE version = $1) | ["20210730183235"]
|
|
[POP] 2021/12/15 10:44:36 sql - SELECT EXISTS (SELECT schema_migrations.* FROM schema_migrations AS schema_migrations WHERE version = $1) | ["20210909172000"]
|
|
[POP] 2021/12/15 10:44:36 sql - SELECT EXISTS (SELECT schema_migrations.* FROM schema_migrations AS schema_migrations WHERE version = $1) | ["20211122151130"]
|
|
Version Name Status
|
|
20210710035447 alter_users Applied
|
|
20210722035447 adds_confirmed_at Applied
|
|
20210730183235 add_email_change_confirmed Applied
|
|
20210909172000 create_identities_table Applied
|
|
20211122151130 create_user_id_idx Applied
|
|
```
|
|
|
|
That lists each migration that was applied. Note: there may be more migrations than those listed.
|
|
|
|
4. Create a `.env` file in the root of the project and copy the following config in [example.env](example.env). Set the values to GOTRUE_SMS_TEST_OTP_VALID_UNTIL in the `.env` file.
|
|
|
|
5. In order to have Auth connect to your PostgreSQL database running in Docker, it is important to set a connection string like:
|
|
|
|
```
|
|
DATABASE_URL="postgres://supabase_auth_admin:root@localhost:5432/postgres"
|
|
```
|
|
|
|
> Important: Auth requires a set of SMTP credentials to run, you can generate your own SMTP credentials via an SMTP provider such as AWS SES, SendGrid, MailChimp, SendInBlue or any other SMTP providers.
|
|
|
|
6. Then finally Start Auth
|
|
7. Verify that Auth is Available
|
|
|
|
### Starting Auth
|
|
|
|
Start Auth by running the executable:
|
|
|
|
```zsh
|
|
./auth
|
|
```
|
|
|
|
This command will re-run migrations and then indicate that Auth has started:
|
|
|
|
```zsh
|
|
INFO[0000] Auth API started on: localhost:9999
|
|
```
|
|
|
|
### How To Verify that Auth is Available
|
|
|
|
To test that your Auth is up and available, you can query the `health` endpoint at `http://localhost:9999/health`. You should see a response similar to:
|
|
|
|
```json
|
|
{
|
|
"description": "Auth is a user registration and authentication API",
|
|
"name": "Auth",
|
|
"version": ""
|
|
}
|
|
```
|
|
|
|
To see the current settings, make a request to `http://localhost:9999/settings` and you should see a response similar to:
|
|
|
|
```json
|
|
{
|
|
"external": {
|
|
"apple": false,
|
|
"azure": false,
|
|
"bitbucket": false,
|
|
"discord": false,
|
|
"github": false,
|
|
"gitlab": false,
|
|
"google": false,
|
|
"facebook": false,
|
|
"spotify": false,
|
|
"slack": false,
|
|
"slack_oidc": false,
|
|
"twitch": true,
|
|
"twitter": false,
|
|
"email": true,
|
|
"phone": false,
|
|
"saml": false
|
|
},
|
|
"external_labels": {
|
|
"saml": "auth0"
|
|
},
|
|
"disable_signup": false,
|
|
"mailer_autoconfirm": false,
|
|
"phone_autoconfirm": false,
|
|
"sms_provider": "twilio"
|
|
}
|
|
```
|
|
|
|
## How to Use Admin API Endpoints
|
|
|
|
To test the admin endpoints (or other api endpoints), you can invoke via HTTP requests. Using [Insomnia](https://insomnia.rest/products/insomnia) can help you issue these requests.
|
|
|
|
You will need to know the `GOTRUE_JWT_SECRET` configured in the `.env` settings.
|
|
|
|
Also, you must generate a JWT with the signature which has the `supabase_admin` role (or one that is specified in `GOTRUE_JWT_ADMIN_ROLES`).
|
|
|
|
For example:
|
|
|
|
```json
|
|
{
|
|
"role": "supabase_admin"
|
|
}
|
|
```
|
|
|
|
You can sign this payload using the [JWT.io Debugger](https://jwt.io/#debugger-io) but make sure that `secret base64 encoded` is unchecked.
|
|
|
|
Then you can use this JWT as a Bearer token for admin requests.
|
|
|
|
### Create User (aka Sign Up a User)
|
|
|
|
To create a new user, `POST /admin/users` with the payload:
|
|
|
|
```json
|
|
{
|
|
"email": "user@example.com",
|
|
"password": "12345678"
|
|
}
|
|
```
|
|
|
|
#### Request
|
|
|
|
```
|
|
POST /admin/users HTTP/1.1
|
|
Host: localhost:9999
|
|
User-Agent: insomnia/2021.7.2
|
|
Content-Type: application/json
|
|
Authorization: Bearer <YOUR_SIGNED_JWT>
|
|
Accept: */*
|
|
Content-Length: 57
|
|
```
|
|
|
|
#### Response
|
|
|
|
And you should get a new user:
|
|
|
|
```json
|
|
{
|
|
"id": "e78c512d-68e4-482b-901b-75003e89acae",
|
|
"aud": "authenticated",
|
|
"role": "authenticated",
|
|
"email": "user@example.com",
|
|
"phone": "",
|
|
"app_metadata": {
|
|
"provider": "email",
|
|
"providers": ["email"]
|
|
},
|
|
"user_metadata": {},
|
|
"identities": null,
|
|
"created_at": "2021-12-15T12:40:03.507551-05:00",
|
|
"updated_at": "2021-12-15T12:40:03.512067-05:00"
|
|
}
|
|
```
|
|
|
|
### List/Find Users
|
|
|
|
To create a new user, make a request to `GET /admin/users`.
|
|
|
|
#### Request
|
|
|
|
```
|
|
GET /admin/users HTTP/1.1
|
|
Host: localhost:9999
|
|
User-Agent: insomnia/2021.7.2
|
|
Authorization: Bearer <YOUR*SIGNED_JWT>
|
|
Accept: */\_
|
|
```
|
|
|
|
#### Response
|
|
|
|
The response from `/admin/users` should return all users:
|
|
|
|
```json
|
|
{
|
|
"aud": "authenticated",
|
|
"users": [
|
|
{
|
|
"id": "b7fd0253-6e16-4d4e-b61b-5943cb1b2102",
|
|
"aud": "authenticated",
|
|
"role": "authenticated",
|
|
"email": "user+4@example.com",
|
|
"phone": "",
|
|
"app_metadata": {
|
|
"provider": "email",
|
|
"providers": ["email"]
|
|
},
|
|
"user_metadata": {},
|
|
"identities": null,
|
|
"created_at": "2021-12-15T12:43:58.12207-05:00",
|
|
"updated_at": "2021-12-15T12:43:58.122073-05:00"
|
|
},
|
|
{
|
|
"id": "d69ae847-99be-4642-868f-439c2cdd9af4",
|
|
"aud": "authenticated",
|
|
"role": "authenticated",
|
|
"email": "user+3@example.com",
|
|
"phone": "",
|
|
"app_metadata": {
|
|
"provider": "email",
|
|
"providers": ["email"]
|
|
},
|
|
"user_metadata": {},
|
|
"identities": null,
|
|
"created_at": "2021-12-15T12:43:56.730209-05:00",
|
|
"updated_at": "2021-12-15T12:43:56.730213-05:00"
|
|
},
|
|
{
|
|
"id": "7282cf42-344e-4474-bdf6-d48e4968a2e4",
|
|
"aud": "authenticated",
|
|
"role": "authenticated",
|
|
"email": "user+2@example.com",
|
|
"phone": "",
|
|
"app_metadata": {
|
|
"provider": "email",
|
|
"providers": ["email"]
|
|
},
|
|
"user_metadata": {},
|
|
"identities": null,
|
|
"created_at": "2021-12-15T12:43:54.867676-05:00",
|
|
"updated_at": "2021-12-15T12:43:54.867679-05:00"
|
|
},
|
|
{
|
|
"id": "e78c512d-68e4-482b-901b-75003e89acae",
|
|
"aud": "authenticated",
|
|
"role": "authenticated",
|
|
"email": "user@example.com",
|
|
"phone": "",
|
|
"app_metadata": {
|
|
"provider": "email",
|
|
"providers": ["email"]
|
|
},
|
|
"user_metadata": {},
|
|
"identities": null,
|
|
"created_at": "2021-12-15T12:40:03.507551-05:00",
|
|
"updated_at": "2021-12-15T12:40:03.507554-05:00"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Running Database Migrations
|
|
|
|
If you need to run any new migrations:
|
|
|
|
```zsh
|
|
make migrate_test
|
|
```
|
|
|
|
## Testing
|
|
|
|
Currently, we don't use a separate test database, so the same database created when installing Auth to run locally is used.
|
|
|
|
The following commands should help in setting up a database and running the tests:
|
|
|
|
```sh
|
|
# Runs the database in a docker container
|
|
$ docker-compose -f docker-compose-dev.yml up postgres
|
|
|
|
# Applies the migrations to the database (requires soda cli)
|
|
$ make migrate_test
|
|
|
|
# Executes the tests
|
|
$ make test
|
|
```
|
|
|
|
### Customizing the PostgreSQL Port
|
|
|
|
if you already run PostgreSQL and need to run your database on a different, custom port,
|
|
you will need to make several configuration changes to the following files:
|
|
|
|
In these examples, we change the port from 5432 to 7432.
|
|
|
|
> Note: This is not recommended, but if you do, please do not check in changes.
|
|
|
|
```
|
|
// file: docker-compose-dev.yml
|
|
ports:
|
|
- 7432:5432 \ 👈 set the first value to your external facing port
|
|
```
|
|
|
|
The port you customize here can them be used in the subsequent configuration:
|
|
|
|
```
|
|
// file: database.yaml
|
|
test:
|
|
dialect: "postgres"
|
|
database: "postgres"
|
|
host: {{ envOr "POSTGRES_HOST" "127.0.0.1" }}
|
|
port: {{ envOr "POSTGRES_PORT" "7432" }} 👈 set to your port
|
|
```
|
|
|
|
```
|
|
// file: test.env
|
|
DATABASE_URL="postgres://supabase_auth_admin:root@localhost:7432/postgres" 👈 set to your port
|
|
```
|
|
|
|
```
|
|
// file: migrate.sh
|
|
export GOTRUE_DB_DATABASE_URL="postgres://supabase_auth_admin:root@localhost:7432/$DB_ENV"
|
|
```
|
|
|
|
## Helpful Docker Commands
|
|
|
|
```
|
|
// file: docker-compose-dev.yml
|
|
container_name: auth_postgres
|
|
```
|
|
|
|
```zsh
|
|
# Command line into bash on the PostgreSQL container
|
|
docker exec -it auth_postgres bash
|
|
|
|
# Removes Container
|
|
docker container rm -f auth_postgres
|
|
|
|
# Removes volume
|
|
docker volume rm postgres_data
|
|
```
|
|
|
|
## Updating Package Dependencies
|
|
|
|
- `make deps`
|
|
- `go mod tidy` if necessary
|
|
|
|
## Submitting Pull Requests
|
|
|
|
We actively welcome your pull requests.
|
|
|
|
- Fork the repo and create your branch from `master`.
|
|
- If you've added code that should be tested, add tests.
|
|
- If you've changed APIs, update the documentation.
|
|
- Ensure the test suite passes.
|
|
- Make sure your code lints.
|
|
|
|
### Checklist for Submitting Pull Requests
|
|
|
|
- Is there a corresponding issue created for it? If so, please include it in the PR description so we can track / refer to it.
|
|
- Does your PR follow the [semantic-release commit guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines)?
|
|
- If the PR is a `feat`, an [RFC](https://github.com/supabase/rfcs) or a detailed description of the design implementation is required. The former (RFC) is preferred before starting on the PR.
|
|
- Are the existing tests passing?
|
|
- Have you written some tests for your PR?
|
|
|
|
## Guidelines for Implementing Additional OAuth Providers
|
|
|
|
> ⚠️ We won't be accepting any additional oauth / sms provider contributions for now because we intend to support these through webhooks or a generic provider in the future.
|
|
|
|
Please ensure that an end-to-end test is done for the OAuth provider implemented.
|
|
|
|
An end-to-end test includes:
|
|
|
|
- Creating an application on the oauth provider site
|
|
- Generating your own client_id and secret
|
|
- Testing that `http://localhost:9999/authorize?provider=MY_COOL_NEW_PROVIDER` redirects you to the provider sign-in page
|
|
- The callback is handled properly
|
|
- Gotrue redirects to the `SITE_URL` or one of the URI's specified in the `URI_ALLOW_LIST` with the access_token, provider_token, expiry and refresh_token as query fragments
|
|
|
|
### Writing tests for the new OAuth provider implemented
|
|
|
|
Since implementing an additional OAuth provider consists of making api calls to an external api, we set up a mock server to attempt to mock the responses expected from the OAuth provider.
|
|
|
|
## License
|
|
|
|
By contributing to Auth, you agree that your contributions will be licensed
|
|
under its [MIT license](LICENSE).
|