configuration-schema.mdx

title	설정 스키마
description	전체 config.yaml 스키마 레퍼런스

이 문서는 현재 tinyauth의 config.yaml 구조를 top-level 그룹 기준으로 정리한 레퍼런스예요.

:::note frontend와 frontend.html_variables는 standalone 전용 설정이에요. @tinyrack/tinyauth-standalone만 이 값을 해석하고, @tinyrack/tinyauth-server의 직접 구성에서는 사용하지 않아요. :::

server

항목	유형	기본값	환경 변수	설명
public_origin	string (URL)	http://localhost:8080	PUBLIC_ORIGIN	공개 URL. 리다이렉트, 이메일 링크, OIDC issuer metadata의 기준이 돼요.
listen_port	number	8080	LISTEN_PORT	standalone 서버가 바인딩할 포트예요.
trust_proxy	boolean | string | string[] | number	false	TRUST_PROXY	리버스 프록시 헤더 신뢰 설정이에요.

tokens

항목	유형	기본값	환경 변수	설명
access_token_ttl	integer (최소 60)	3600	ACCESS_TOKEN_TTL	액세스 토큰 수명(초)
refresh_token_ttl	integer (최소 3600)	2592000	REFRESH_TOKEN_TTL	리프레시 토큰 수명(초)
key_rotation.enabled	boolean	true	JWT_KEY_ROTATION_ENABLED	JWT 키 자동 순환 활성화
key_rotation.interval_days	integer (최소 1)	30	JWT_KEY_ROTATION_DAYS	키 순환 주기(일)
key_rotation.overlap_days	integer (최소 1)	7	JWT_KEY_OVERLAP_DAYS	이전 키 유지 기간(일)

i18n

항목	유형	기본값	환경 변수	설명
supported_languages	Locale[]	['en', 'ko', 'ja']	-	지원 언어 목록
default_language	'auto' | Locale	'auto'	DEFAULT_LANGUAGE	기본 언어
fallback_language	Locale	'en'	FALLBACK_LANGUAGE	대체 언어

branding

항목	유형	기본값	환경 변수	설명
light_theme	AppTheme	'light'	LIGHT_THEME	라이트 모드 테마
dark_theme	AppTheme	'dark'	DARK_THEME	다크 모드 테마
theme_mode	'light' | 'dark' | 'system'	'system'	THEME_MODE	테마 선택 방식
background_url	string (URL)	기본 배경 이미지	BACKGROUND_URL	배경 이미지 URL
icon_url	string (URL)	-	ICON_URL	로고 이미지 URL
title	Record<string, string>	기본 다국어 제목	-	언어별 제목
subtitle	Record<string, string>	기본 다국어 부제목	-	언어별 부제목

registration

항목	유형	기본값	환경 변수	설명
enabled	boolean	false	REGISTRATION_ENABLED	자체 회원가입 활성화 여부. 비밀번호 가입과 최초 OAuth 가입 모두 이 값을 따라요.
allowed_email_patterns	string[]	[]	-	가입 허용 이메일 패턴. enabled: true일 때만 적용되며, 빈 배열이면 모든 이메일 가입을 허용해요.
email_verification_required	boolean	true	EMAIL_VERIFICATION_REQUIRED	비밀번호 회원가입 후 이메일 인증 필수 여부
signup_notice	Record<string, string>	{}	-	암시적 약관 동의 안내 문구(HTML 가능)

account_deletion

항목	유형	기본값	환경 변수	설명
enabled	boolean	false	ACCOUNT_DELETION_ENABLED	사용자 직접 탈퇴 허용 여부
retention	DurationString	'30d'	ACCOUNT_DELETION_RETENTION	탈퇴 요청 후 실제 영구 삭제까지의 유예 기간

logging

항목	유형	기본값	환경 변수	설명
level	'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent'	'info'	LOG_LEVEL	로그 레벨
format	'json' | 'pretty'	'json'	LOG_FORMAT	로그 출력 형식

security

항목	유형	기본값	환경 변수	설명
session_secret	string (16자 이상)	필수	SESSION_SECRET	세션 쿠키 서명 키
hash_secret	string (base64url 32바이트)	필수	HASH_SECRET	비밀번호, 클라이언트 시크릿, 일회성 토큰 해싱용 루트 시크릿
pbkdf2_iterations	integer (최소 1)	600000	PBKDF2_ITERATIONS	PBKDF2 반복 횟수

