hailin
/
chatdesk-ui
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
chatdesk-ui/auth_v2.169.0/CONTRIBUTING.md

16 KiB
Raw Blame History

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 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 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 section below. Otherwise, you can skip ahead to the How To Verify that GoTrue 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.

make dev

Running tests in the containers

Start the containers with a fresh database and run the project's tests.

make docker-test

Removing the containers

Remove both containers and their volumes. This removes any data associated with the containers.

make docker-clean

Rebuild the containers

Fully rebuild the containers without using any cached layers.

make docker-build

Setup and Tooling

Auth -- as the name implies -- is a user registration and authentication API developed in Go.

It connects to a PostgreSQL database in order to store authentication data, Soda CLI to manage database schema and migrations, and runs inside a Docker container.

Therefore, to contribute to Auth you will need to install these tools.

Install Tools

  • Install Go 1.22
# 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

# Via Homebrew on macOS
brew install docker

Or, if you prefer, download Docker Desktop.

# Via Homebrew on macOS
brew install gobuffalo/tap/pop

If you are on macOS Catalina you may run into issues installing Soda with Brew. Do check your GOPATH and run

go build -o /bin/soda github.com/gobuffalo/pop/soda to resolve.

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:
# 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 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.

  1. 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:

# 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:

make build
  1. To setup the database schema via Soda, run:
make migrate_test

You should see log messages that indicate that the Auth migrations were applied successfully:

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.

  1. Create a .env file in the root of the project and copy the following config in example.env. Set the values to GOTRUE_SMS_TEST_OTP_VALID_UNTIL in the .env file.

  2. 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.

  1. Then finally Start Auth
  2. Verify that Auth is Available

Starting Auth

Start Auth by running the executable:

./auth

This command will re-run migrations and then indicate that Auth has started:

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:

{
  "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:

{
  "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 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:

{
  "role": "supabase_admin"
}

You can sign this payload using the JWT.io Debugger 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:

{
  "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:

{
  "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:

{
  "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:

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:

# 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

# 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?
  • If the PR is a feat, an RFC 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.