Rihpig

Posted on Jul 16 • Originally published at apidog.com

Apidog에서 클라이언트 인증서(mTLS)가 필요한 API 테스트 방법

파트너 API에 유효한 토큰과 올바른 요청을 보내도 TLS 핸드셰이크가 실패할 수 있습니다. 이 경우 엔드포인트는 API 키만 요구하는 것이 아니라, HTTP 요청이 네트워크를 떠나기 전에 클라이언트 인증서로 호출자의 신원을 증명하도록 요구합니다. 이것이 상호 TLS(mTLS)이며, 테스트 도구에서 인증서를 구성하지 않으면 통합 작업이 지연될 수 있습니다.

지금 Apidog를 사용해 보세요

이 가이드에서는 Apidog에서 클라이언트 인증서와 CA 인증서를 설정해 mTLS 보호 API를 테스트하는 방법을 설명합니다. 특정 호스트에 클라이언트 인증서와 키를 연결하고, 자체 서명 루트로 인한 검증 오류가 발생하면 CA 인증서를 추가한 뒤, Apidog가 해당 호스트의 HTTPS 요청에 인증서를 자동으로 적용하게 만듭니다.

인증서 오류가 익숙하지 않다면 먼저 SSL 인증서 확인을 확인하세요. TLS 프로토콜 자체는 MDN TLS 참조를 참고하면 됩니다.

mTLS(상호 TLS)란 무엇이며 왜 필요한가?

일반 HTTPS는 서버만 인증서를 제시하는 단방향 신뢰 모델입니다.

서버가 인증서를 제시합니다.
클라이언트가 인증서를 검증합니다.
암호화된 연결을 수립합니다.
API 키, 베어러 토큰 또는 OAuth 토큰으로 요청자를 인증합니다.

mTLS에서는 서버뿐 아니라 클라이언트도 인증서를 제시합니다. 서버가 신뢰하는 CA가 서명한 클라이언트 인증서가 아니면 TLS 핸드셰이크가 실패하며, 헤더나 요청 본문은 서버까지 도달하지 않습니다.

mTLS는 주로 다음 환경에서 사용됩니다.

은행 및 결제 API: OAuth와 함께 조직별 클라이언트 인증서를 요구할 수 있습니다. Stripe 문서는 민감한 금융 엔드포인트에서 사용하는 계층형 자격 증명 모델을 다룹니다.
내부 서비스 간 통신: 제로 트러스트 환경에서 네트워크 위치 대신 인증서로 서비스 신원을 확인합니다.
B2B 파트너 API: 파트너 온보딩 과정에서 인증서를 발급해 등록된 클라이언트만 API에 접근하도록 제한합니다.

OAuth와 mTLS를 함께 사용할 수도 있습니다. RFC 8705는 OAuth 토큰을 클라이언트 인증서에 바인딩하는 방식을 정의합니다.

핵심은 역할을 분리하는 것입니다.

구성 요소	역할	Apidog 설정 위치
클라이언트 인증서	TLS 계층에서 클라이언트 신원 증명	인증서 탭
CA 인증서	서버 인증서의 서명 체인 신뢰	인증서 탭
API 키, Bearer 토큰, OAuth	HTTP 요청 계층 인증 및 권한 부여	권한 부여 탭

인증(Authorization) 설정은 mTLS 인증서를 대체하지 않습니다. 파트너가 둘 다 요구하면 각각 별도 위치에서 구성해야 합니다.

Apidog의 호스트별 인증서 적용 방식

Apidog의 CA 인증서와 클라이언트 인증서는 개별 요청이 아니라 전역적으로 설정됩니다. 인증서를 특정 호스트에 연결하면 Apidog가 해당 호스트와 일치하는 모든 HTTPS 요청에 자동으로 적용합니다.

두 인증서 유형의 목적은 다릅니다.

클라이언트 인증서: mTLS 핸드셰이크에서 서버에 제시하는 신원 증명입니다.
CA 인증서: Apidog가 기본적으로 신뢰하지 않는 내부 또는 자체 서명 CA를 신뢰하도록 합니다. 이를 설정하면 SSL Error: Self signed certificate 오류를 해결할 수 있습니다.

