모든 API 팀은 동일한 문제에 봉착합니다. 엔드포인트는 개별적으로 작동하지만, 누군가 OAuth 2.0을 켜면 테스트 스위트의 절반이 401 오류를 반환하기 시작합니다. 갑자기 권한 부여 서버, 단기 액세스 토큰, 스코프를 다뤄야 하고, curl 응답에서 헤더 필드로 토큰을 수동으로 복사하는 작업은 세 번째 실행부터 지겨워집니다.
해결책은 테스트에서 인증을 건너뛰는 것이 아닙니다. 토큰 처리를 테스트 설정의 일부로 만들어 수동 작업을 없애는 것입니다. 이 가이드는 거의 모든 테스트 계획에서 접하게 될 두 가지 흐름을 다룹니다: 사용자를 대신하여 API가 작동하는 경우의 OAuth 권한 부여 코드 흐름(PKCE 포함), 그리고 시스템 간 호출을 위한 클라이언트 자격 증명 흐름입니다. 먼저 전체 권한 부여 맵을 원하시면, 저희의 OAuth 2.0 흐름 개요에서 모든 흐름을 설명합니다.
그런 다음 실습으로 들어갑니다: Apidog에서 OAuth 2.0 인증을 구성하고, 토큰을 한 번 가져와서 여러 요청에 재사용하며, 만료된 토큰이 자동으로 갱신되도록 하고, 폴더 수준에서 인증을 상속받으며, 보안 검토에서 질문할 실패 경로를 테스트합니다.
API 테스트에 중요한 두 가지 흐름
OAuth 2.0은 여러 권한 부여 유형을 정의하지만, 일상적인 API 테스트를 위해서는 그중 두 가지에 대부분의 시간을 할애할 것입니다. API가 사용자를 대신하여 작동하는지, 아니면 서비스를 대신하여 작동하는지라는 한 가지 질문을 기반으로 선택하십시오.
PKCE를 사용한 권한 부여 코드 흐름
권한 부여 코드 흐름은 사용자와 연결된 토큰을 얻는 표준적인 방법입니다. 클라이언트는 사용자를 권한 부여 서버로 보내고, 사용자는 로그인하고 동의하며, 서버는 일회성 코드를 사용하여 리다이렉트하고, 클라이언트는 토큰 엔드포인트에서 코드를 액세스 토큰으로 교환합니다. RFC 6749는 섹션 4.1에서 전체 과정을 정의합니다.
PKCE(Proof Key for Code Exchange, RFC 7636)는 교환 과정을 강화합니다. 클라이언트는 임의의 검증자(verifier)를 생성하고, 권한 부여 요청과 함께 해시된 챌린지를 보내고, 코드를 사용할 때 원래 검증자를 가지고 있음을 증명합니다. 코드를 가로챈 공격자는 이를 사용할 수 없습니다. PKCE는 모바일 앱 문제를 해결하기 위해 시작되었지만, oauth.net의 현재 지침은 모든 권한 부여 코드 교환에 이를 권장하며, 기밀 클라이언트도 포함됩니다.
엔드포인트의 동작이 사용자가 누구인지에 따라 달라지는 경우(예: 호출자의 주문만 반환하는 GET /orders, 역할 기반 관리 엔드포인트, 사용자별 속도 제한 등)에는 이 흐름으로 테스트하십시오.
클라이언트 자격 증명 흐름
OAuth 2.0 클라이언트 자격 증명 부여는 사용자를 완전히 건너뜁니다. 클라이언트는 자체 ID와 시크릿으로 인증하고, 애플리케이션 자체를 나타내는 토큰을 받습니다. 토큰 엔드포인트에 한 번 POST 요청을 보내며, 브라우저나 리다이렉트가 필요 없습니다:
curl -X POST https://auth.example.com/oauth/token \
-d grant_type=client_credentials \
-d client_id=orders_service \
-d client_secret=s3cr3t_value \
-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 포함)를 선택합니다. PKCE는 Apidog에서 체크박스가 아닌 별도의 권한 부여 옵션입니다. 몇 가지 필드가 더 필요합니다:
- 인증 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이 이를 처리하기 전에는 만료된 토큰은 실패한 실행과 수동 재가져오기를 의미했으며, 이는 팀이 무시하기 쉬운 종류의 불안정한 실패입니다.
이제 Apidog은 권한 부여 서버가 갱신 토큰을 발행했을 때 OAuth 2.0 토큰을 자동으로 갱신합니다. 이 기능은 6월 업데이트에 포함되었습니다. 저장된 액세스 토큰이 만료되면 Apidog은 갱신 토큰을 사용하여 새 토큰을 가져와 전송하기 전에 교체합니다. 공급자가 두 엔드포인트를 분리하는 경우 고급 설정에서 사용자 지정 갱신 토큰 URL을 지정할 수도 있습니다.
클라이언트 자격 증명의 경우, 많은 서버가 갱신 토큰을 완전히 건너뜁니다(클라이언트가 언제든지 다시 인증할 수 있으므로 사양에서 허용함). 실제로 이것은 문제가 되지 않습니다. 토큰 가져오기로 다시 가져오는 것은 한 번의 클릭이며, 예약되거나 CI 실행은 각 실행 시작 시 새 토큰을 요청할 수 있습니다.
폴더 수준에서 인증 상속
모든 요청에 OAuth를 구성하는 것은 잘못된 접근 방식입니다. Apidog은 폴더에 인증을 설정할 수 있도록 하며, 그 안에 있는 요청은 상위 폴더의 구성을 상속받습니다. "주문 API" 폴더에 OAuth 2.0을 한 번 설정하면, 그 아래의 모든 요청(다음 스프린트에서 팀원들이 추가할 새 요청 포함)은 동일하게 관리되는 토큰을 보냅니다.
이는 다단계 테스트 시나리오에서 가장 중요합니다. 결제 시나리오에는 POST /carts, POST /carts/{id}/items, POST /orders가 연쇄적으로 포함될 수 있습니다. 폴더 수준 인증을 사용하면 세 단계 모두 하나의 토큰과 하나의 구성을 공유합니다. 시나리오 중간에 토큰이 만료되면 자동 갱신이 이를 처리합니다. 그리고 보안 팀이 클라이언트 시크릿을 교체할 때, 40개의 요청 대신 하나의 폴더만 업데이트하면 됩니다.
요청은 상위 설정을 재정의할 수 있는 옵션을 유지하며, 이는 부정적인 테스트에 정확히 필요한 기능입니다. 이제 이에 대해 더 자세히 알아보겠습니다.
실패 경로 테스트
해피 경로 OAuth 테스트는 토큰 파이프라인이 작동함을 증명합니다. 실패 경로 테스트는 API가 인증을 강제하는지 증명합니다. 이들을 건너뛰면 프레임워크 기본값을 신뢰하게 됩니다. 여기 자동화할 가치가 있는 세 가지 경우가 있습니다. 각 상태 코드가 무엇을 의미해야 하는지에 대한 복습은 API 키와 베어러 토큰 비교를 참조하십시오.
만료되었거나 누락된 토큰: 401 예상
시나리오에서 한 요청을 복제하고, 상속된 인증을 '인증 없음' 또는 `Bearer expired_token_do_not_rotate`와 같이 하드코딩된, 오래된 베어러 토큰으로 재정의하십시오. 다음을 단언합니다:
- 상태 코드가
401과 같음 WWW-Authenticate응답 헤더가 존재함 (RFC 6749의 동반 문서인 RFC 6750은 이를 예상함)- 본문에 스택 추적이나 내부 호스트 이름이 유출되지 않음
여기서 200 응답은 심각한 버그입니다. 403 응답은 티켓을 만들 가치가 있는 설계 오류입니다. 서버는 "누구인지 모릅니다"와 "당신은 알지만, 권한이 없습니다"를 구별해야 합니다.
잘못된 스코프: 403 예상
orders:read로 제한된 두 번째 테스트 클라이언트를 프로비저닝하고, 해당 토큰을 가져와 POST /orders와 같은 쓰기 엔드포인트를 호출하십시오. 상태 코드가 403이고, API가 RFC 6750을 따른다면 WWW-Authenticate 헤더에 error="insufficient_scope"가 포함되어 있는지 단언합니다. 이 테스트는 일부 경로에서는 게이트웨이에서 스코프가 확인되지만 다른 경로에서는 잊히는 고전적인 잘못된 구성 문제를 잡아냅니다. 스코프가 팀에 새로운 개념이라면 OAuth 2.0 스코프 설명에서 스코프를 나누는 방법을 다룹니다.
유효하지 않은 클라이언트: 깔끔한 토큰 엔드포인트 오류 예상
잘못된 client_secret으로 https://auth.example.com/oauth/token에 직접 요청을 보냅니다. RFC 6749 섹션 5.2에 따르면, 서버는 400(또는 클라이언트 인증 실패의 경우 401)과 함께 "error": "invalid_client"를 포함하는 JSON 본문을 반환해야 합니다. 둘 다 단언합니다. 권한 부여 서버도 API이며, 그 오류 계약은 여러분의 서비스 표면의 일부입니다.
테스트 시나리오에서 토큰 응답에 대한 단언
토큰 엔드포인트는 유효하지 않은 클라이언트 경우를 넘어선 자체적인 검증이 필요합니다. 테스트 시나리오에 토큰 엔드포인트를 직접 호출하는 단계를 추가하고, 응답에 대한 단언을 첨부하십시오:
access_token이 존재하고 비어 있지 않음token_type이bearer와 같음 (사양에 따라 대소문자 구분 없음)expires_in이 0보다 크고 정책 내에 있음 (예: 3600을 넘지 않음)scope가 요청된 내용과 일치함, 서버가 부여를 묵묵히 축소하는 경우를 잡아냄
Apidog의 테스트 시나리오에서는 이러한 단언을 응답 JSON에 대한 시각적 단언으로 추가할 수 있으며, 스크립팅이 필요하지 않습니다. 또한 관리되는 인증을 사용하는 대신 원시 핸드셰이크를 테스트하고 싶을 때 access_token을 변수로 추출하여 다음 단계에 사용할 수 있습니다. 시나리오를 CI 실행에 연결하면 오작동하는 권한 부여 서버가 프로덕션에서 미스터리 401로 나타나는 대신 빌드를 실패시킵니다.
전체 흐름은 다음과 같습니다: 해피 경로를 위한 폴더 수준 OAuth 2.0 구성, 401 및 403 경우를 위한 요청별 재정의, 그리고 토큰 엔드포인트의 계약을 테스트하는 하나의 시나리오. 이는 PKCE를 사용한 권한 부여 코드를 통한 사용자 컨텍스트 API와 클라이언트 자격 증명을 통한 서비스 간 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 인증 테스트 가이드는 토큰 자체의 유효성 검사에 대해 자세히 설명합니다.