API Management에서 클라이언트 인증서 인증을 사용하여 API를 보호하는 방법

아티클
10/30/2024

적용 대상: 모든 API Management 계층

API Management는 클라이언트 인증서 및 상호 TLS 인증을 사용하여 API(즉, API Management에 대한 클라이언트)에 대한 액세스를 보호하는 기능을 제공합니다. 연결 클라이언트가 제공한 인증서의 유효성을 검사하고 정책 식을 사용하여 원하는 값에 대한 인증서 속성을 확인할 수 있습니다.

클라이언트 인증서를 사용하여 API의 백 엔드 서비스(즉, 백 엔드에 대한 API Management)에 대한 액세스를 보호하는 방법에 대한 자세한 내용은 클라이언트 인증서 인증을 사용하여 백 엔드 서비스를 보호하는 방법을 참조하세요.

API 인증의 개념적 개요는 API Management의 API에 대한 인증 및 권한 부여를 참조하세요.

인증서 옵션

인증서 유효성 검사를 위해 API Management는 API Management 인스턴스에서 관리되는 인증서의 유효성을 검사할 수 있습니다. API Management를 사용하여 클라이언트 인증서를 관리하도록 선택한 경우 다음 옵션이 있습니다.

Azure Key Vault에서 관리되는 인증서 참조
API Management에 직접 인증서 파일 추가

API Management 보안을 높이기 위해 키 자격 증명 모음 인증서를 사용하는 것이 좋습니다.

키 자격 증명 모음에 저장된 인증서는 서비스에서 재사용할 수 있습니다.
키 자격 증명 모음에 저장된 인증서에 세분화된 액세스 정책을 적용할 수 있습니다.
키 자격 증명 모음에서 업데이트한 인증서는 API Management에서 자동으로 회전됩니다. 키 자격 증명 모음에서 업데이트 후 API Management에 있는 인증서는 4시간 이내에 업데이트됩니다. Azure Portal 또는 Management REST API를 사용하여 인증서를 수동으로 새로 고칠 수도 있습니다.

필수 조건

아직 API Management 서비스 인스턴스를 만들지 않은 경우 API Management 서비스 인스턴스 만들기를 참조하세요.
Azure Key Vault에서 관리를 위해 인증서 및 암호에 액세스하거나 API Management 서비스에 업로드해야 합니다. 인증서는 CER 또는 PFX 형식이어야 합니다. 자체 서명된 인증서도 사용할 수 있습니다.

자체 서명된 인증서를 사용하는 경우 API Management 인스턴스에 신뢰할 수 있는 루트 및 중간 CA 인증서도 설치합니다.

참고 항목

인증서 유효성 검사를 위한 CA 인증서는 소비 계층에서 지원되지 않습니다.

키 자격 증명 모음 통합을 위한 사전 요구 사항

참고 항목

현재 이 기능은 작업 영역에서 사용할 수 없습니다.

아직 키 자격 증명 모음이 없으면 새로 만듭니다. 키 자격 증명 모음을 만드는 단계는 빠른 시작: Azure Portal을 사용하여 키 자격 증명 모음 만들기를 참조하세요.

Key Vault에 인증서를 만들거나 가져오려면 빠른 시작: Azure Portal을 사용하여 Azure Key Vault에서 인증서 설정 및 검색을 참조하세요.
API Management 인스턴스에서 시스템 또는 사용자가 할당한 관리 ID를 사용하도록 설정합니다.

키 자격 증명 모음에 대한 액세스 구성

포털에서 키 자격 증명 모음으로 이동합니다.
왼쪽 메뉴에서 액세스 구성을 선택하고 구성된 권한 모델을 기록해 둡니다.
권한 모델에 따라 API Management 관리 ID에 대해 키 자격 증명 모음 액세스 정책 또는 Azure RBAC 액세스를 구성합니다.

키 자격 증명 모음 액세스 정책을 추가하려면:
1. 왼쪽 메뉴에서 액세스 정책을 선택합니다.
2. 액세스 정책 페이지에서 + 만들기를 선택합니다.
3. 권한 탭의 비밀 권한에서 가져오기 및 나열을 선택한 후 다음을 선택합니다.
4. 보안 주체 탭에서 보안 주체를 선택하고, 관리 ID의 리소스 이름을 검색한 후, 다음을 선택합니다. 시스템이 할당한 ID를 사용하는 경우 보안 주체는 API Management 인스턴스의 이름입니다.
5. 다음을 다시 선택합니다. 검토 + 만들기 탭에서 만들기를 선택합니다.
Azure RBAC 액세스를 구성하려면:
1. 왼쪽 메뉴에서 액세스 제어(IAM)를 선택합니다.
2. 액세스 제어(IAM) 페이지에서 역할 할당 추가를 선택합니다.
3. 역할 탭에서 Key Vault 인증서 사용자를 선택합니다.
4. 멤버 탭에서 관리 ID>+ 멤버 선택을 선택합니다.
5. 관리 ID 선택 페이지에서 시스템이 할당한 관리 ID 또는 API Management 인스턴스와 연결된 사용자가 할당한 관리 ID를 선택한 다음, 선택을 선택합니다.
6. 검토 + 할당을 선택합니다.

