4. 인증 API#
DataAPI는 JWT Bearer 인증과 Basic 인증을 지원한다.
- JWT Bearer 인증: 최초 인증 후 발급받은 토큰을 이후 요청에 재사용하는 방식으로, 매 요청마다 자격증명을 전송하지 않고도 세션을 유지할 수 있다. 토큰 만료, 갱신, 로그아웃, 세션 초기화 등의 인증 흐름을 직접 제어하려는 애플리케이션 클라이언트에 적합하다.
- Basic 인증: 별도의 토큰 발급 과정 없이 매 요청마다 자격증명을 직접 전달하는 방식으로, 별도 로그인이나 토큰 관리 없이 요청마다 DB 자격증명을 독립적으로 검증해야 하는 스크립트, 배치 작업, 모니터링 수집 계정에 적합하다.
엔드포인트 인증 헤더#
JWT Bearer 인증#
클라이언트는 최초 인증 요청을 통해 Access 토큰을 발급받고, 이후 요청의 Authorization 헤더에 Bearer 스킴과 함께 토큰을 포함하여 전달한다. Bearer 인증 방식은 토큰의 서명 및 만료 시간 검증, 블록리스트 등록 여부, Access 토큰 여부 및 세션 풀의 유효성을 함께 검사한다.
Authorization: Bearer <access-token>
토큰은 발급 시점부터 일정 시간 동안만 유효하며, 만료된 경우 재인증을 통해 새 토큰을 발급받아야 한다.
Basic 인증#
클라이언트는 사용자 이름과 비밀번호를 username:password 형식으로 결합한 뒤 Base64로 인코딩하여 Authorization 헤더에 포함한다. 별도의 토큰 발급 과정이 없으므로, 요청마다 자격증명이 함께 전송된다.
Authorization: Basic <base64(username:password)>
Note
Basic 인증은 매 요청마다 자격증명을 검증하며, 검증 성능 향상을 위해 최근 검증 결과를 짧은 시간 동안 재사용할 수 있다. 이로 인해 사용자 권한(role)이 변경된 직후 일정 시간 동안은 변경 사항이 즉시 반영되지 않을 수 있다.
4.1 로그인#
엔드포인트 :
POST /dataapi/auth/token
요청:
{
"username": "app_user",
"password": "app_password"
}
성공 응답:
{
"accessToken": "<jwt-access-token>",
"refreshToken": "<jwt-refresh-token>"
}
Bearer 인증을 사용하는 클라이언트는 최초 인증 시 이 API를 호출하여 Access 토큰과 Refresh 토큰을 발급받아야 한다.
로그인에 성공하면 해당 사용자만을 위한 JWT Bearer 커넥션 풀이 개별적으로 생성되며, Access 토큰과 Refresh 토큰이 발급된다. 두 토큰은 동일한 로그인 세션에 속하며, 동일한 JWT 세션 식별자를 공유한다. 입력한 비밀번호는 로그인 검증에만 사용되며, 보안을 위해 서버에 저장되지 않는다.
한편, 동일한 사용자에 대해 이미 활성화된 JWT 세션 풀이 존재하는 상태에서 새로운 로그인을 시도할 경우, 해당 요청은 AUTH_014 오류로 거부될 수 있다. 이 경우 기존에 발급받은 토큰으로 계속 요청을 수행하거나, 로그아웃 후 재로그인해야 한다.
4.2 Access 토큰 갱신#
엔드포인트 :
POST /dataapi/auth/refresh
요청:
{
"refreshToken": "<jwt-refresh-token>"
}
성공 응답:
{
"accessToken": "<new-jwt-access-token>",
"refreshToken": "<new-jwt-refresh-token>"
}
Access 토큰이 만료되면 클라이언트가 직접 /auth/refresh를 호출하여 토큰을 갱신해야 한다.
DataAPI는 만료된 Access 토큰을 자동으로 갱신하거나 요청을 재시도하지 않는다. 따라서 토큰 갱신과 원래 요청의 재시도는 클라이언트가 직접 처리해야 한다.
Refresh 토큰은 갱신할 때마다 새로운 토큰으로 교체되며, 이전 Refresh 토큰은 더 이상 사용할 수 없다. 이미 사용되었거나 교체된 Refresh 토큰으로 갱신을 요청하면 AUTH_010 오류가 발생한다.
Caution
토큰 갱신에 성공하면 클라이언트는 기존 Access 토큰과 Refresh 토큰을 모두 새로 발급된 값으로 교체해야 한다.
클라이언트 구현 예시는 부록 B. Refresh Token 클라이언트 구현 예제를 참고한다.
4.3 JWT 세션 초기화#
엔드포인트 :
POST /dataapi/auth/session/reset
요청:
{
"username": "app_user",
"password": "app_password"
}
성공 응답:
- HTTP 200 OK
- 본문 없음
JWT 세션을 초기화하면 현재 로그인 세션이 종료되고, 이전에 발급된 Access 토큰과 Refresh 토큰은 모두 사용할 수 없다.
세션 초기화 후에는 자동으로 다시 로그인되지 않으므로, API를 계속 사용하려면 /auth/token을 호출하여 새로운 Access 토큰과 Refresh 토큰을 발급받아야 한다.
4.4 로그아웃#
엔드포인트 :
POST /dataapi/auth/logout
요청 헤더:
Authorization: Bearer <jwt-access-token>
요청:
{
"refreshToken": "<jwt-refresh-token>"
}
성공 응답:
- HTTP 200 OK
- 본문 없음
로그아웃에 성공하면 현재 로그인 세션이 종료되며, 사용 중인 Access 토큰과 Refresh 토큰은 모두 무효화된다. 로그아웃 요청에 포함된 Access 토큰과 Refresh 토큰은 동일한 로그인 세션에서 발급된 것이어야 한다. 서로 일치하지 않거나 유효하지 않은 토큰으로 요청하면 로그아웃이 실패한다.
Note
이 API는 JWT(Bearer) 인증을 사용하는 클라이언트를 위한 API이다. Basic 인증은 로그인 세션을 생성하지 않으므로, 로그아웃 API를 사용할 수 없다.