supabase/authAPI на основе JWT для управления пользователями и выдачи JWT-токенов
# Auth - Аутентификация и управление пользователями от Supabase
[](https://coveralls.io/github/supabase/auth?branch=master)
Auth — это сервер аутентификации и управления пользователями, написанный на Go, который обеспечивает работу таких функций
[Supabase](https://supabase.com), как:
- Выпуск JWT
- Безопасность на уровне строк (Row Level Security) с PostgREST
- Управление пользователями
- Вход по email, паролю, magic link, номеру телефона
- Вход через внешних провайдеров (Google, Apple, Facebook, Discord, ...)
Изначально он основан на отличном
[коде GoTrue от Netlify](https://github.com/netlify/gotrue), однако с тех пор обе реализации значительно разошлись в возможностях и функциональности.
Если вы хотите внести вклад в проект, пожалуйста, обратитесь к [руководству по внесению вклада](https://github.com/supabase/auth/blob/master/CONTRIBUTING.md).
## Содержание
- [Быстрый старт](#quick-start)
- [Запуск в продакшене](#running-in-production)
- [Конфигурация](#configuration)
- [Эндпоинты](#endpoints)
## Быстрый старт
Создайте файл `.env` для хранения собственных переменных окружения. См. [`example.env`](https://github.com/supabase/auth/blob/master/example.env)
1. Запустите локальную базу данных Postgres в контейнере Postgres: `docker-compose -f docker-compose-dev.yml up postgres`
2. Соберите бинарный файл auth: `make build` . Вы должны увидеть вывод, похожий на этот:```bash
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
```
3. Выполните бинарный файл auth: `./auth`
### Если у вас установлен Docker
Создайте файл `.env.docker` для хранения собственных переменных окружения. См. [`example.docker.env`](https://github.com/supabase/auth/blob/master/example.docker.env)
1. `make build`
2. `make dev`
3. `docker ps` должен показать два Docker-контейнера (`auth-auth-1` и `auth-postgres-1`)
4. Вот и всё! Перейдите к [конечной точке проверки состояния](http://localhost:9999/health), чтобы убедиться, что auth запущен.
## Запуск в производственной среде
Запуск сервера аутентификации в производственной среде — непростая задача. Мы
рекомендуем использовать [Supabase Auth](https://supabase.com/auth), который регулярно
получает обновления безопасности.
В противном случае убедитесь, что вы настроили процесс своевременного обновления до
последней версии. Это можно сделать, следя за этим репозиторием, в частности за
разделами [Releases](https://github.com/supabase/auth/releases) и [Security
Advisories](https://github.com/supabase/auth/security/advisories).
### Обратная совместимость
Auth использует схему [Semantic Versioning](https://semver.org). Ниже приведены
дополнительные разъяснения гарантий обратной совместимости:
**Совместимость Go API**
Auth не предназначен для использования в качестве библиотеки Go. Нет никаких гарантий
обратной совместимости API при таком использовании, независимо от того, какой номер
версии изменяется.
**Патч**
Изменения патч-версии гарантируют обратную совместимость с:
- объектами базы данных (таблицы, столбцы, индексы, функции).
- REST API
- структурой JWT
- конфигурацией
Гарантированные примеры:
- Столбец не изменит свой тип.
- Таблица не изменит свой первичный ключ.
- Индекс не будет удалён.
- Ограничение уникальности не будет удалено.
- REST API не будет удалён.
- Параметры REST API будут работать так же, как и раньше (или лучше, если ошибка
была исправлена).
- Конфигурация не изменится.
Негарантированные примеры:
- Таблица может добавить новые столбцы.
- Столбцы в таблице могут быть переупорядочены.
- Неуникальные ограничения могут быть удалены (проверки на уровне базы данных, null, значения
по умолчанию).
- JWT может добавлять новые свойства.
**Минорная версия**
Изменения минорной версии гарантируют обратную совместимость с:
- REST API
- структурой JWT
- конфигурацией
Исключения из этих гарантий допускаются только в тех случаях, когда обнаружены
серьёзные проблемы безопасности, которые невозможно устранить иным способом.
Гарантированные примеры:
- Существующие API могут быть объявлены устаревшими, но продолжат работать в течение следующих нескольких минорных
выпусков версий.
- Изменения конфигурации могут быть объявлены устаревшими, но продолжат работать в течение следующих
нескольких минорных выпусков версий.
- Уже выпущенные JWT будут приниматься, но новые JWT могут иметь другую
структуру (но обычно аналогичную).
Негарантированные примеры:
- Удаление полей JWT после уведомления об устаревании.
- Удаление некоторых API после уведомления об устаревании.
- Удаление входа через внешних провайдеров после уведомления об устаревании.
- Удаление, усечение, существенные изменения схемы таблиц, индексов, представлений,
функций.
Мы стремимся предоставлять уведомление об устаревании в журналах выполнения как минимум
для двух мажорных выпусков версий или в течение двух недель, если выходит несколько
релизов. Совместимость будет гарантироваться, пока уведомление активно.
**Мажорная версия**
Изменения мажорной версии не гарантируют обратной совместимости с
предыдущими версиями.
### Унаследованные функции
Некоторые унаследованные функции из кодовой базы Netlify не поддерживаются
Supabase и могут быть удалены без предварительного уведомления в будущем. Вот
полный список этих функций:
1. Мультиарендность через таблицу `instances`, т.е. `GOTRUE_MULTI_INSTANCE_MODE`
параметр конфигурации.
2. Системный пользователь (пользователь с нулевым UUID).
3. Супер-администратор через столбец `is_super_admin`.
4. Информация о группах в JWT через `GOTRUE_JWT_ADMIN_GROUP_NAME` и другие
поля конфигурации.
5. Подпись JWT. Supabase Auth поддерживает асимметричные ключи (RS256 по умолчанию;
ECC/Ed25519 опционально). HS256 по-прежнему поддерживается для совместимости, но
рекомендуется перейти на асимметричные ключи для упрощения проверки и
ротации. Будущие удаления будут объявлены в журнале изменений. См.
[JWT Signing Keys](https://supabase.com/docs/guides/auth/signing-keys) и
[JWTs guide](https://supabase.com/docs/guides/auth/jwts) для подробностей.
Обратите внимание, что это не исчерпывающий список, и он может измениться.
### Рекомендации при самостоятельном размещении
Вот несколько рекомендаций, которым следует следовать при самостоятельном размещении,
чтобы обеспечить обратную совместимость с Auth:
1. Не изменяйте схему, управляемую Auth. Вы можете просмотреть все
миграции в каталоге `migrations`.
2. Не полагайтесь на схему и структуру данных в базе данных. Всегда используйте
API Auth и JWT для получения информации о пользователях.
3. Всегда запускайте Auth за прокси с поддержкой TLS, например балансировщиком нагрузки, CDN,
nginx или другим подобным программным обеспечением.
## Конфигурация
Вы можете настроить Auth, используя файл конфигурации `.env`,
переменные окружения или их комбинацию. Переменные окружения имеют префикс `GOTRUE_` и всегда имеют приоритет над значениями, указанными в файле.
### Верхний уровень```properties
GOTRUE_SITE_URL=https://example.netlify.com/
```
`SITE_URL` - `string` **обязательно**
Базовый URL, по которому расположен ваш сайт. В настоящее время используется в сочетании с другими настройками для формирования URL-адресов, используемых в электронных письмах. Любой URI, у которого общий хост с `SITE_URL`, является допустимым значением для параметров `redirect_to` (см. `/authorize` и т.д.).
`URI_ALLOW_LIST` - `string`
Список URI, разделённых запятыми (например, `"https://foo.example.com,https://*.foo.example.com,https://bar.example.com"`), которые разрешены в качестве допустимых направлений `redirect_to`. По умолчанию — []. Поддерживает сопоставление с подстановочными знаками с помощью glob-шаблонов. Например, `https://*.foo.example.com` разрешит принимать `https://a.foo.example.com` и `https://b.foo.example.com`. Glob-шаблоны также поддерживаются для поддоменов. Например, `https://foo.example.com/*` разрешит принимать `https://foo.example.com/page1` и `https://foo.example.com/page2`.
Дополнительные распространённые glob-шаблоны см. по [следующей ссылке](https://pkg.go.dev/github.com/gobwas/glob#Compile).
`OPERATOR_TOKEN` - `string` _только для мультиинстансного режима_
Общий секрет с оператором (обычно Netlify) для этого микросервиса. Используется для проверки того, что запросы были проксированы через оператора и значениям полезной нагрузки можно доверять.
`DISABLE_SIGNUP` - `bool`
Когда регистрация отключена, единственный способ создать новых пользователей — через приглашения. По умолчанию — `false`, все регистрации включены.
`GOTRUE_EXTERNAL_EMAIL_ENABLED` - `bool`
Используйте это для отключения регистрации по электронной почте (пользователи по-прежнему могут использовать внешних OAuth-провайдеров для регистрации / входа)
`GOTRUE_EXTERNAL_PHONE_ENABLED` - `bool`
Используйте это для отключения регистрации по телефону (пользователи по-прежнему могут использовать внешних OAuth-провайдеров для регистрации / входа)
`GOTRUE_RATE_LIMIT_HEADER` - `string`
Заголовок, на основе которого ограничивается частота запросов к конечной точке `/token`. Ожидается, что этот заголовок будет устанавливаться доверенным вышестоящим прокси (например, Kong или Envoy). Такие заголовки, как `x-forwarded-for`, могут быть подделаны, и им нельзя доверять при ограничении частоты запросов, если они передаются напрямую клиентом.
`GOTRUE_RATE_LIMIT_EMAIL_SENT` - `string`
Ограничивает количество писем, отправляемых в час, на следующих конечных точках: `/signup`, `/invite`, `/magiclink`, `/recover`, `/otp` и `/user`.
`GOTRUE_PASSWORD_MIN_LENGTH` - `int`
Минимальная длина пароля, по умолчанию 6.
`GOTRUE_PASSWORD_REQUIRED_CHARACTERS` - строка наборов символов, разделённых `:`. Пароль должен содержать хотя бы один символ из каждого набора, чтобы быть принятым. Чтобы использовать символ `:`, экранируйте его с помощью `\`.
`GOTRUE_SECURITY_REFRESH_TOKEN_ROTATION_ENABLED` - `bool`
Если включена ротация refresh-токенов, auth автоматически обнаружит вредоносные попытки повторного использования отозванного refresh-токена. При обнаружении вредоносной попытки GoTrue немедленно отзывает все токены, произошедшие от проблемного токена.
`GOTRUE_SECURITY_REFRESH_TOKEN_REUSE_INTERVAL` - `string`
Эта настройка применима только в том случае, если включён параметр `GOTRUE_SECURITY_REFRESH_TOKEN_ROTATION_ENABLED`. Интервал повторного использования refresh-токена позволяет обменивать refresh-токен несколько раз в течение этого интервала для поддержки конкурентности или проблем с офлайн-доступом. В течение интервала повторного использования auth не будет рассматривать использование отозванного токена как вредоносную попытку и просто вернёт дочерний refresh-токен.
Повторно использовать можно только предыдущий отозванный токен. Использование старого refresh-токена задолго до текущего действительного refresh-токена вызовет обнаружение повторного использования.
### API```properties
GOTRUE_API_HOST=localhost
PORT=9999
API_EXTERNAL_URL=http://localhost:9999
```
`API_HOST` - `string`
Имя хоста для прослушивания.
`PORT` (no prefix) / `API_PORT` - `number`
Номер порта для прослушивания. По умолчанию — `8081`.
`API_ENDPOINT` - `string` _Только для многокомпонентного режима_
Управляет конечной точкой, через которую Netlify может обращаться к этому API.
`API_EXTERNAL_URL` - `string` **обязательно**
URL, по которому может быть доступен GoTrue.
`REQUEST_ID_HEADER` - `string`
Если вы хотите унаследовать идентификатор запроса из входящего запроса, укажите его имя в этом значении.
### База данных```properties
GOTRUE_DB_DRIVER=postgres
DATABASE_URL=root@localhost/auth
```
`DB_DRIVER` - `string` **обязательно**
Выбирает диалект базы данных. Должно быть `postgres`.
`DATABASE_URL` (без префикса) / `DB_DATABASE_URL` - `string` **обязательно**
Строка подключения к базе данных.
`GOTRUE_DB_MAX_POOL_SIZE` - `int`
Задаёт максимальное количество открытых соединений с базой данных. По умолчанию 0, что эквивалентно «неограниченному» числу соединений.
`DB_NAMESPACE` - `string`
Добавляет префикс ко всем именам таблиц.
**Примечание о миграциях**
Миграции применяются автоматически при запуске `./auth`. Однако у вас также есть возможность перезапустить миграции следующими способами:
- Если собрано локально: `./auth migrate`
- С использованием Docker: `docker run --rm auth gotrue migrate`
### Логирование```properties
LOG_LEVEL=debug # available without GOTRUE prefix (exception)
GOTRUE_LOG_FILE=/var/log/go/auth.log
```
`LOG_LEVEL` — `string`
Управляет тем, какие уровни логирования выводятся. Выберите `panic`, `fatal`, `error`, `warn`, `info` или `debug`. По умолчанию — `info`.
`LOG_FILE` — `string`
Если вы хотите записывать логи в файл, укажите в `log_file` допустимый путь к файлу.
### Наблюдаемость
В Auth встроена базовая наблюдаемость. Он может экспортировать
метрики и трейсы [OpenTelemetry](https://opentelemetry.io) в коллектор.
#### Трейсинг
Чтобы включить трейсинг, настройте эти переменные:
`GOTRUE_TRACING_ENABLED` — `bool`
`GOTRUE_TRACING_EXPORTER` — `string`, поддерживается только `opentelemetry`
Убедитесь, что вы также настроили конфигурацию [OpenTelemetry
Exporter](https://opentelemetry.io/docs/reference/specification/protocol/exporter/)
для вашего коллектора или сервиса.
Например, если вы используете
[Honeycomb.io](https://docs.honeycomb.io/getting-data-in/opentelemetry/go-distro/#using-opentelemetry-without-the-honeycomb-distribution),
вам следует задать эти стандартные переменные OTLP OpenTelemetry:```
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"
```
#### Метрики
Чтобы включить метрики, настройте эти переменные:
`GOTRUE_METRICS_ENABLED` - `boolean`
`GOTRUE_METRICS_EXPORTER` - `string`, поддерживаются только `opentelemetry` и `prometheus`
Убедитесь, что вы также настроили конфигурацию [OpenTelemetry
Exporter](https://opentelemetry.io/docs/reference/specification/protocol/exporter/)
для вашего коллектора или сервиса.
Если вы используете экспортер `prometheus`, хост и порт сервера можно
настроить с помощью этих стандартных переменных OpenTelemetry:
`OTEL_EXPORTER_PROMETHEUS_HOST` - IP-адрес, по умолчанию `0.0.0.0`
`OTEL_EXPORTER_PROMETHEUS_PORT` - номер порта, по умолчанию `9100`
Метрики экспортируются по пути `/` на сервере.
Если вы используете экспортер `opentelemetry`, метрики отправляются в
коллектор.
Например, если вы используете
[Honeycomb.io](https://docs.honeycomb.io/getting-data-in/opentelemetry/go-distro/#using-opentelemetry-without-the-honeycomb-distribution),
вам следует задать эти стандартные переменные OTLP OpenTelemetry:```
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"
```
Обратите внимание, что Honeycomb.io требует платного тарифа для приёма метрик.
Если вам нужно отладить проблему с трейсами или метриками, которые не отправляются, вы можете установить `DEBUG=true`, чтобы получить больше информации от OpenTelemetry SDK.
#### Пользовательские атрибуты ресурсов
При использовании экспортёра трейсов или метрик OpenTelemetry вы можете задать пользовательские атрибуты ресурсов с помощью [стандартной переменной окружения `OTEL_RESOURCE_ATTRIBUTES`](https://opentelemetry.io/docs/reference/specification/resource/sdk/#specifying-resource-information-via-an-environment-variable).
Предоставляется атрибут по умолчанию `auth.version`, содержащий версию сборки.
#### Трассировка HTTP-маршрутов
Все HTTP-вызовы к Auth API трассируются. Маршруты используют параметризованную версию маршрута, а значения параметров маршрута можно найти в атрибуте спана `http.route.params.<route-key>`.
Например, следующий запрос:```
GET /admin/users/4acde936-82dc-4552-b851-831fb8ce0927/
```
будет отслеживаться как:```
http.method = GET
http.route = /admin/users/{user_id}
http.route.params.user_id = 4acde936-82dc-4552-b851-831fb8ce0927
```
#### Метрики Go runtime и HTTP
Все метрики Go runtime предоставляются. Некоторые HTTP-метрики также собираются по умолчанию.
### JSON Web Tokens (JWT)```properties
GOTRUE_JWT_SECRET=supersecretvalue
GOTRUE_JWT_EXP=3600
GOTRUE_JWT_AUD=netlify
```
`JWT_SECRET` - `string` **обязательно**
Секрет, используемый для подписи JWT-токенов.
`JWT_EXP` - `number`
Сколько времени токены действительны, в секундах. По умолчанию: 3600 (1 час).
`JWT_AUD` - `string`
Аудитория JWT по умолчанию. Используйте аудитории для группировки пользователей.
`JWT_ADMIN_GROUP_NAME` - `string`
Название группы администраторов (если включено). По умолчанию: `admin`.
`JWT_DEFAULT_GROUP_NAME` - `string`
Группа по умолчанию, в которую назначаются все новые пользователи.
### Внешние провайдеры аутентификации
Мы поддерживаем внешнюю аутентификацию через `apple`, `azure`, `bitbucket`, `discord`, `facebook`, `figma`, `github`, `gitlab`, `google`, `keycloak`, `linkedin`, `notion`, `snapchat`, `spotify`, `slack`, `twitch`, `twitter` и `workos`.
Используйте эти названия в качестве ключей внутри `external`, чтобы настроить каждого провайдера отдельно.```properties
GOTRUE_EXTERNAL_GITHUB_ENABLED=true
GOTRUE_EXTERNAL_GITHUB_CLIENT_ID=myappclientid
GOTRUE_EXTERNAL_GITHUB_SECRET=clientsecretvaluessssh
GOTRUE_EXTERNAL_GITHUB_REDIRECT_URI=http://localhost:3000/callback
```
No external providers are required, but you must provide the required values if you choose to enable any.
`EXTERNAL_X_ENABLED` - `bool`
Whether this external provider is enabled or not
`EXTERNAL_X_CLIENT_ID` - `string` **required**
The OAuth2 Client ID registered with the external provider.
`EXTERNAL_X_SECRET` - `string` **required**
The OAuth2 Client Secret provided by the external provider when you registered.
`EXTERNAL_X_REDIRECT_URI` - `string` **required**
The URI a OAuth2 provider will redirect to with the `code` and `state` values.
`EXTERNAL_X_URL` - `string`
The base URL used for constructing the URLs to request authorization and access tokens. Used by `gitlab` and `keycloak`. For `gitlab` it defaults to `https://gitlab.com`. For `keycloak` you need to set this to your instance, for example: `https://keycloak.example.com/realms/myrealm`
#### Network hardening
Configuring an external authentication provider causes Auth to make outbound HTTP requests to that provider's authorization, token, and userinfo endpoints. Configuring a provider either via `GOTRUE_EXTERNAL_*` settings or an admin API is an administrative action, and doing so implies trust in the hosts and URLs that will be contacted.
The network Auth runs in should be hardened so these outbound connections cannot reach internal-only resources you don't want exposed, such as `localhost`/loopback addresses or cloud metadata endpoints (e.g. `169.254.169.254`). This matters most for providers with admin-configurable or discoverable endpoints (e.g. custom OAuth/OIDC providers), where a misconfigured or malicious URL could otherwise be used to reach internal infrastructure.
#### Apple OAuth
To try out external authentication with Apple locally, you will need to do the following:
1. Remap localhost to \<my_custom_dns \> in your `/etc/hosts` config.
2. Configure auth to serve HTTPS traffic over localhost by replacing `ListenAndServe` in [api.go](https://github.com/supabase/auth/blob/master/internal/api/api.go) with: ```
func (a *API) ListenAndServe(hostAndPort string) {
log := logrus.WithField("component", "api")
path, err := os.Getwd()
if err != nil {
log.Println(err)
}
server := &http.Server{
Addr: hostAndPort,
Handler: a.handler,
}
done := make(chan struct{})
defer close(done)
go func() {
waitForTermination(log, done)
ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
defer cancel()
server.Shutdown(ctx)
}()
if err := server.ListenAndServeTLS("PATH_TO_CRT_FILE", "PATH_TO_KEY_FILE"); err != http.ErrServerClosed {
log.WithError(err).Fatal("http server listen failed")
}
}
```
3. Сгенерируйте файлы crt и key. См. [здесь](https://www.freecodecamp.org/news/how-to-get-https-working-on-your-local-development-environment-in-5-minutes-7af615770eec/) для получения дополнительной информации.
4. Сгенерируйте `GOTRUE_EXTERNAL_APPLE_SECRET`, следуя этому [руководству](https://medium.com/identity-beyond-borders/how-to-configure-sign-in-with-apple-77c61e336003)!
### Электронная почта
Отправка электронных писем не обязательна, но настоятельно рекомендуется для восстановления пароля.
Если эта функция включена, необходимо указать требуемые значения ниже.```properties
GOTRUE_SMTP_HOST=smtp.mandrillapp.com
GOTRUE_SMTP_PORT=587
[email protected]
GOTRUE_SMTP_PASS=correcthorsebatterystaple
[email protected]
GOTRUE_MAILER_SUBJECTS_CONFIRMATION="Please confirm"
```
`SMTP_ADMIN_EMAIL` - `string` **required**
Адрес электронной почты `From` для всех отправляемых писем.
`SMTP_HOST` - `string` **required**
Имя хоста почтового сервера, через который отправляются письма.
`SMTP_PORT` - `number` **required**
Номер порта для подключения к почтовому серверу.
`SMTP_USER` - `string`
Если почтовый сервер требует аутентификации — имя пользователя.
`SMTP_PASS` - `string`
Если почтовый сервер требует аутентификации — пароль.
`SMTP_MAX_FREQUENCY` - `number`
Управляет минимальным промежутком времени, который должен пройти перед отправкой очередного письма с подтверждением регистрации или сбросом пароля. Значение указывается в секундах. По умолчанию — 900 (15 минут).
`SMTP_SENDER_NAME` - `string`
Задаёт имя отправителя. По умолчанию используется `SMTP_ADMIN_EMAIL`, если имя не указано.
`MAILER_AUTOCONFIRM` - `bool`
Если подтверждение email не требуется, можно установить значение `true`. По умолчанию — `false`.
`MAILER_OTP_EXP` - `number`
Управляет сроком действия ссылки в письме или одноразового пароля (OTP).
`MAILER_URLPATHS_INVITE` - `string`
Путь URL, используемый в письме с приглашением пользователя. По умолчанию — `/verify`.
`MAILER_URLPATHS_CONFIRMATION` - `string`
```
---
[Read more](https://github.com/supabase/auth)