Key Vault 방화벽에 대한 요구 사항

키 자격 증명 모음에서 Key Vault 방화벽을 사용하도록 설정한 경우 추가 요구 사항은 다음과 같습니다.

키 자격 증명 모음에 액세스하려면 API Management 인스턴스의 시스템 할당 관리 ID를 사용해야 합니다.
Key Vault 방화벽에서 신뢰할 수 있는 Microsoft 서비스가 이 방화벽을 우회하도록 허용 옵션을 사용하도록 설정합니다.
Azure API Management에 추가할 인증서 또는 비밀을 선택하는 동안 로컬 클라이언트 IP 주소가 키 자격 증명 모음에 일시적으로 액세스할 수 있는지 확인합니다. 자세한 내용은 Azure Key Vault 네트워킹 설정 구성을 참조하세요.

구성을 완료한 후 키 자격 증명 모음 방화벽에서 클라이언트 주소를 차단할 수 있습니다.

가상 네트워크 요구 사항

API Management 인스턴스가 가상 네트워크에 배포된 경우 다음 네트워크 설정도 구성합니다.

API Management 서브넷에서 Azure Key Vault에 대한 서비스 엔드포인트를 사용하도록 설정합니다.
AzureKeyVault 및 AzureActiveDirectory 서비스 태그에 대한 아웃바운드 트래픽을 허용하도록 NSG(네트워크 보안 그룹) 규칙을 구성합니다.

자세한 내용은 VNet에서 Azure API Management를 설정할 때 네트워크 구성을 참조하세요.

키 자격 증명 모음 인증서 추가

키 자격 증명 모음 통합을 위한 필수 구성 요소를 참조하세요.

Important

API Management 인스턴스에 키 자격 증명 모음 인증서를 추가할 때 키 자격 증명 모음의 비밀을 나열할 수 있는 권한이 있어야 합니다.

주의

API Management에서 키 자격 증명 모음 인증서를 사용하는 경우 키 자격 증명 모음 액세스에 사용하는 인증서, 키 자격 증명 모음 또는 관리 ID를 삭제하지 않도록 주의합니다.

API Management에 키 자격 증명 모음 인증서를 추가하려면 다음을 수행합니다.

Azure Portal에서 API Management 인스턴스로 이동합니다.
보안에서 인증서를 선택합니다.
인증서>+ 추가를 선택합니다.
ID에서 원하는 이름을 입력합니다.
인증서에서 키 자격 증명 모음을 선택합니다.
키 자격 증명 모음 인증서의 식별자를 입력하거나, 키 자격 증명 모음에서 인증서를 선택하려면 선택을 선택합니다.

Important

키 자격 증명 모음 인증서 식별자를 직접 입력할 때 버전 정보를 포함해서는 안 됩니다. 이를 포함할 경우 키 자격 증명 모음을 업데이트한 후에 API Management에서 인증서가 자동으로 회전되지 않습니다.
클라이언트 ID에서 시스템 또는 기존 사용자가 할당한 관리 ID를 선택합니다. API Management 서비스에서 관리 ID를 추가 또는 수정하는 방법에 대해 알아봅니다.

참고 항목

ID에는 키 자격 증명 모음에서 인증서를 가져오고 나열할 수 있는 권한이 필요합니다. 키 자격 증명 모음에 대한 액세스를 아직 구성하지 않은 경우 API Management는 필수적인 권한을 통해 ID를 자동으로 구성할 수 있도록 메시지를 표시합니다.
추가를 선택합니다.
저장을 선택합니다.

인증서 업로드

API Management에 클라이언트 인증서를 업로드하려면 다음을 수행합니다.

Azure Portal에서 API Management 인스턴스로 이동합니다.
보안에서 인증서를 선택합니다.
인증서>+ 추가를 선택합니다.
ID에서 원하는 이름을 입력합니다.
인증서에서 사용자 지정을 선택합니다.
인증서 .pfx 파일을 찾아 선택하고 암호를 입력합니다.
추가를 선택합니다.
저장을 선택합니다.

참고 항목

인증서를 사용하여 API Management로 클라이언트를 인증하려는 경우 CER 파일을 업로드할 수 있습니다.

API Management 인스턴스를 사용하도록 설정하여 클라이언트 인증서 수신 및 확인

개발자, 기본, 표준 또는 프리미엄 계층

개발자, 기본, 표준 또는 프리미엄 계층에서 HTTP/2를 통해 클라이언트 인증서를 수신하고 확인하려면 아래와 같이 사용자 지정 도메인 블레이드에서 클라이언트 인증서 협상 설정을 켜야 합니다.

클라이언트 인증서 협상

소비, 기본 v2, 표준 v2 또는 프리미엄 v2 계층

소비, 기본 v2, 표준 v2 또는 프리미엄 v2 계층에서 클라이언트 인증서를 수신하고 확인하려면 아래와 같이 사용자 지정 도메인 블레이드에서 클라이언트 인증서 요청 설정을 사용하도록 설정해야 합니다.

클라이언트 인증서 요청

클라이언트 인증서의 유효성을 검사하는 정책