database

database.type에 따라 하위 필드가 달라져요.

SQLite (type: 'sqlite')

항목	유형	기본값	환경 변수	설명
type	'sqlite'	-	DATABASE_TYPE	데이터베이스 유형
path	string	/opt/tinyauth/database.db	DATABASE_PATH	데이터베이스 파일 경로
test	boolean	false	DATABASE_TEST	테스트 모드 여부

PostgreSQL (type: 'postgres')

항목	유형	기본값	환경 변수	설명
type	'postgres'	-	DATABASE_TYPE	데이터베이스 유형
host	string	'localhost'	DATABASE_HOST	호스트
port	number	5432	DATABASE_PORT	포트
user	string	'postgres'	DATABASE_USER	사용자
password	string	'postgres'	DATABASE_PASSWORD	비밀번호
name	string	'tinyauth'	DATABASE_NAME	데이터베이스 이름

auth

auth.password

항목	유형	기본값	환경 변수	설명
enabled	boolean	true	PASSWORD_AUTH_ENABLED	비밀번호 인증 활성화
two_factor.enrollment_required	boolean	false	PASSWORD_2FA_ENROLLMENT_REQUIRED	비밀번호 사용자의 2차 인증 등록 필수 여부
totp.enabled	boolean	false	PASSWORD_TOTP_ENABLED	TOTP 사용 여부
totp.issuer	string	'Tinyrack'	PASSWORD_TOTP_ISSUER	인증 앱 표시 이름
policy.min_length	number	8	PASSWORD_MIN_LENGTH	최소 길이
policy.max_length	number	128	PASSWORD_MAX_LENGTH	최대 길이

auth.passkey

항목	유형	기본값	환경 변수	설명
enabled	boolean	false	PASSKEY_ENABLED	패스키 인증 활성화
rp_id	string	server.public_origin에서 추출	PASSKEY_RP_ID	WebAuthn RP ID (도메인만)
origins	string[]	[server.public_origin]	-	허용 WebAuthn origin 목록

email

email은 선택 설정이며, 메일 전송 기능을 사용할 때만 필요해요.

항목	유형	기본값	환경 변수	설명
transport	'smtp' | 'test'	-	EMAIL_TRANSPORT	이메일 전송 방식
from	string	-	EMAIL_FROM	발신자 주소

SMTP (transport: 'smtp')

항목	유형	기본값	환경 변수	설명
host	string	'localhost'	EMAIL_HOST	SMTP 서버 호스트
port	number	465	EMAIL_PORT	SMTP 포트
secure	boolean	true	EMAIL_SECURE	SSL/TLS 사용 여부
user	string	필수	EMAIL_USER	SMTP 사용자
password	string	필수	EMAIL_PASSWORD	SMTP 비밀번호

identity_providers

배열 형태로 여러 제공자를 설정할 수 있어요. 사용하지 않을 때는 섹션을 생략하거나 []로 두면 돼요. 자세한 내용은 타사 로그인 개요를 참고해 주세요.

항목	유형	설명
id	string	고유 식별자
type	'github' | 'google' | 'apple' | 'generic_oauth'	제공자 유형
enabled	boolean	활성화 여부
display_name	string	표시 이름
icon_url	string	아이콘 URL
client_id	string	OAuth 클라이언트 ID
client_secret	string	OAuth 클라이언트 시크릿
authorization_url	string	인증 엔드포인트
token_url	string	토큰 엔드포인트
userinfo_url	string | null	사용자 정보 엔드포인트
email_url	string	이메일 조회 엔드포인트
scopes	string[]	요청 스코프 목록
email_conflict_strategy	'auto_link' | 'require_link'	이메일 충돌 처리 방식

clients

항목	유형	설명
id	string	내부 고유 식별자
name	string	표시 이름
logo_uri	string	로고 URL
client_id	string	공개 클라이언트 ID
client_secret	string	클라이언트 시크릿
redirect_uris	string[]	허용 리다이렉트 URL
response_types	string[]	허용 응답 유형
grant_types	string[]	허용 권한 부여 유형
scope	string	허용 스코프(공백 구분)

users

항목	유형	설명
sub	string	사용자 고유 식별자
email	string	이메일 주소
password	string	초기 비밀번호
role	'user' | 'admin'	사용자 역할

