# UserFront 사용자 가이드

## 로그인

UserFront는 Baron SSO 로그인, 연결 승인, consent, 연동 앱 탐색의 사용자 접점이다.

1. 서비스 또는 UserFront에서 로그인을 시작한다.
2. email, phone, employee ID 등 화면에 허용된 식별자를 입력한다.
3. 다른 기기 승인이나 link가 필요한 경우 화면의 pending 상태를 유지한다.
4. 승인 후 원래 서비스 또는 UserFront로 돌아오는지 확인한다.

`잠시 사용할 수 없음`이나 readiness 오류를 미가입·비밀번호 오류로 해석하지 않는다. 잠시 뒤 재시도하고 계속 실패하면 표시된 추적 정보와 시각을 운영자에게 전달한다.

## Consent

- 필수 scope는 해제할 수 없다.
- 선택 scope는 서비스에 제공할 정보 범위를 보고 선택한다.
- 동의를 거부하면 로그인 시도는 원래 RP로 오류와 함께 돌아갈 수 있다.
- 과거 동의는 활동상황 또는 연결된 서비스 화면에서 확인한다.
- 연동 해지는 해당 RP의 consent와 authorization에 영향을 주며 다음 접속에서 다시 동의를 요구할 수 있다.

## 연결된 서비스

- RP card를 선택하면 등록된 서비스 시작 URL 또는 홈페이지로 이동한다.
- 자동 로그인 지원 RP는 별도 login button 없이 OIDC 흐름을 시작할 수 있다.
- UserFront가 RP의 `state`, `nonce`, PKCE를 대신 만들지 않는다.
- 예상하지 않은 도메인이나 redirect가 보이면 진행하지 않고 운영자에게 알린다.

## QR과 다른 기기 승인

- QR을 표시한 기기가 로그인 대상이고 스캔 기기는 승인을 수행한다.
- QR이나 link가 만료되면 현재 화면에서 새 요청을 발급한다.
- `pending`은 실패가 아니다. 승인 완료 또는 만료까지 화면 안내를 따른다.
- 같은 요청을 여러 창에서 반복 승인하지 않는다.

## 로그아웃

- UserFront 로그아웃은 Kratos session을 종료한다.
- 연결된 RP는 Back-Channel Logout, token refresh 실패, `/user/me` 재검증 등 지원 방식에 따라 local session을 정리한다.
- SMS 또는 NAVER WORKS 원격 로그아웃 link는 대상 서비스와 요청 시각을 확인한 뒤 승인한다.
- 의심스러운 요청은 승인하지 말고 UserFront에서 직접 session 상태를 확인한다.

## 비밀번호와 복구

1. 로그인 화면의 복구 진입점을 사용한다.
2. 수신한 link/code의 대상 계정과 만료 여부를 확인한다.
3. 새 비밀번호 설정 뒤 기존 session이 유지되는지 화면 안내를 따른다.
4. 이미 사용했거나 만료된 복구 요청은 새로 발급한다.

인증·로그인 정책의 정본은 [Authentication and Login Flow](https://gitea.hmac.kr/baron/baron-sso/wiki/Authentication-and-Login-Flow)다.

## TOTP와 recovery code

- 보안 설정 화면에서 Kratos TOTP를 등록·해제하고 recovery code를 발급한다. TOTP secret은 계정당 하나이며 RP별 secret을 만들지 않는다.
- TOTP 등록은 서로 다른 30초 구간에 표시된 코드 두 개를 연속으로 확인해야 완료된다. 첫 코드 직후에는 다음 코드로 바뀔 때까지 기다린 뒤 두 번째 값을 입력한다.
- recovery code는 TOTP의 평상시 대체 수단이 아니라 계정 복구에만 사용한다. 발급 직후 안전한 장소에 보관하고, 노출되었거나 사용한 code는 다시 발급한다.
- recovery code로 TOTP를 해제한 session은 새 TOTP를 등록하고 두 번째 코드까지 확인하기 전에는 비밀번호 변경, RP, AdminFront, DevFront, token 경로로 이동할 수 없다.
- 이 복구는 lookup secret을 Kratos에 제출하기 전에 session 한정 `lookup_pending` 상태로 서버에 먼저 기록된다. 원장을 기록할 수 없으면 lookup secret도 제출하지 않는다. 명시적인 잘못된 code 응답은 pending을 취소하고, 응답 결과가 불명확하면 해당 session만 격리한다. Kratos가 성공을 확인한 뒤에만 `lookup_self_recovery`를 `session_bound`로 승격하고 같은 identity의 다른 session을 즉시 fence한다. 복구를 시작한 동일 session만 새 TOTP 등록과 recovery code 재발급을 끝낼 수 있다.
- Tenant 또는 RP가 AAL2를 요구하는데 현재 session이 부족하면 UserFront가 Kratos AAL2 로그인 화면으로 이동시킨다. Factor 검증이 끝나면 원래 로그인 흐름을 이어간다.
- 비밀번호 reset 또는 TOTP reset 대상 계정은 최초 정상화 session에서 비밀번호 변경, TOTP 등록, recovery code 확인을 지정된 순서대로 완료한다. 이 흐름이 끝나기 전에는 일반 제품·RP·token 경로를 사용할 수 없다.
- 일반 보안 설정의 비밀번호 변경, TOTP 초기화, recovery code 재발급, 신뢰할 수 있는 브라우저 등록은 작업 직전에 현재 TOTP를 다시 검증한다. recovery code로 얻은 AAL2는 이 fresh-TOTP 확인을 대신할 수 없다.

## 신뢰할 수 있는 브라우저

- AAL2 session에서 현재 브라우저를 등록할 수 있다. private key는 브라우저의 Web Crypto와 IndexedDB에 non-extractable key로 보관하며 서버에는 public JWK만 저장한다.
- grant는 최대 30일이며 현재 브라우저에서 자동 proof를 수행한다. 폐기, 만료, key 손실 또는 replay 검출 시 다시 등록해야 한다.
- 신뢰할 수 있는 브라우저만으로 Tenant AAL2를 유예하지 않는다. Connect 후보의 내부망 Network Assurance까지 같은 요청에서 성공해야 하며, RP AAL2·Fresh TOTP·Exact Super Admin 요구는 유예하지 않는다.