로그인과 가입

이메일 인증 코드, Google 로그인, 신규 사용자 가입 범위를 설정합니다.

Multica는 기본적으로 이메일 인증 코드로 로그인하며 Google OAuth를 추가할 수도 있습니다. 기존 사용자는 언제든 다시 로그인할 수 있습니다. 가입 제한은 새 계정을 만들 수 있는지만 결정합니다.

이메일 인증 코드

사용자가 이메일을 입력하면 Multica가 6자리 인증 코드를 보냅니다. 코드는 10분 동안 유효하며 인증에 성공하면 브라우저에 로그인 cookie가 발급됩니다.

이메일은 Resend 또는 SMTP로 보낼 수 있습니다. 둘 다 설정하면 SMTP_HOST가 우선합니다.

Resend 사용

Resend에서 발신 도메인을 인증하고 API key를 만듭니다.

다음을 설정합니다.

RESEND_API_KEY=re_xxxxxxxxxxxxxxxx
RESEND_FROM_EMAIL=noreply@example.com

API 서비스를 다시 시작합니다.

RESEND_FROM_EMAIL은 Resend에서 인증한 도메인에 속해야 합니다.

SMTP 사용

최소한 host와 발신 주소를 설정해야 합니다.

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=multica
SMTP_PASSWORD=<password>
SMTP_FROM_EMAIL=noreply@example.com

일반적인 연결 방식은 다음과 같습니다.

환경	설정
내부 네트워크 익명 relay	`SMTP_PORT=25`, 사용자 이름과 비밀번호는 비워 둠
STARTTLS	`SMTP_PORT=587`, 서버가 지원하면 기본적으로 TLS로 업그레이드
암시적 TLS	`SMTP_PORT=465` 또는 `SMTP_TLS=implicit` 명시

SMTP_FROM_EMAIL을 설정하지 않으면 RESEND_FROM_EMAIL을 사용합니다. 사설 CA 또는 자체 서명 인증서를 사용하려면 컨테이너 신뢰 저장소에 CA를 추가해야 합니다. SMTP_TLS_INSECURE=true는 인증서 검증을 건너뛰므로 신뢰할 수 있는 내부 네트워크에서만 임시로 사용하세요.

일부 엄격한 relay에는 유효한 EHLO 이름도 필요합니다.

SMTP_EHLO_NAME=mail.example.com

이메일 서비스가 없을 때의 동작

서버는 계속 시작되지만 인증 코드와 초대 링크가 이메일로 전송되지 않고 로그에만 기록됩니다. 로컬 개발에는 적합하지만 프로덕션 환경에는 적합하지 않습니다.

시작 로그에는 현재 Resend API, SMTP relay, DEV mode 중 무엇을 사용하는지 표시됩니다.

로컬 고정 인증 코드

로컬 자동화 테스트에서는 고정 인증 코드를 설정할 수 있습니다.

APP_ENV=development
MULTICA_DEV_VERIFICATION_CODE=888888

인증 코드는 6자리 숫자여야 합니다. APP_ENV=production에서는 고정 코드가 무시됩니다.

공개 인터넷에 노출된 인스턴스에서 고정 인증 코드를 사용하지 마세요. 프로덕션 환경에서는 APP_ENV=production을 사용하고 MULTICA_DEV_VERIFICATION_CODE를 비워 둡니다.

Google 로그인

Google Cloud Console에서 OAuth 2.0 client를 만듭니다.
Multica 프런트엔드의 callback 주소를 Authorized redirect URIs에 추가합니다.
```
https://multica.example.com/auth/callback
```

다음을 설정합니다.

GOOGLE_CLIENT_ID=xxxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxx
GOOGLE_REDIRECT_URI=https://multica.example.com/auth/callback

API 서비스를 다시 시작합니다.

Google Console과 GOOGLE_REDIRECT_URI의 주소는 프로토콜, 포트, 마지막 슬래시까지 완전히 같아야 합니다. 설정이 적용되면 로그인 페이지에 Google 로그인 버튼이 표시됩니다. 프런트엔드 이미지를 다시 빌드할 필요는 없습니다.

가입 범위 제어

세 변수가 새 계정을 만들 수 있는지 함께 결정합니다.

