본문으로 건너뛰기
버전: 개발 버전 (최신)

인증 방법

개요​

dta-wide API는 두 가지 주요 인증 방식을 사용합니다.

인증 유형​

1. 앱 인증​

앱 인증은 모바일 애플리케이션이 dta-wide 백엔드 서버와 통신하기 전에 수행되는 첫 번째 보안 계층입니다. 이 과정은 정당한 클라이언트 앱만이 API에 접근할 수 있도록 보장합니다.

  • 디바이스 ID와 시간 기반 챌린지-응답 메커니즘 사용
  • 앱 토큰 발급 및 관리
  • 사용자 로그인 전에 필수적으로 완료해야 함

앱 인증 상세 정보

2. 사용자 인증​

사용자 인증은 개별 사용자의 신원을 확인하고 해당 사용자에게 적절한 권한과 자원에 대한 접근을 제공합니다.

  • JSON Web Token(JWT) 기반 인증
  • 액세스 토큰 및 리프레시 토큰 관리
  • 사용자별 인증 상태 및 권한 관리

사용자 인증 상세 정보

인증 방식 활용​

  1. 앱 출시 후 최초 실행 시:

    • 앱 인증을 통해 appToken 획득
    • appToken으로 공개 API 호출 가능

  2. 사용자 로그인 시:

    • 앱 인증 상태에서 사용자 로그인 수행
    • accessToken 및 refreshToken 획득

  3. 보호된 리소스 접근 시:

    • 사용자 accessToken으로 인증 필요 API 호출
    • 토큰 만료 시 refreshToken으로 갱신

v2 EU 인증 정책​

EU 환자용 v2 인증 표면은 다음 6가지 정책을 따릅니다 — v1(KR password 기반) 과 차이가 큽니다.

1. Authorization: Bearer 단일 채널​

모든 v2 EU endpoint 는 인증을 Authorization: Bearer <token> 한 줄로만 받습니다. 별도 헤더를 보내도 무시되며 인증 의미를 갖지 않습니다.

토큰 종류는 endpoint 마다 다릅니다:

Endpoint 분류Authorization Bearer가드
/v2/auth/app/* (토큰 발급)없음없음 (공개)
/v2/auth/email/*, /v2/security/appcheck/verifyapp tokenapp token 검증
/v2/auth/register/eid/*, /v2/auth/register/native/*app tokenapp token 검증
/v2/auth/eid/login/*, /v2/auth/login/native/*app token 또는 user access token (분기)서버 라우팅
/v2/auth/user-cycle/activate, /v2/auth/user-cycle/stateuser access token사용자 토큰 검증

서버 라우팅 는 Authorization Bearer 의 payload 종류를 보고 app token = first-login / 새 기기 첫 로그인, user access token = 재로그인 분기로 라우팅합니다.

2. deviceId 는 token payload 에서​

/v2/auth/app/challenge·complete-challenge (토큰 발급 단계)만 body 로 deviceId(객체)+deviceIdHash 를 받습니다. 그 이후의 모든 v2 EU endpoint 는 deviceId 를 token payload(request.appPayload.deviceId 또는 request.user.deviceId)에서 가져옵니다 .

body 에 deviceId 를 포함하면 forbidNonWhitelisted 정책에 의해 400 VALIDATION_ERROR 가 반환됩니다. 이는 client 가 token 과 무관하게 deviceId 를 위조할 수 있던 surface 를 차단하기 위한 의도된 변경입니다.

3. AppCheck 는 verify-only​

POST /v2/security/appcheck/verify 는 토큰을 검증하고 {verified, reason?} 만 반환합니다. 세션토큰(appCheckSessionToken) 발급 없음, 보호 endpoint 에 X-AppCheck-Session-Token 헤더 없음. 앱 부팅 후 한 번 호출해 attest 를 통과시키면 됩니다.

4. signup ack-only + first-login 분리 (4-STAGE 흐름)​

EU 가입은 4 STAGE 로 분리됩니다:

  1. 회원가입 (ack-only): /v2/auth/register/{eid,native}/complete 가 User+Profile(+EidLink/+디바이스 키) 생성만 수행하고 응답 {success:true} 만 반환. 토큰 미발급.
  2. 첫 로그인 (first-login): /v2/auth/eid/login/complete (Authorization=app token + body LOGIN OTP) 또는 /v2/auth/login/native/complete (Authorization=app token + body signature) 가 첫 access/refresh 를 발급. 이 시점은 REGISTERED 상태이므로 token payload 에 uci 가 없습니다.
  3. 서비스 활성화: /v2/auth/user-cycle/activate (Authorization=user access token) 가 UserCycle 을 생성하고 uci 가 박힌 토큰을 재발급합니다 (SERVICE_STARTED).
  4. 재로그인 / 새 기기 첫 로그인: 활성 사용자의 후속 로그인. Authorization 토큰 종류로 분기합니다.

가입과 토큰 발급을 분리해서 (a) AppCheck failure 가 가입 자체를 막지 않게 했고, (b) 토큰 발급 책임을 LoginResponseBuilder 에 단일화했습니다.

5. �� AccessCode 는 서비스 활성화 시점​

v2 가입에서는 accessCode 를 받지 않습니다 . 가입 단계의 cohort 는 항상 standard 이고, clinical cohort 분기와 AccessCode 검증은 /v2/auth/user-cycle/activate 에서 수행됩니다.

6. Endpoint 경로​

  • 옛 표기 /v2/auth/signup/eid/* 는 폐기 — 모두 /v2/auth/register/eid/* 로 통일.
  • Native 2FA 가입/로그인은 별도 endpoint 묶음 (/v2/auth/register/native/*, /v2/auth/login/native/*).

더 자세히​