Rihpig

Posted on Aug 31 Originally published at apidog.com

Apidog에서 OAuth 2.0 API 테스트 방법 (인가 코드, 클라이언트 자격 증명, 토큰 갱신)

모든 API 팀은 비슷한 문제를 겪습니다. 엔드포인트는 개별적으로 작동하지만 OAuth 2.0을 활성화하는 순간 테스트 스위트의 절반이 401 오류를 반환합니다. 권한 부여 서버, 단기 액세스 토큰, 스코프를 처리해야 하고, curl 응답에서 토큰을 헤더로 수동 복사하는 일은 금방 번거로워집니다.

오늘 Apidog을 사용해 보세요

해결책은 테스트에서 인증을 생략하는 것이 아니라, 토큰 처리를 테스트 설정에 포함해 수동 작업을 없애는 것입니다. 이 가이드에서는 대부분의 테스트 계획에서 사용하는 두 가지 흐름을 다룹니다.

사용자를 대신하는 API를 위한 OAuth 권한 부여 코드 흐름(PKCE 포함)
시스템 간 호출을 위한 클라이언트 자격 증명 흐름

전체 권한 부여 맵이 필요하다면 OAuth 2.0 흐름 개요를 참고하세요.

실습에서는 Apidog에서 OAuth 2.0을 구성하고, 토큰을 여러 요청에 재사용하며, 만료된 토큰을 자동 갱신하고, 폴더 수준 인증을 상속받고, 실패 경로를 테스트합니다.

API 테스트에 중요한 두 가지 흐름

OAuth 2.0에는 여러 권한 부여 유형이 있지만, 일상적인 API 테스트에서는 다음 두 가지가 대부분의 상황을 해결합니다.

PKCE를 사용한 권한 부여 코드 흐름

권한 부여 코드 흐름은 사용자와 연결된 토큰을 얻는 표준 방식입니다.

클라이언트를 권한 부여 서버로 리디렉션합니다.
사용자가 로그인하고 동의합니다.
서버가 일회성 코드를 리디렉션 URI로 전달합니다.
클라이언트가 토큰 엔드포인트에서 코드를 액세스 토큰으로 교환합니다.

전체 과정은 RFC 6749 섹션 4.1에 정의되어 있습니다.

PKCE(RFC 7636)는 이 교환 과정을 강화합니다. 클라이언트는 임의의 검증자(verifier)를 생성하고, 권한 부여 요청에는 해시된 챌린지를 포함합니다. 코드를 교환할 때 원래 검증자를 제시해 소유권을 증명하므로, 코드를 가로챈 공격자는 이를 사용할 수 없습니다.

PKCE는 모바일 앱 문제를 해결하기 위해 시작되었지만, oauth.net은 기밀 클라이언트를 포함한 모든 권한 부여 코드 교환에 PKCE를 사용할 것을 권장합니다.

다음처럼 사용자에 따라 응답이 달라지는 엔드포인트에 이 흐름을 사용하세요.

호출자의 주문만 반환하는 GET /orders
역할 기반 관리자 엔드포인트
사용자별 속도 제한

클라이언트 자격 증명 흐름

OAuth 2.0 클라이언트 자격 증명 부여는 사용자를 거치지 않습니다. 클라이언트가 자체 ID와 시크릿으로 인증하고 애플리케이션을 나타내는 토큰을 받습니다.

브라우저나 리디렉션 없이 토큰 엔드포인트에 한 번 요청하면 됩니다.

curl -X POST https://auth.example.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=orders_service \
  -d [REDACTED CREDENTIAL] \
  -d scope="orders:read orders:write"

이 흐름은 다음과 같은 시스템 간 API에 적합합니다.

내부 마이크로서비스
cron 작업
배포 API를 호출하는 CI 파이프라인
자동화된 테스트

테스트 환경에서 테스트 클라이언트를 프로비저닝할 수 있다면, 사용자 ID 자체가 테스트 대상인 경우를 제외하고는 클라이언트 자격 증명을 우선 사용하세요.

