Blog

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

Apidog에서 클라이언트 인증서(mTLS)가 필요한 API를 테스트하는 방법을 알아보세요: 호스트별로 클라이언트 인증서와 키를 추가하고, CA 인증서를 첨부한 다음, 인증된 요청을 전송하세요.

INEZA Felin-Michel

INEZA Felin-Michel

16 July 2026

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

Apidog 엔터프라이즈

온프레미스 배포

SSO & RBAC

SOC 2 준수

Apidog Enterprise 살펴보기

파트너 API를 호출하고, 유효한 토큰으로 잘 구성된 요청을 보내더라도 TLS 핸드셰이크 실패가 발생할 수 있습니다. 엔드포인트는 API 키를 요구하는 것이 아닙니다. HTTP 요청이 머신을 떠나기도 전에 클라이언트에게 인증서로 신원을 증명하라고 요구하는 것입니다. 이것이 상호 TLS(Mutual TLS)이며, 테스트 도구에서 이를 구성해 본 적이 없다면 통합 작업이 하루 종일 지연될 수 있습니다.

이 가이드는 Apidog에서 클라이언트 인증서 및 CA 인증서를 설정하는 방법을 안내하여 핸드셰이크 문제 없이 mTLS 보호 API를 테스트할 수 있도록 합니다. 특정 호스트에 대한 클라이언트 인증서와 키를 추가하고, 자체 서명된 루트로 인한 오류가 발생하지 않도록 CA 인증서를 첨부한 다음, Apidog가 자동으로 서명하는 인증된 요청을 보낼 것입니다. 인증서 오류가 처음이라면, 이 가이드와 함께 SSL 인증서 확인에 대한 기본 지식을 읽어볼 가치가 있습니다. 프로토콜 자체에 대해서는 MDN TLS 참조가 훌륭하고 공급업체 중립적인 설명서입니다.

button

mTLS(상호 TLS)란 무엇이며 일부 API에서 이를 요구하는 이유

일반 HTTPS는 단방향 신뢰입니다. 서버는 인증서를 제시하고, 클라이언트는 이를 확인하며, 연결은 암호화됩니다. 서버는 사용자가 누구인지에 대한 암호화된 증거를 가지고 있지 않으며, 이를 위해 요청 내의 토큰이나 API 키에 의존합니다.

상호 TLS는 신뢰를 양방향으로 만듭니다. 서버는 여전히 자신의 인증서를 제시하지만, 클라이언트에게도 인증서를 제시하도록 요청합니다. 서버가 신뢰하는 인증 기관에서 서명하지 않은 인증서라면 핸드셰이크는 실패하고 연결은 열리지 않습니다. 요청 본문, 헤더 등 어떤 것도 통과할 수 없습니다.

유출된 베어러 토큰이 허용 가능한 실패 모드가 아닌 다음과 같은 경우에 상호 TLS(mTLS) 인증을 접하게 될 것입니다.

OAuth도 사용되는 경우, 이 둘은 깔끔하게 결합됩니다. RFC 8705는 상호 TLS가 OAuth 토큰을 클라이언트 인증서에 어떻게 바인딩하는지 공식화합니다. 인증서는 요청의 애플리케이션 계층 인증과는 별개인 네트워크 계층 자격 증명입니다. 이 구분은 Apidog에서 중요하며, 사람들이 가장 자주 혼란스러워하는 부분입니다. 인증서는 mTLS를 처리합니다. 인증(Authorization) 탭은 API 키, 베어러 토큰, OAuth 및 기본 인증을 처리합니다. 종종 두 가지 모두 필요하지만, 서로 다른 곳에서 구성합니다.

Apidog가 호스트별로 인증서 범위를 지정하는 방법

Apidog는 CA 인증서와 클라이언트 인증서 모두를 처리하며, 요청별이 아닌 전역적으로 구성합니다. 인증서를 한 번 설정하고 호스트에 연결하면, Apidog는 해당 호스트와 일치하는 모든 HTTPS 요청에 자동으로 첨부합니다. 기억해야 할 요청별 토글이나 붙여넣을 헤더는 없습니다.

두 가지 인증서 유형은 두 가지 다른 작업을 수행합니다.

범위 지정 키는 호스트입니다. 모든 클라이언트 인증서는 도메인에 바인딩되며, Apidog는 나가는 요청의 호스트를 해당 바인딩과 일치시킵니다. 호스트를 올바르게 설정하면 모든 것이 자동으로 처리됩니다. 잘못 설정하면 Apidog는 일치하는 항목을 찾지 못했기 때문에 아무것도 조용히 보내지 않습니다.

mTLS API를 위한 클라이언트 인증서 설정

