ADR-005: Keycloak 인증 사용자 내부 자동 등록

Status

Accepted

Date

2026-05-12

Context

Keycloak 이 로그인과 계정 lifecycle 을 소유하면 auth-server 는 검증된 access token 으로 내부 사용자 레코드를 식별해야 합니다. 기존 결정은 내부 사용자가 없으면 AUTH-004 404 를 반환하는 방식이었지만, 이 방식은 Keycloak self-service registration 과 auth-server 의 내부 사용자 테이블을 별도 운영 절차로 동기화해야 했습니다.

자동 등록을 도입하더라도 email 을 계정 연결 키로 쓰면 안 됩니다. email 은 변경되거나 재사용될 수 있으므로 내부 권한 식별자는 계속 Keycloak sub 와 (provider=KEYCLOAK, provider_subject=sub) 조합이어야 합니다.

Decision Drivers

Keycloak self-service registration 이후 첫 API 호출에서 내부 사용자 레코드를 준비한다.
인증 주체와 token 발급 책임은 계속 Keycloak 에 둔다.
email 은 충돌 검사에만 사용하고 내부 계정 연결 키로 사용하지 않는다.
내부 사용자 생성은 application use case 의 트랜잭션 경계 안에서 수행한다.
Resource Server 부팅은 Keycloak discovery endpoint 가 떠 있어야만 성공하는 구조를 피한다.

Considered Options

Option 1: 내부 사용자가 없으면 계속 404 반환

장점: GET /api/v1/auth/me 가 순수 조회로 남고 쓰기 부작용이 없다.
단점: Keycloak 사용자와 내부 사용자 테이블을 별도 배치나 운영 절차로 맞춰야 한다.
트레이드오프: HTTP 의미는 단순하지만 운영 동기화 비용이 생긴다.

Option 2: 첫 인증 요청에서 내부 사용자 자동 등록

장점: Keycloak 에서 계정을 만든 사용자가 첫 API 호출 시 바로 내부 사용자 레코드를 얻는다.
단점: GET /api/v1/auth/me 가 missing user 경로에서 쓰기를 수행한다.
트레이드오프: 사용자 온보딩은 단순해지지만 transaction, 충돌 처리, 감사 이벤트가 필요하다.

Option 3: Keycloak Admin/Event API 로 사전 동기화

장점: API 요청 경로의 쓰기 부작용을 줄일 수 있다.
단점: 외부 API 호출, retry, idempotency, 실패 보상 흐름이 필요하다.
트레이드오프: 운영 복잡도가 커지고 Keycloak 이벤트 전달 신뢰성에 의존한다.

Decision

Option 2 를 채택합니다. GET /api/v1/auth/me 는 검증된 Keycloak claim 의 sub 로 내부 사용자를 조회하고, 없으면 email 충돌을 먼저 검사한 뒤 내부 사용자를 자동 등록합니다. 동일 email 이 이미 다른 subject 에 연결되어 있으면 자동 연결하지 않고 AUTH-005 409 를 반환합니다.

Consequences

긍정적 결과

Keycloak self-service registration 과 내부 사용자 생성이 첫 API 호출에서 자연스럽게 이어진다.
내부 사용자 식별 기준은 여전히 immutable sub 이며, email 기반 자동 연결은 금지된다.
자동 등록 성공은 KEYCLOAK_USER_AUTO_REGISTERED 감사 이벤트로 남는다.

부정적 결과

GET /api/v1/auth/me 는 missing user 경로에서 DB write 를 수행한다.
동시 첫 요청에서는 DB unique 제약과 충돌 처리 정책을 함께 고려해야 한다.
운영 환경은 APP_SECURITY_KEYCLOAK_ISSUER_URI 를 제공해야 한다.

위험 완화

application use case 에 transaction boundary 를 둔다.
같은 email 이 이미 존재하면 AUTH-005 409 로 중단하고 새 subject 에 자동 연결하지 않는다.
(provider, provider_subject) unique 제약으로 subject 중복 생성을 방지한다.

3.6 KiB Raw Permalink Blame History