Apidog에서 OAuth 2.0 인증 구성

Apidog은 OAuth 2.0을 기본 인증 유형으로 지원합니다. 요청 또는 폴더의 Auth 탭에서 한 번 구성하면 토큰 가져오기, 첨부, 갱신을 관리합니다.

지원되는 권한 부여 유형은 다음과 같습니다.

권한 부여 코드
권한 부여 코드(PKCE 포함)
클라이언트 자격 증명
비밀번호 자격 증명
암시적(Implicit)

다음은 가상의 주문 관리 API를 기준으로 한 설정입니다.

클라이언트 자격 증명 설정

요청을 열고 인증 유형을 OAuth 2.0으로 변경한 뒤, 권한 부여 유형으로 클라이언트 자격 증명을 선택합니다. 가능하면 개별 요청보다 폴더에 설정하는 것이 좋습니다.

다음 값을 입력하세요.

액세스 토큰 URL: https://auth.example.com/oauth/token
클라이언트 ID: orders_service
클라이언트 시크릿: 프로비저닝된 시크릿
스코프: orders:read orders:write 고급 옵션에서 설정합니다.

Apidog은 자격 증명을 다음 두 방식으로 전달할 수 있습니다.

기본 인증 헤더
요청 본문

권한 부여 서버가 기대하는 방식을 선택하세요. Auth0와 Okta는 두 방식을 모두 허용하지만, 일부 자체 구현 서버는 본문만 파싱합니다.

토큰 가져오기를 클릭하면 Apidog이 토큰 엔드포인트를 호출하고 결과를 저장합니다. 이후 모든 요청에 Bearer 접두사가 붙은 Authorization 헤더가 자동으로 추가됩니다. 토큰을 복사하거나 {{token}} 변수를 연결할 필요가 없습니다.

PKCE를 사용한 권한 부여 코드 설정

사용자 컨텍스트를 테스트하려면 권한 부여 유형으로 권한 부여 코드(PKCE 포함)를 선택합니다. Apidog에서 PKCE는 별도 권한 부여 옵션입니다.

다음 필드를 입력하세요.

인증 URL: https://auth.example.com/oauth/authorize
액세스 토큰 URL: https://auth.example.com/oauth/token
콜백 URL: 공급자에 등록된 리디렉트 URI
클라이언트 ID 및 클라이언트 시크릿: OAuth 앱 등록 정보

토큰 가져오기를 클릭하면 Apidog이 로그인 페이지를 여는 브라우저 창을 표시합니다. 테스트 사용자로 로그인하고 동의 화면을 승인하면 토큰이 반환되어 같은 관리 슬롯에 저장됩니다.

공급자가 액세스 토큰과 함께 OpenID Connect ID 토큰을 반환한다면 사용된 토큰 유형 옵션으로 첨부할 토큰을 선택할 수 있습니다. API가 ID 토큰을 검증하는 경우 유용합니다.

역할별 전용 테스트 사용자를 유지하는 것도 좋습니다.

구매자
관리자
읽기 전용 감사자

각 사용자로 토큰을 가져온 뒤 같은 시나리오를 실행하면 역할 기반 접근 제어를 빠르게 검증할 수 있습니다.

토큰 재사용 및 자동 갱신

액세스 토큰은 일반적으로 한 시간 이내에 만료됩니다. 자동 관리가 없으면 토큰 만료로 테스트가 실패하고, 매번 수동으로 토큰을 다시 가져와야 합니다. 이런 불안정한 실패는 쉽게 무시됩니다.

Apidog은 권한 부여 서버가 갱신 토큰을 발행한 경우 OAuth 2.0 토큰을 자동으로 갱신합니다. 이 기능은 6월 업데이트에 포함되었습니다.

저장된 액세스 토큰이 만료되면 Apidog이 갱신 토큰으로 새 토큰을 가져와 요청 전에 교체합니다. 공급자가 별도의 갱신 토큰 URL을 사용하는 경우 고급 설정에서 사용자 지정 URL을 지정할 수 있습니다.