시나리오는 다음과 같습니다. 결제 파트너인 partner-api.acmebank.com이 온보딩 중에 클라이언트 인증서와 개인 키를 발급했습니다. 해당 API는 HTTPS 전용이며, 해당 인증서를 제시할 수 없는 모든 클라이언트를 거부합니다. GET /v1/settlements를 호출하고 응답을 확인하고자 합니다.

1단계: 인증서 설정 열기

오른쪽 상단의 설정 아이콘을 사용하여 Apidog 설정을 열고, **인증서** 탭으로 이동합니다. 이곳은 두 가지 인증서 유형이 모두 있는 곳입니다. 여기 있는 것은 단일 요청에 묶여 있지 않으며, 호스트 일치를 기반으로 모든 요청에 적용됩니다.

2단계: 클라이언트 인증서 추가

**클라이언트 인증서** 아래에서 **인증서 추가**를 선택합니다. 호스트 바인딩 및 인증서 파일에 대한 양식이 열립니다.

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

partner-api.acmebank.com

https://는 생략합니다. 이 필드는 순수 도메인을 받습니다. 여러 하위 도메인을 하나의 인증서로 처리해야 하는 경우, 호스트 필드는 패턴 매칭을 지원합니다. *.acmebank.com을 입력하면 acmebank.com 아래의 모든 하위 도메인에 동일한 클라이언트 인증서를 사용하는데, 이는 파트너가 동일하게 발급된 인증서로 partner-api, sandbox-api, settlements-api를 실행할 때 유용합니다.

사용자 지정 포트는 선택 사항입니다. 비워두면 Apidog는 표준 HTTPS 포트인 443으로 기본 설정됩니다. mTLS 엔드포인트가 8443과 같은 다른 포트에서 수신하는 경우에만 포트를 설정하십시오.

3단계: 인증서 파일 선택

Apidog는 클라이언트 인증서에 대해 두 가지 파일 레이아웃을 허용합니다. 파트너가 제공한 파일 유형을 선택하십시오.

인증서가 암호와 함께 생성되었다면 **암호** 필드에 입력하십시오. 선택 사항이므로 키가 암호로 보호되지 않은 경우 비워두십시오. 은행의 일반적인 온보딩 번들은 .crt 및 .key 쌍으로 제공되며, 때로는 키에 암호가 있을 수도 있습니다.

4단계: 저장하기

**추가**를 선택하여 클라이언트 인증서를 저장합니다. 이제 partner-api.acmebank.com에 바인딩된 상태로 목록에 나타납니다. 이 시점부터 요청당 다시 건드릴 필요가 없습니다.

5단계: 인증된 요청 보내기

호스트에 요청을 생성하고 보냅니다.

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

Apidog는 호스트를 일치시키고, TLS 핸드셰이크 중에 클라이언트 인증서를 첨부하며, 요청이 나가기 전에 상호 TLS 인증을 완료합니다. 파트너가 OAuth도 요구하는 경우, 해당 베어러 토큰은 평소와 같이 요청에 포함됩니다. 인증서는 머신을 증명하고, 토큰은 호출자를 증명합니다. 성공적인 응답은 다음과 같을 수 있습니다.

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

수동적인 요청별 단계가 이 작업을 수행한 것이 아닙니다. 호스트 일치가 그렇게 한 것입니다.

내부 또는 자체 서명된 루트를 위한 CA 인증서 추가

클라이언트 인증서는 이야기의 절반에 불과합니다. 나머지 절반은 서버의 자체 인증서가 머신이 신뢰하지 않는 기관(예: 개인 루트 CA를 사용하는 내부 서비스 및 스테이징 환경)에 의해 서명될 때 나타납니다.

이런 일이 발생하면 mTLS가 작동할 기회도 얻기 전에 SSL Error: Self signed certificate와 같은 메시지와 함께 요청이 실패합니다. 해결책은 Apidog에 CA를 제공하여 해당 루트를 신뢰하도록 하는 것입니다.

동일한 **인증서** 탭에서 **CA 인증서** 옆의 토글을 켜고 PEM 파일을 선택합니다. CA 인증서는 PEM 형식을 사용하며, 단일 PEM 파일에 여러 CA 인증서가 포함될 수 있으므로, 내부 루트 및 중간 인증서의 전체 체인을 하나의 파일로 묶을 수 있습니다.

-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQG...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIBAgIQeM8V5x8B3QksZ4 b2VqkJTANBgkqhkiG9w0BAQ...
-----END CERTIFICATE-----

CA가 신뢰되면 Apidog는 해당 CA에 의해 서명된 엔드포인트를 거부하지 않습니다. 신뢰할 수 있는 CA와 클라이언트 인증서를 함께 사용하여 개인 루트를 사용하는 내부 mTLS 서비스를 종단 간 테스트할 수 있습니다. CA는 서버를 신뢰하게 하고, 클라이언트 인증서는 서버가 사용자를 신뢰하게 합니다.