terms

배열 형태로 여러 약관을 설정할 수 있어요.

항목	유형	설명
id	string	고유 식별자 (소문자, -, _)
required	boolean	필수 동의 여부
consent_mode	'explicit' | 'implicit'	동의 수집 방식
version	string	약관 버전
content	Record<string, { title, type, content }>	언어별 약관 내용

content의 각 항목에서 type은 link 또는 text만 사용할 수 있어요.

scheduler

항목	유형	기본값	환경 변수	설명
enabled	boolean	true	SCHEDULER_ENABLED	내장 스케줄러 활성화
mode	'croner' | 'database'	'croner'	SCHEDULER_MODE	스케줄러 백엔드
cleanup_cron	string	'0 2 * * *'	SCHEDULER_CLEANUP_CRON	정리 작업 cron 표현식
poll_interval_ms	number	5000	SCHEDULER_POLL_INTERVAL_MS	database 모드 polling 주기(ms)
lock_ttl_ms	number	60000	SCHEDULER_LOCK_TTL_MS	database 모드 lease TTL(ms)
background_retry_delay_ms	number	1000	SCHEDULER_BACKGROUND_RETRY_DELAY_MS	database 모드 background job 재시도 대기 시간(ms)
background_max_attempts	integer	3	SCHEDULER_BACKGROUND_MAX_ATTEMPTS	database 모드 background job 최대 시도 횟수
background_retention_ms	number	604800000	SCHEDULER_BACKGROUND_RETENTION_MS	완료된 background job(succeeded/failed) 보존 기간(ms). pending/running job은 삭제하지 않음
instance_id	string	자동 생성	SCHEDULER_INSTANCE_ID	database 모드 lease 소유자 식별자

cleanup

항목	유형	기본값	환경 변수	설명
revoked_tokens.enabled	boolean	true	CLEANUP_REVOKED_TOKENS_ENABLED	취소된 토큰 정리
revoked_tokens.retention	DurationString	'0'	CLEANUP_REVOKED_TOKENS_RETENTION	보존 기간
oauth_codes.enabled	boolean	true	CLEANUP_OAUTH_CODES_ENABLED	인증 코드 정리
oauth_codes.consumed_retention	DurationString	'24h'	CLEANUP_OAUTH_CODES_RETENTION	사용된 코드 보존 기간
email_verifications.enabled	boolean	true	CLEANUP_EMAIL_VERIFICATIONS_ENABLED	이메일 인증 토큰 정리
email_verifications.retention	DurationString	'0'	CLEANUP_EMAIL_VERIFICATIONS_RETENTION	보존 기간
password_resets.enabled	boolean	true	CLEANUP_PASSWORD_RESETS_ENABLED	비밀번호 재설정 토큰 정리
password_resets.retention	DurationString	'0'	CLEANUP_PASSWORD_RESETS_RETENTION	보존 기간
pending_oauth_registrations.enabled	boolean	true	CLEANUP_PENDING_OAUTH_REGISTRATIONS_ENABLED	중단된 OAuth 가입 정리
pending_oauth_registrations.retention	DurationString	'0'	CLEANUP_PENDING_OAUTH_REGISTRATIONS_RETENTION	보존 기간

openapi

항목	유형	기본값	환경 변수	설명
enabled	boolean	true	-	라이브 OpenAPI 라우트 GET /api/docs, GET /api/docs/json 노출 여부
title	string	'TinyAuth API'	-	OpenAPI 문서 제목
description	string	'OpenID Connect Provider API'	-	OpenAPI 문서 설명
ui_title	string	'TinyAuth API Reference'	-	라이브 Scalar API 레퍼런스 UI의 브라우저 페이지 제목

frontend (standalone only)

항목	유형	기본값	환경 변수	설명
enabled	boolean	true	FRONTEND_ENABLED	프론트엔드 서빙 활성화 여부
mode	'proxy' | 'static'	'static'	FRONTEND_MODE	proxy는 업스트림 전달, static은 디스크 서빙
path	string	런타임 기본값	FRONTEND_PATH	프론트엔드 경로
html_variables	Record<string, string>	{}	-	HTML 템플릿 치환 변수

:::note DurationString 형식: "0" (즉시), "30s" (초), "30m" (분), "24h" (시간), "7d" (일), "1y" (년) :::