클라이언트 자격 증명 흐름에서는 갱신 토큰을 발행하지 않는 서버가 많습니다. 클라이언트가 언제든 다시 인증할 수 있으므로 사양상 허용되는 동작입니다. 이 경우 토큰 가져오기를 다시 클릭하면 됩니다. 예약 작업이나 CI에서는 실행 시작 시 새 토큰을 요청하도록 구성할 수도 있습니다.

폴더 수준에서 인증 상속

모든 요청에 OAuth를 개별 설정하는 대신 폴더에 인증을 설정하세요. 폴더 안의 요청은 상위 폴더 구성을 상속합니다.

예를 들어 주문 API 폴더에 OAuth 2.0을 한 번 설정하면, 기존 요청은 물론 다음 스프린트에 추가되는 요청도 같은 관리 토큰을 사용합니다.

다단계 시나리오에서는 특히 유용합니다.

POST /carts
POST /carts/{id}/items
POST /orders

세 요청이 하나의 토큰과 설정을 공유하므로 다음 작업이 간단해집니다.

시나리오 중간의 토큰 만료 처리
클라이언트 시크릿 교체
수십 개 요청의 인증 설정 관리

요청별로 상위 설정을 재정의할 수도 있습니다. 이 기능은 부정적인 테스트에 사용합니다.

실패 경로 테스트

해피 경로 테스트는 토큰 파이프라인이 작동한다는 것을 보여줍니다. 실패 경로 테스트는 API가 인증을 제대로 강제하는지 검증합니다.

상태 코드의 의미는 API 키와 베어러 토큰 비교를 참고하세요.

만료되었거나 누락된 토큰: 401 예상

시나리오의 요청을 복제하고 상속된 인증을 다음 중 하나로 재정의합니다.

인증 없음
Bearer [REDACTED]

다음 항목을 단언하세요.

상태 코드가 401
WWW-Authenticate 응답 헤더가 존재함
본문에 스택 추적이나 내부 호스트 이름이 노출되지 않음

RFC 6750에 따르면 WWW-Authenticate 헤더가 예상됩니다.

200 응답은 심각한 버그입니다. 403 응답도 설계 오류로 보고할 가치가 있습니다. 서버는 “사용자를 인증할 수 없음”과 “인증은 되었지만 권한이 없음”을 구분해야 합니다.

잘못된 스코프: 403 예상

orders:read만 허용하는 두 번째 테스트 클라이언트를 만들고 토큰을 가져온 뒤, POST /orders처럼 쓰기 권한이 필요한 엔드포인트를 호출합니다.

다음 항목을 확인하세요.

상태 코드가 403
RFC 6750을 따른다면 WWW-Authenticate 헤더에 error="insufficient_scope"가 포함됨

이 테스트는 어떤 경로에서는 게이트웨이가 스코프를 확인하지만 다른 경로에서는 검사를 빠뜨리는 잘못된 구성을 찾는 데 효과적입니다.

스코프 설계가 익숙하지 않다면 OAuth 2.0 스코프 설명을 참고하세요.

유효하지 않은 클라이언트: 토큰 엔드포인트 오류 예상

잘못된 client_secret으로 토큰 엔드포인트에 직접 요청을 보냅니다.

https://auth.example.com/oauth/token

RFC 6749 섹션 5.2에 따르면 서버는 다음 중 하나를 반환해야 합니다.

일반적인 경우 400
클라이언트 인증 실패의 경우 401

응답 JSON에는 다음 오류가 포함되어야 합니다.

{
  "error": "invalid_client"
}

권한 부여 서버 역시 API이므로, 오류 계약도 서비스 표면의 일부로 테스트해야 합니다.

토큰 응답에 대한 단언

토큰 엔드포인트는 잘못된 클라이언트 외에도 별도의 검증이 필요합니다. 테스트 시나리오에서 토큰 엔드포인트를 직접 호출하고 다음 응답 조건을 단언하세요.