호스트 매칭이 핵심입니다. 호스트를 올바르게 지정하면 요청마다 인증서를 선택할 필요가 없습니다. 반대로 호스트나 포트가 일치하지 않으면 Apidog는 인증서를 보내지 않습니다.

mTLS API용 클라이언트 인증서 설정

다음 상황을 가정합니다.

API 호스트: partner-api.acmebank.com
엔드포인트: GET /v1/settlements
파트너가 제공한 항목: 클라이언트 인증서와 개인 키
추가 인증: OAuth Bearer 토큰

1. 인증서 설정 열기

Apidog 오른쪽 상단의 설정 아이콘을 선택한 뒤 인증서 탭으로 이동합니다.

이 화면에서 설정하는 인증서는 특정 요청에만 적용되지 않습니다. 이후 요청 URL의 호스트가 등록한 호스트와 일치하면 자동으로 사용됩니다.

2. 클라이언트 인증서 추가

클라이언트 인증서 섹션에서 인증서 추가를 선택합니다.

호스트 필드에는 프로토콜 없이 도메인만 입력합니다.

partner-api.acmebank.com

다음과 같이 https://를 포함하면 안 됩니다.

https://partner-api.acmebank.com

여러 하위 도메인에서 같은 인증서를 사용해야 한다면 와일드카드 패턴을 사용할 수 있습니다.

*.acmebank.com

예를 들어 동일한 인증서가 다음 호스트에 적용될 수 있습니다.

partner-api.acmebank.com
sandbox-api.acmebank.com
settlements-api.acmebank.com

포트는 선택 사항입니다. 비워 두면 기본 HTTPS 포트인 443이 사용됩니다. mTLS 엔드포인트가 8443처럼 다른 포트에서 실행되는 경우에만 해당 포트를 지정하세요.

3. 인증서 파일 선택

Apidog에서는 다음 두 가지 클라이언트 인증서 형식을 사용할 수 있습니다.

CRT + 키 파일: 인증서 파일과 개인 키 파일이 분리된 형식
PFX 파일: 인증서와 개인 키가 하나로 묶인 형식

파트너가 제공한 파일 구조에 맞게 선택합니다.

개인 키가 암호로 보호되어 있다면 암호 필드에 암호를 입력하세요. 암호가 없는 키라면 비워 둡니다.

일반적인 파일 구성은 다음과 같습니다.

client.crt
client.key

또는 다음과 같은 PFX 번들일 수 있습니다.

client.pfx

4. 인증서 저장

추가를 선택해 인증서를 저장합니다.

목록에 partner-api.acmebank.com 호스트와 연결된 인증서가 표시되면 설정이 완료된 것입니다. 이후 이 호스트로 보내는 HTTPS 요청에서는 해당 인증서가 자동으로 사용됩니다.

5. mTLS 요청 보내기

이제 API 요청을 생성합니다.

GET https://partner-api.acmebank.com/v1/settlements
Authorization: Bearer <your_oauth_token>

요청을 보내면 Apidog는 다음 순서로 처리합니다.

요청 URL의 호스트를 확인합니다.
등록된 클라이언트 인증서와 호스트를 매칭합니다.
TLS 핸드셰이크 중 클라이언트 인증서를 제시합니다.
mTLS 핸드셰이크가 성공하면 HTTP 요청을 전송합니다.
OAuth가 필요한 경우 Authorization 헤더의 토큰도 함께 전송합니다.

응답 예시는 다음과 같습니다.

{
  "settlements": [
    {
      "id": "stl_88213",
      "amount": 41200,
      "currency": "USD",
      "status": "cleared",
      "settled_at": "2026-07-14T09:31:00Z"
    }
  ],
  "next_cursor": null
}

이 과정에서 요청별로 인증서를 수동 선택할 필요는 없습니다. 호스트 매칭이 인증서 적용을 처리합니다.

내부 또는 자체 서명 루트용 CA 인증서 추가

클라이언트 인증서를 설정했더라도 서버 인증서가 사설 CA 또는 자체 서명 루트로 발급되었다면 연결은 실패할 수 있습니다.