고급 팁 및 일반적인 변형

기본적인 설정이 끝나면 시간을 절약할 수 있는 몇 가지 사항이 있습니다.

Apidog CLI로 워크플로우 자동화

mTLS 요청을 수동으로 통과시킨 후, 저장된 테스트 시나리오에 통합하고 Apidog 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

apidog run 명령은 클라이언트 인증서 구성을 직접 지원하므로, mTLS는 GUI에서 파이프라인으로 전환되어도 유지됩니다. 단일 인증서의 경우 --ssl-client-cert (PEM 인증서), --ssl-client-key (개인 키)를 전달하고, 키에 암호가 있는 경우 --ssl-client-passphrase를 전달합니다. 추가 신뢰할 수 있는 CA에 --ssl-extra-ca-certs를 지정하거나, URL 패턴으로 인증서를 호스트에 일치시킬 때는 설정 파일과 함께 --ssl-client-cert-list를 사용하십시오. 리포터는 -r로 설정됩니다 (예: -r html,cli). 이 명령을 작업에 연결하면 인증서로 보호되는 API가 푸시할 때마다 테스트됩니다. CI/CD의 Apidog CLI 가이드는 파이프라인 내에서 실행하는 방법을 다룹니다.

자주 묻는 질문

클라이언트 인증서와 CA 인증서 둘 다 필요한가요, 아니면 하나만 필요한가요?

엔드포인트에 따라 다릅니다. 클라이언트 인증서는 신원을 증명하므로, 서버가 상호 TLS를 요구할 때마다 필요합니다. CA 인증서는 서버 자체 인증서가 내부 루트 CA와 같이 머신이 이미 신뢰하지 않는 기관에 의해 서명된 경우에만 필요합니다. 신뢰할 수 있는 공용 CA의 공개 파트너 API는 클라이언트 인증서만 필요하며, 개인 루트의 내부 mTLS 서비스는 일반적으로 둘 다 필요합니다.

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

거의 항상 호스트 불일치 또는 일반 HTTP 대상 때문입니다. **호스트** 필드에 https:// 접두사 없이 정확한 도메인이 포함되어 있는지, 포트가 일치하는지(기본값 443이므로 엔드포인트가 다른 곳에서 수신하는 경우 사용자 지정 포트 설정), 그리고 요청 URL이 HTTPS인지 확인하십시오. Apidog는 HTTP 요청에 인증서를 첨부하지 않습니다.

API 키와 베어러 토큰은 인증서에 없으면 어디에 입력하나요?

요청 또는 폴더의 **권한 부여** 탭에 있습니다. 이는 인증서 설정과는 별개입니다. 인증서는 TLS 계층 신원을 처리하고, 권한 부여는 요청 계층에서 API 키, 베어러 토큰, OAuth 및 기본 인증을 처리합니다. 보안 체계 가이드에서 모든 인증 유형에 대한 자세한 내용을 찾을 수 있으며, 폴더 또는 컬렉션 수준에서 한 번 인증을 설정하여 모든 요청이 이를 상속받도록 할 수 있습니다.

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

예. 호스트 필드는 패턴 매칭을 지원합니다. *.example.com을 입력하면 example.com의 모든 하위 도메인에 동일한 클라이언트 인증서가 적용됩니다. 이는 파트너가 여러 API 하위 도메인을 위해 발급한 와일드카드 범위 인증서를 깔끔하게 재사용하는 방법입니다.

인증서가 추가된 후 어떻게 업데이트하나요?

인증서는 그 자리에서 편집할 수 없습니다. 삭제 아이콘으로 기존 인증서를 제거한 다음, 수정되거나 갱신된 버전을 다시 추가하십시오. 인증서 교체를 위해 이 점을 명심하고, 테스트 설정을 구성하는 동안 Apidog에서 전역 매개변수 설정은 요청 전반에 걸쳐 환경 값을 깔끔하게 유지하는 데 좋습니다.

마무리

mTLS로 보호되는 API를 테스트하는 것은 Apidog에서 세 가지 작업으로 요약됩니다. 올바른 호스트에 클라이언트 인증서를 바인딩하고, 서버가 개인 루트를 사용하는 경우 CA 인증서를 첨부하며, 호스트 일치 기능을 통해 모든 HTTPS 요청을 자동으로 서명하도록 하는 것입니다. 인증서와 권한 부여를 별도의 영역으로 유지하면 핸드셰이크가 더 이상 미스터리가 아닐 것입니다.

Apidog를 다운로드하여 따라 해보고, 파트너의 인증서를 추가하고, 첫 번째 인증된 요청을 보내보세요. 무료로 사용해 볼 수 있으며 신용카드 정보는 필요 없습니다.

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드