access_token이 존재하고 비어 있지 않음
token_type이 bearer와 일치함 사양상 대소문자는 구분하지 않습니다.
expires_in이 0보다 크고 정책 범위 내에 있음 예: 3600 이하
scope가 요청한 값과 일치함 서버가 권한을 조용히 축소하는 문제를 찾을 수 있습니다.

Apidog 시나리오에서는 스크립트 없이 응답 JSON에 시각적 단언을 추가할 수 있습니다. 관리형 인증 대신 원시 핸드셰이크를 테스트하려면 access_token을 변수로 추출해 다음 단계에서 사용하세요.

이 시나리오를 CI에 연결하면 권한 부여 서버의 문제를 프로덕션에서 알 수 없는 401 오류로 발견하는 대신, 빌드 단계에서 즉시 실패시킬 수 있습니다.

권장 구성은 다음과 같습니다.

해피 경로에는 폴더 수준 OAuth 2.0을 사용합니다.
401 및 403 테스트에는 요청별 인증 재정의를 사용합니다.
토큰 엔드포인트 계약을 별도 시나리오로 검증합니다.
사용자 컨텍스트 API에는 PKCE 권한 부여 코드를 사용합니다.
서비스 간 API에는 클라이언트 자격 증명을 사용합니다.
갱신 토큰이 있는 경우 자동 갱신을 활성화합니다.

Apidog을 다운로드하여 무료로 사용해 보세요. OAuth 2.0 인증 유형은 무료 플랜에서도 사용할 수 있으므로, 몇 분 안에 자체 토큰 엔드포인트에 연결할 수 있습니다.

FAQ

API 테스트에는 어떤 OAuth 흐름을 사용해야 하나요?

시스템 간 작업과 대부분의 자동화된 테스트 스위트에는 클라이언트 자격 증명을 사용하세요. 브라우저 상호 작용이 필요 없기 때문입니다.

테스트가 사용자 ID에 의존한다면 PKCE를 사용한 권한 부여 코드 흐름을 선택하세요.

사용자별 데이터 격리
역할 검증
동의 동작 검증

새 테스트 계획에서는 암시적(implicit) 및 비밀번호(password) 권한 부여를 피하는 것이 좋습니다. 두 방식 모두 현재 OAuth 지침에서 권장되지 않습니다.

Apidog에서 만료된 토큰을 자동으로 갱신하려면 어떻게 해야 하나요?

Auth 탭에서 OAuth 2.0을 구성하고 토큰 가져오기로 토큰을 가져오세요. 권한 부여 서버가 갱신 토큰을 반환하면 Apidog이 만료 시 액세스 토큰을 자동으로 갱신합니다.

공급자가 별도의 갱신 토큰 URL을 사용한다면 고급 설정에서 지정할 수 있습니다. 갱신 토큰이 없는 클라이언트 자격 증명 설정에서는 토큰 가져오기를 다시 실행하면 새 토큰을 받을 수 있습니다.

시나리오의 모든 요청이 하나의 OAuth 토큰을 공유할 수 있나요?

가능합니다. 상위 폴더에 OAuth 2.0을 설정하면 내부 요청이 해당 설정을 상속하므로 다단계 시나리오가 하나의 관리 토큰으로 실행됩니다.

개별 요청은 폴더 설정을 재정의할 수 있습니다. 따라서 만료된 토큰이나 잘못된 스코프 같은 부정적인 테스트도 같은 시나리오에 포함할 수 있습니다.

OAuth 보호 API에서 401과 403은 무엇을 의미해야 하나요?

인증에 실패하면 401을 반환해야 합니다.

토큰이 없음
토큰이 만료됨
토큰 형식이 잘못됨

토큰은 유효하지만 권한이 부족하면 403을 반환해야 합니다. 예를 들어 필요한 스코프가 없는 경우입니다.

두 상태를 혼동하면 클라이언트 재시도 로직이 깨집니다. 401은 다시 인증하라는 의미이고, 403은 요청을 중단하라는 의미이기 때문입니다.

토큰 자체의 유효성 검사는 JWT 인증 테스트 가이드를 참고하세요.

DEV Community