대표적인 오류는 다음과 같습니다.

SSL Error: Self signed certificate

이 오류는 mTLS 인증 이전에 발생할 수 있습니다. 서버 인증서의 발급자를 신뢰하지 못해 TLS 연결 자체가 시작되지 않기 때문입니다.

해결 방법은 Apidog에 CA 인증서를 추가하는 것입니다.

인증서 탭으로 이동합니다.
CA 인증서 옆의 토글을 활성화합니다.
내부 루트 CA 또는 중간 CA가 포함된 PEM 파일을 선택합니다.

CA 인증서는 PEM 형식을 사용합니다. 하나의 PEM 파일에 루트 CA와 중간 CA를 함께 포함할 수 있습니다.

-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQG...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIBAgIQeM8V5x8B3QksZ4b2VqkJTANBgkqhkiG9w0BAQ...
-----END CERTIFICATE-----

설정 후의 역할은 다음과 같이 구분됩니다.

CA 인증서: Apidog가 서버 인증서를 신뢰하게 합니다.
클라이언트 인증서: 서버가 클라이언트를 신뢰하게 합니다.

내부 mTLS 서비스에서 사설 루트를 사용한다면 일반적으로 두 인증서가 모두 필요합니다.

구현 시 자주 놓치는 사항

하위 도메인은 와일드카드로 묶기

여러 API 하위 도메인에 동일한 인증서를 적용해야 한다면 각각 등록하지 말고 다음처럼 설정합니다.

*.acmebank.com

단, 파트너가 발급한 인증서의 범위가 해당 하위 도메인을 포함하는지 확인해야 합니다.

비표준 포트 확인하기

다음과 같은 내부 게이트웨이는 기본 포트 443이 아닐 수 있습니다.

https://gateway.internal.example:8443
https://gateway.internal.example:9443

Apidog의 인증서 설정에서 포트를 비워 두면 443이 기본값입니다. 실제 요청 포트와 인증서 설정 포트가 다르면 호스트 매칭에 실패해 인증서가 전송되지 않을 수 있습니다.

인증서 수정 대신 삭제 후 재등록하기

추가된 인증서는 그 자리에서 편집할 수 없습니다. 인증서를 갱신했거나 호스트를 잘못 입력했다면 다음 순서로 처리합니다.

기존 인증서를 삭제합니다.
새 인증서 또는 수정한 설정으로 다시 추가합니다.
대상 HTTPS 요청을 다시 실행합니다.

도메인별 인증서는 하나만 유지하기

같은 도메인에 여러 클라이언트 인증서를 등록하면 어떤 인증서를 제시해야 하는지 모호해질 수 있습니다. 호스트당 하나의 인증서 바인딩을 유지하세요.

인증서와 권한 부여를 분리하기

mTLS 설정은 인증서 탭에서 처리합니다.

API 키, Bearer 토큰, OAuth, Basic Auth는 요청 또는 폴더의 권한 부여 탭에서 처리합니다. 권한 부여는 요청, 폴더, 컬렉션 수준에서 설정할 수 있으며 하위 요청이 상속할 수 있습니다.

토큰 기반 인증 설정은 API 게이트웨이 인증을 참고하세요. Windows 중심 환경에서 Kerberos를 사용한다면 Apidog에서 Kerberos 인증 구성도 참고할 수 있습니다.

HTTP에서는 mTLS가 동작하지 않음

클라이언트 인증서는 TLS 핸드셰이크의 일부입니다. 따라서 일반 HTTP 요청에는 적용되지 않습니다.

http://example.com

다음과 같이 HTTPS를 사용해야 합니다.

https://example.com

Apidog CLI로 mTLS 테스트 자동화

GUI에서 mTLS 요청을 검증했다면, 저장된 시나리오를 Apidog CLI로 실행해 CI/CD에 연결할 수 있습니다.

먼저 CLI를 설치하고 인증합니다.

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

저장된 시나리오를 특정 환경에서 실행합니다.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