validate-client-certificate 정책을 사용하여 API Management 인스턴스에서 호스트되는 API에 액세스하는 데 사용되는 클라이언트 인증서의 하나 이상의 특성에 대한 유효성을 검사합니다.

인증서 발급자, 주체, 지문, 인증서가 온라인 해지 목록에 대한 인증서의 유효성 검사 여부 등을 비롯한 하나 이상의 특성에 대한 유효성을 검사하도록 정책을 구성합니다.

컨텍스트 변수를 사용한 인증서 유효성 검사

context 변수를 사용하여 클라이언트 인증서를 확인하는 정책 식을 만들 수도 있습니다. 다음 섹션의 예제에서는 context.Request.Certificate 속성 및 기타 context 속성을 사용하는 식을 보여줍니다.

참고 항목

API Management 게이트웨이 엔드포인트가 Application Gateway를 통해 노출될 때 상호 인증서 인증이 제대로 작동하지 않을 수 있습니다. Application Gateway가 계층 7 부하 분산 장치로 작동하여 백 엔드 API Management 서비스와 고유한 SSL 연결을 설정하기 때문입니다. 따라서 초기 HTTP 요청에서 클라이언트가 연결한 인증서는 APIM으로 전달되지 않습니다. 그러나 해결 방법으로 서버 변수 옵션을 사용하여 인증서를 전송할 수 있습니다. 자세한 지침은 상호 인증 서버 변수를 참조하세요.

Important

2021년 5월부터 context.Request.Certificate 속성은 API Management 인스턴스의 hostnameConfiguration이 negotiateClientCertificate 속성을 True로 설정한 경우에만 인증서를 요청합니다. 기본적으로 negotiateClientCertificate는 false로 설정됩니다.
클라이언트에서 TLS 재협상이 사용하지 않도록 설정된 경우 context.Request.Certificate 속성을 사용하여 인증서를 요청할 때 TLS 오류가 표시될 수 있습니다. 이 경우 클라이언트에서 TLS 재협상 설정을 사용하도록 설정합니다.
인증 재협상은 API Management v2 계층에서 지원되지 않습니다.

발급자 및 주체 확인

클라이언트 인증서의 발급자 및 주체를 확인하도록 아래 정책을 구성할 수 있습니다.

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Issuer != "trusted-issuer" || context.Request.Certificate.SubjectName.Name != "expected-subject-name")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

참고 항목

인증서 해지 목록 확인을 사용하지 않도록 설정하려면 context.Request.Certificate.Verify() 대신 context.Request.Certificate.VerifyNoRevocation()을 사용합니다. 클라이언트 인증서가 자체 서명된 경우 루트(또는 중간) CA 인증서를 API Management로 업로드해야 context.Request.Certificate.Verify() 및 context.Request.Certificate.VerifyNoRevocation()이 작동합니다.

지문 확인

클라이언트 인증서의 지문을 확인하도록 아래 정책을 구성할 수 있습니다.

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Thumbprint != "DESIRED-THUMBPRINT-IN-UPPER-CASE")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

참고 항목

API Management에 업로드된 인증서에 대해 지문 확인

다음 예제에서는 API Management에 업로드된 인증서에 대해 클라이언트 인증서의 지문을 확인하는 방법을 보여 줍니다.

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify()  || !context.Deployment.Certificates.Any(c => c.Value.Thumbprint == context.Request.Certificate.Thumbprint))" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

참고 항목

팁

이 문서에서 설명하는 클라이언트 인증서 교착 상태 문제는 요청이 중지하거나, 요청 시간 초과로 인해 403 Forbidden 상태 코드가 발생하거나, context.Request.Certificate가 null이 되는 등 다양한 방식으로 나타날 수 있습니다. 이 문제는 일반적으로 콘텐츠 길이가 약 60KB 이상인 POST 및 PUT 요청에 영향을 줍니다. 이 문제가 발생하지 않도록 하려면 이 문서의 첫 번째 이미지에 표시된 것처럼 '사용자 지정 도메인' 블레이드에서 원하는 호스트 이름에 대해 '클라이언트 인증서 협상' 설정을 켭니다. 소비 계층에서는 이 기능을 사용할 수 없습니다.

다음을 통해 공유

API Management에서 클라이언트 인증서 인증을 사용하여 API를 보호하는 방법

인증서 옵션

필수 조건

키 자격 증명 모음 통합을 위한 사전 요구 사항

키 자격 증명 모음에 대한 액세스 구성

Key Vault 방화벽에 대한 요구 사항

가상 네트워크 요구 사항

키 자격 증명 모음 인증서 추가

인증서 업로드

API Management 인스턴스를 사용하도록 설정하여 클라이언트 인증서 수신 및 확인

개발자, 기본, 표준 또는 프리미엄 계층

소비, 기본 v2, 표준 v2 또는 프리미엄 v2 계층

클라이언트 인증서의 유효성을 검사하는 정책

컨텍스트 변수를 사용한 인증서 유효성 검사

발급자 및 주체 확인

지문 확인

API Management에 업로드된 인증서에 대해 지문 확인

다음 단계

피드백

추가 리소스