アップデート一覧に戻る
New releaseSep 10, 2026

auth v2.197.0

ユーザー管理とJWTトークン発行のためのJWTベースのAPI

共有

Auth - Supabaseによる認証とユーザー管理

Coverage Status

Authは、Goで書かれたユーザー管理・認証サーバーであり、Supabase の以下のような機能を支えています:

  • JWTの発行
  • PostgRESTによる行レベルセキュリティ
  • ユーザー管理
  • メール、パスワード、マジックリンク、電話番号でのサインイン
  • 外部プロバイダーでのサインイン (Google、Apple、Facebook、Discord、...)

これは元々、優れた NetlifyによるGoTrueコードベース に基づいていますが、両者は機能と能力において大幅に分岐しています。

プロジェクトに貢献したい場合は、貢献ガイド を参照してください。

目次

クイックスタート

独自のカスタム環境変数を保存するための .env ファイルを作成します。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` を実行すると、2つのDockerコンテナ（`auth-auth-1` と `auth-postgres-1`）が表示されるはずです
4. これで完了です！[ヘルスチェックエンドポイント](http://localhost:9999/health) にアクセスして、authが実行中であることを確認してください。

## 本番環境での実行

認証サーバーを本番環境で実行するのは簡単なことではありません。定期的に
セキュリティアップデートが行われる [Supabase Auth](https://supabase.com/auth) の利用を
お勧めします。

それ以外の場合は、最新バージョンへ速やかに更新する仕組みを必ず
整えてください。これには、このリポジトリ、具体的には
[リリース](https://github.com/supabase/auth/releases) と [セキュリティ
アドバイザリ](https://github.com/supabase/auth/security/advisories) セクションをフォローしてください。

### 後方互換性

Authは [セマンティックバージョニング](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の削除。
- 非推奨通知後の外部プロバイダーによるサインインの削除。
- テーブル、インデックス、ビュー、関数に対する削除、切り詰め、大幅なスキーマ変更。

私たちは、実行ログに少なくとも2つのメジャーバージョンリリース、または複数のリリースが
公開される場合は2週間、非推奨通知を提供することを目指しています。通知が有効な間は
互換性が保証されます。

**メジャー**

メジャーバージョンの変更は、以前のバージョンとの後方互換性を一切保証しません。

### 継承された機能

Netlifyコードベースから継承された特定の機能はSupabaseではサポートされておらず、
将来予告なしに削除される可能性があります。以下はそれらの機能の包括的なリストです：

1. `instances` テーブルを介したマルチテナンシー、つまり `GOTRUE_MULTI_INSTANCE_MODE`
   設定パラメータ。
2. システムユーザー（ゼロUUIDユーザー）。
3. `is_super_admin` カラムによるスーパー管理者。
4. `GOTRUE_JWT_ADMIN_GROUP_NAME` およびその他の設定フィールドを介したJWT内の
   グループ情報。
5. JWT署名。Supabase Authは非対称キー（デフォルトではRS256、
   ECC/Ed25519もオプション）をサポートしています。HS256も互換性のために引き続きサポートされていますが、
   検証とローテーションを容易にするため、非対称キーへの移行が推奨されます。将来の非推奨はチェンジログで発表されます。詳細は
   [JWT署名キー](https://supabase.com/docs/guides/auth/signing-keys) と
   [JWTガイド](https://supabase.com/docs/guides/auth/jwts) を参照してください。

これは網羅的なリストではなく、変更される可能性があることに注意してください。

### セルフホスティング時のベストプラクティス

Authとの後方互換性を確保するためにセルフホスティング時に従うべき、いくつかのベストプラクティスを以下に示します：

1. Authによって管理されているスキーマを変更しないでください。マイグレーションはすべて
   `migrations` ディレクトリで確認できます。
2. データベースのスキーマやデータ構造に依存しないでください。ユーザー情報を推測するには、常に
   Auth APIとJWTを使用してください。
3. 常にAuthをロードバランサー、CDN、
   nginx、その他の類似ソフトウェアなどのTLS対応プロキシの背後で実行してください。

## 設定

Authは、`.env` という名前の設定ファイル、
環境変数、またはその両方の組み合わせを使用して設定できます。環境変数には `GOTRUE_` プレフィックスが付き、ファイルで提供された値よりも常に優先されます。

### トップレベル```properties
GOTRUE_SITE_URL=https://example.netlify.com/