CLI에서 mTLS 관련 옵션을 사용할 수 있습니다.

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <scenario_id> \
  -e <env_id> \
  --ssl-client-cert <client-cert.pem> \
  --ssl-client-key <client-key.pem> \
  --ssl-client-passphrase <passphrase> \
  --ssl-extra-ca-certs <ca-bundle.pem> \
  -r html,cli

주요 옵션은 다음과 같습니다.

옵션	용도
`--ssl-client-cert`	PEM 클라이언트 인증서 지정
`--ssl-client-key`	개인 키 지정
`--ssl-client-passphrase`	암호화된 개인 키의 암호 지정
`--ssl-extra-ca-certs`	추가로 신뢰할 CA 인증서 지정
`--ssl-client-cert-list`	URL 패턴별 인증서 매칭을 위한 설정 파일 지정
`-r`	리포터 지정, 예: `html,cli`

이 명령을 CI 작업에 추가하면 인증서로 보호된 API를 코드 푸시마다 테스트할 수 있습니다. 자세한 파이프라인 구성은 CI/CD의 Apidog CLI를 참고하세요.

자주 묻는 질문

클라이언트 인증서와 CA 인증서가 모두 필요한가요?

엔드포인트 구성에 따라 다릅니다.

서버가 mTLS를 요구하면 클라이언트 인증서가 필요합니다.
서버 인증서가 Apidog가 기본적으로 신뢰하지 않는 사설 CA나 자체 서명 CA로 발급되었다면 CA 인증서도 필요합니다.
공용 CA가 서명한 파트너 API라면 보통 클라이언트 인증서만 필요합니다.
사설 루트를 사용하는 내부 mTLS 서비스라면 보통 두 인증서가 모두 필요합니다.

Apidog가 클라이언트 인증서를 보내지 않는 이유는 무엇인가요?

다음을 확인하세요.

호스트 필드에 https:// 없이 정확한 도메인을 입력했는지 확인합니다.
요청 URL의 호스트와 인증서에 등록한 호스트가 일치하는지 확인합니다.
비표준 포트를 사용한다면 인증서 설정에도 동일한 포트를 지정했는지 확인합니다.
요청 URL이 https://인지 확인합니다.

Apidog는 HTTP 요청에 클라이언트 인증서를 첨부하지 않습니다.

API 키와 Bearer 토큰은 어디에 설정하나요?

요청 또는 폴더의 권한 부여 탭에서 설정합니다. 인증서 설정과는 별개입니다.

인증서: TLS 계층 신원 증명
권한 부여: API 키, Bearer 토큰, OAuth, Basic Auth

모든 인증 방식은 보안 체계 가이드에서 확인할 수 있습니다.

하나의 인증서로 여러 하위 도메인을 처리할 수 있나요?

가능합니다. 호스트 필드에 와일드카드 패턴을 사용합니다.

*.example.com

이 설정은 example.com의 하위 도메인에 같은 클라이언트 인증서를 적용합니다.

인증서를 갱신하거나 수정하려면 어떻게 하나요?

기존 인증서를 삭제한 뒤 새 파일과 설정으로 다시 추가해야 합니다. 인증서는 추가 후 직접 편집할 수 없습니다.

인증서 교체와 함께 환경값을 관리해야 한다면 Apidog에서 전역 매개변수 설정을 참고하세요.

마무리

Apidog에서 mTLS 보호 API를 테스트하는 절차는 다음 세 단계로 정리할 수 있습니다.

클라이언트 인증서를 올바른 호스트와 포트에 바인딩합니다.
서버가 사설 또는 자체 서명 루트를 사용하면 CA 인증서를 추가합니다.
HTTPS 요청을 보내고 Apidog의 호스트 매칭으로 인증서를 자동 적용합니다.

인증서 설정과 요청 권한 부여를 분리해서 관리하면 mTLS 핸드셰이크 문제를 더 빠르게 진단할 수 있습니다.

Apidog를 다운로드하고 파트너 인증서를 등록한 뒤 첫 mTLS 요청을 실행해 보세요. 무료로 사용해 볼 수 있으며 신용카드 정보는 필요 없습니다.

DEV Community