업데이트로 돌아가기
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` 명령어는 두 개의 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는 [시맨틱 버저닝](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주 동안 제공하는 것을 목표로 합니다. 공지가
유효한 동안에는 호환성이 보장됩니다.

**메이저**

메이저 버전 변경은 이전 버전과의 호환성을
보장하지 않습니다.

### 상속된 기능

Netlify 코드베이스에서 상속된 일부 기능은 Supabase에서 지원되지 않으며
향후 사전 공지 없이 제거될 수 있습니다. 다음은
해당 기능의 전체 목록입니다:

1. `instances` 테이블을 통한 멀티 테넌시, 즉 `GOTRUE_MULTI_INSTANCE_MODE`
   구성 매개변수.
2. 시스템 사용자 (zero 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)와
   [JWTs 가이드](https://supabase.com/docs/guides/auth/jwts)를 참조하세요.

이 목록은 완전한 목록이 아니며 변경될 수 있습니다.

### 자체 호스팅 시 모범 사례

자체 호스팅 시 Auth와의 이전 버전 호환성을 보장하기 위해 따라야 할 몇 가지 모범
사례는 다음과 같습니다:

1. Auth가 관리하는 스키마를 수정하지 마세요. `migrations` 디렉토리에서 모든
   마이그레이션을 확인할 수 있습니다.
2. 데이터베이스의 스키마와 데이터 구조에 의존하지 마세요. 사용자 정보를 파악하려면
   항상 Auth API와 JWT를 사용하세요.
3. 항상 로드 밸런서, CDN, nginx 또는 이와 유사한 소프트웨어와 같은 TLS 지원
   프록시 뒤에서 Auth를 실행하세요.

## 구성

`.env`라는 구성 파일,
환경 변수, 또는 둘의 조합을 사용하여 Auth를 구성할 수 있습니다. 환경 변수는 `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"). 기본값은 []입니다. 글롭(glob)을 통한 와일드카드 매칭을 지원합니다. 예를 들어 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

다음 엔드포인트에서 시간당 전송되는 이메일 수를 제한합니다: /signup, /invite, /magiclink, /recover, /otp, /user.

GOTRUE_PASSWORD_MIN_LENGTH — int

최소 비밀번호 길이, 기본값은 6입니다.

GOTRUE_PASSWORD_REQUIRED_CHARACTERS — :로 구분된 문자 집합 문자열입니다. 비밀번호는 각 집합의 문자를 하나 이상 포함해야 승인됩니다. : 문자를 사용하려면 \로 이스케이프하세요.

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`을 유효한 파일 경로로 설정하세요.

### Observability
더 읽기

카테고리

Authentication & AuthorizationIdentity ManagementIdentity & Access Management (IAM)Authentication