SITE_URL - string 必須

あなたのサイトが置かれているベースURLです。現在は他の設定と組み合わせて、メールで使用されるURLを構築するために使われます。SITE_URL とホストを共有する任意のURIは、redirect_to パラメータの許可値となります（/authorize などを参照）。

URI_ALLOW_LIST - string

有効な redirect_to 宛先として許可されるURIのカンマ区切りリストです（例: "https://foo.example.com,https://*.foo.example.com,https://bar.example.com"）。デフォルトは [] です。グロビングによるワイルドカードマッチングをサポートします。例: https://*.foo.example.com は https://a.foo.example.com と https://b.foo.example.com を許可します。グロビングはサブドメインでもサポートされます。例: https://foo.example.com/* は https://foo.example.com/page1 と https://foo.example.com/page2 を許可します。

より一般的なグロブパターンについては、次のリンク を確認してください。

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

次のエンドポイントで1時間あたりに送信されるメール数をレート制限します: /signup、/invite、/magiclink、/recover、/otp、& /user。

GOTRUE_PASSWORD_MIN_LENGTH - int

パスワードの最小長です。デフォルトは6です。

GOTRUE_PASSWORD_REQUIRED_CHARACTERS - : で区切られた文字セットの文字列です。パスワードは、受け入れられるために各セットの文字を少なくとも1つ含む必要があります。: 文字を使用するには、\ でエスケープします。

GOTRUE_SECURITY_REFRESH_TOKEN_ROTATION_ENABLED - bool

リフレッシュトークンのローテーションが有効な場合、認証は失効したリフレッシュトークンを再利用しようとする悪意のある試みを自動的に検出します。悪意のある試みが検出されると、GoTrueは問題のトークンから派生したすべてのトークンを直ちに失効させます。

GOTRUE_SECURITY_REFRESH_TOKEN_REUSE_INTERVAL - string

この設定は、GOTRUE_SECURITY_REFRESH_TOKEN_ROTATION_ENABLED が有効な場合にのみ適用されます。リフレッシュトークンの再利用間隔により、その間隔中にリフレッシュトークンを複数回交換して、並行性やオフラインの問題に対応できます。再利用間隔中、認証は失効したトークンの使用を悪意のある試みとは見なさず、単に子リフレッシュトークンを返します。

再利用できるのは、直前に失効したトークンだけです。現在の有効なリフレッシュトークンよりかなり前に発行された古いリフレッシュトークンを使用すると、再利用検出がトリガーされます。

API```properties

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

`API_HOST` - `string`

リッスンするホスト名。

`PORT` (プレフィックスなし) / `API_PORT` - `number`

リッスンするポート番号。デフォルトは`8081`。

`API_ENDPOINT` - `string` _マルチインスタンスモードのみ_

NetlifyがこのAPIにアクセスできるエンドポイントを制御します。

`API_EXTERNAL_URL` - `string` **必須**

GoTrueがアクセスされる可能性のあるURL。

`REQUEST_ID_HEADER` - `string`

受信リクエストからリクエストIDを継承したい場合は、この値に名前を指定してください。

### データベース```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) のメトリクスとトレースをコレクタにエクスポートできます。

#### トレーシング

トレーシングを有効にするには、以下の変数を設定してください。
もっと読む

カテゴリ

認証と認可ID管理アイデンティティ＆アクセス管理 (IAM)認証