변수	역할
`ALLOWED_EMAILS`	허용할 전체 이메일 주소, 여러 값은 쉼표로 구분
`ALLOWED_EMAIL_DOMAINS`	허용할 이메일 도메인, 여러 값은 쉼표로 구분
`ALLOW_SIGNUP`	allowlist가 없을 때 가입 허용 여부, 기본값 `true`

판단 순서는 다음과 같습니다.

이메일이 ALLOWED_EMAILS와 일치하면 허용합니다.
또는 도메인이 ALLOWED_EMAIL_DOMAINS와 일치하면 허용합니다.
allowlist가 없고 ALLOW_SIGNUP=true이면 허용합니다.
그 외에도 해당 이메일에 대기 중이며 만료되지 않은 워크스페이스 초대가 있으면 허용합니다.
나머지는 거부합니다.

일반적인 설정:

# 회사 도메인과 초대받은 사용자 허용
ALLOW_SIGNUP=false
ALLOWED_EMAIL_DOMAINS=company.com

# 외부 협업자 한 명 추가 허용
ALLOWED_EMAILS=partner@example.net

ALLOW_SIGNUP=false일 때도 두 allowlist를 명시적인 예외 목록으로 사용할 수 있습니다.

대기 중이며 만료되지 않은 워크스페이스 초대가 있으면 ALLOW_SIGNUP=false이거나 이메일이 ALLOWED_EMAILS 또는 ALLOWED_EMAIL_DOMAINS와 일치하지 않아도 계정을 만들 수 있습니다. 이 예외는 ALLOW_SIGNUP=true이고 allowlist가 설정된 경우에도 적용됩니다. allowlist는 유효한 초대를 받은 사용자를 차단하는 절대적인 경계가 아닙니다.

기존 사용자는 계속 로그인할 수 있습니다. 새 사용자가 allowlist와 일치하지 않고 공개 가입도 허용되지 않으면 대기 중이며 만료되지 않은 초대가 필요합니다. 없거나 만료, 수락, 거절, 취소된 초대는 가입 권한을 부여하지 않습니다. 로그인 코드를 요청할 때와 계정을 만들 때 초대를 확인하며, Google 로그인으로 계정을 만드는 경우에도 적용됩니다.

일반 초대 사용자를 ALLOWED_EMAILS에 추가하거나 서버를 다시 시작할 필요가 없습니다. 워크스페이스에 참여하려면 계정을 만든 뒤에도 정상 초대 흐름에서 초대를 수락해야 합니다.

초대를 취소해도 해당 초대로 이미 만든 계정은 삭제되지 않으며 기존 계정의 로그인도 차단되지 않습니다.

로그인 유효 기간

세션은 슬라이딩 갱신됩니다. 아래 값은 로그인 시점부터의 카운트다운이 아니라 유휴 한도입니다. 남은 유효 기간이 절반 아래로 내려가면 다음 요청에서 전체 기간으로 다시 발급되므로, 계속 사용하는 계정이 주기적으로 로그아웃되지 않습니다. 절대 상한은 없습니다.

이 한도는 한쪽 방향으로만 적용됩니다. 절반 아래로 내려간 뒤에야 다시 발급되므로, 마지막 사용 시점에 절반 이상 남아 있던 세션은 연장되지 않습니다. 항상 견딜 수 있는 유휴 시간은 아래 값의 절반입니다.

AUTH_TOKEN_TTL로 조정할 수 있으며 Go duration 또는 양의 정수 초를 지원합니다.

AUTH_TOKEN_TTL=720h

최솟값은 60s이며, 더 짧은 값은 60s로 조정되고 시작 시 경고가 기록됩니다. 이보다 짧으면 서버가 계산한 갱신 확인 주기가 클라이언트의 하한보다 낮아져, 세션이 유지될 수 있는 시간보다 드물게 확인하게 됩니다.

변경 후 API 서비스를 다시 시작해야 합니다. 이 값은 이후 발급되거나 다시 발급되는 세션에 적용됩니다. 세션은 슬라이딩 갱신되므로 기존 세션도 다음 재발급 때 새 기간을 적용받습니다.

다음 단계

환경 변수 — 전체 변수 참조를 확인합니다.
인증과 토큰 — 로그인 세션과 토큰 유형을 알아봅니다.
멤버와 권한 — 초대와 역할을 알아봅니다.