API Gateway에서 REST API에 대한 상호 TLS 인증을 켜는 방법

상호 TLS 인증에는 클라이언트와 서버 간의 양방향 인증이 필요합니다. 상호 TLS를 사용하는 경우 클라이언트가 API에 액세스하려면 자격 증명을 확인하기 위해 X.509 인증서를 제공해야 합니다. 상호 TLS는 사물 인터넷(IoT) 및 B2B 애플리케이션에 일반적으로 요구됩니다.

API Gateway가 지원하는 다른 권한 부여 및 인증 작업과 함께 상호 TLS를 사용할 수 있습니다. API Gateway는 클라이언트가 제공하는 인증서를 Lambda 권한 부여자와 백엔드 통합에 전달합니다.

상호 TLS의 사전 조건

상호 TLS를 구성하려면 다음이 필요합니다.

사용자 지정 도메인 이름

REST API에 상호 TLS를 활성화하려면 API에 대한 사용자 지정 도메인 이름을 구성해야 합니다. 사용자 지정 도메인 이름에 상호 TLS를 활성화한 다음 클라이언트에 사용자 지정 도메인 이름을 제공할 수 있습니다. 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스하려면 클라이언트가 API 요청에서 신뢰할 수 있는 인증서를 제공해야 합니다. 추가 정보는 API Gateway의 REST API에 대한 사용자 지정 도메인 이름 단원에서 확인할 수 있습니다.

AWS Certificate Manager에서 발급된 인증서 사용

ACM에서 직접 공인 인증서를 요청하거나 공용 인증서 또는 자체 서명된 인증서를 가져올 수 있습니다. ACM에 인증서를 설정하려면 ACM으로 이동하세요. 인증서를 가져오려면 다음 단원을 계속 읽으세요.

가져온 인증서 또는 AWS Private Certificate Authority 인증서 사용

ACM으로 가져온 인증서 또는 AWS Private Certificate Authority에서 가져온 인증서를 상호 TLS와 함께 사용하려면 API Gateway에서 ACM이 발급한 ownershipVerificationCertificate가 필요합니다. 이 소유권 인증서는 도메인 이름을 사용할 수 있는 권한이 있는지 확인하는 데에만 사용됩니다. TLS 핸드셰이크에는 사용되지 않습니다. 아직 ownershipVerificationCertificate가 없으면 https://console.aws.amazon.com/acm/으로 이동하여 하나를 설정합니다.

도메인 이름의 수명 동안 이 인증서를 유효하게 유지해야 합니다. 인증서가 만료되고 자동 갱신이 실패하면 도메인 이름에 대한 모든 업데이트가 잠깁니다. 다른 변경 사항을 적용하기 전에 유효한 ownershipVerificationCertificate를 사용해 ownershipVerificationCertificateArn을 업데이트해야 합니다. ownershipVerificationCertificate는 API Gateway의 다른 상호 TLS 도메인에 대한 서버 인증서로 사용할 수 없습니다. 인증서를 ACM으로 직접 다시 가져오는 경우 발급자는 동일하게 유지해야 합니다.

트러스트 스토어 구성

트러스트 스토어는 파일 확장자가 .pem인 텍스트 파일입니다. 인증 기관으로부터의 신뢰할 수 있는 인증서 목록입니다. 상호 TLS를 사용하려면 API에 액세스하도록 신뢰할 수 있는 X.509 인증서의 트러스트 스토어를 생성합니다.

발급 CA 인증서부터 루트 CA 인증서까지의 전체 신뢰 체인을 트러스트 스토어에 포함시켜야 합니다. API Gateway는 현재 신뢰 체인에 있는 모든 CA에서 발급한 클라이언트 인증서를 수락합니다. 공인 또는 사설 인증 기관의 인증서가 포함될 수 있습니다. 인증서의 체인 길이는 최대 4개가 될 수 있습니다. 자체 서명된 인증서를 제공할 수도 있습니다. 트러스트 스토어에서 지원되는 알고리즘은 다음과 같습니다.

API Gateway에서는 여러 인증서 속성의 유효성을 검사합니다. Lambda 권한 부여자를 사용하여 클라이언트가 API를 호출할 때 인증서가 해지되었는지 확인하는 것과 같은 추가 검사를 수행할 수 있습니다. API Gateway는 다음 속성의 유효성을 검사합니다.

단일 파일의 Amazon S3 버킷에 트러스트 스토어를 업로드합니다.

다음은 .pem 파일의 예입니다.

-----BEGIN CERTIFICATE-----
<Certificate contents>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Certificate contents>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Certificate contents>
-----END CERTIFICATE-----
...

다음 AWS CLI 명령은 Amazon S3 버킷에 certificates.pem을 업로드합니다.

aws s3 cp certificates.pem s3://bucket-name

사용자 지정 도메인 이름에 대한 상호 TLS 구성

REST API에 대한 상호 TLS를 구성하려면 API에 대해 TLS_1_2 보안 정책과 함께 리전 사용자 지정 도메인 이름을 사용해야 합니다. 보안 정책에 대한 자세한 설명은 API Gateway에서 REST API 사용자 지정 도메인에 대한 보안 정책 선택 섹션을 참조하세요.

트러스트 스토어를 Amazon S3에 업로드한 후 상호 TLS를 사용하도록 사용자 지정 도메인 이름을 구성할 수 있습니다. 다음 내용(슬래시 포함)을 터미널에 붙여 넣습니다.

aws apigateway create-domain-name --region us-east-2 \
    --domain-name api.example.com \
    --regional-certificate-arn arn:aws:acm:us-east-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
    --endpoint-configuration types=REGIONAL \
    --security-policy TLS_1_2 \
    --mutual-tls-authentication truststoreUri=s3://bucket-name/key-name

도메인 이름을 생성한 후에는 API 작업에 대한 DNS 레코드와 기본 경로 매핑을 구성해야 합니다. 자세한 내용은 API Gateway에서 리전 사용자 지정 도메인 이름 설정 단원을 참조하십시오.

상호 TLS가 요구되는 사용자 지정 도메인 이름을 사용하여 API 호출

상호 TLS가 활성화된 API를 호출하려면 클라이언트가 API 요청에서 신뢰할 수 있는 인증서를 제공해야 합니다. 클라이언트가 API를 호출하려고 하면 API Gateway는 트러스트 스토어에서 클라이언트 인증서의 발급자를 찾습니다. API Gateway가 요청을 진행하려면 인증서의 발급자 및 루트 CA 인증서까지의 전체 신뢰 체인이 트러스트 스토어에 있어야 합니다.

다음 예제 curl 명령은 요청에 api.example.com,을 포함하여 my-cert.pem에 요청을 보냅니다. my-key.key는 인증서의 프라이빗 키입니다.

curl -v --key ./my-key.key --cert ./my-cert.pem api.example.com

트러스트 스토어가 인증서를 신뢰하는 경우에만 API가 호출됩니다. 다음 조건에서는 API Gateway가 TLS 핸드셰이크에 실패하고 403 상태 코드와 함께 요청을 거부합니다. 인증서가 다음 상태인 경우:

트러스트 스토어 업데이트

트러스트 스토어의 인증서를 업데이트하려면 새 인증서 번들을 Amazon S3에 업로드합니다. 그런 다음 업데이트된 인증서를 사용하도록 사용자 지정 도메인 이름을 업데이트할 수 있습니다.

Amazon S3 버전 관리를 사용하여 트러스트 스토어의 여러 버전을 유지 관리합니다. 새 트러스트 스토어 버전을 사용하도록 사용자 지정 도메인 이름을 업데이트하면 인증서가 유효하지 않을 경우 API Gateway에서 경고가 반환됩니다.

API Gateway는 도메인 이름을 업데이트할 때만 인증서 경고를 생성합니다. API Gateway는 이전에 업로드한 인증서 만료를 알려주지 않습니다.

다음 AWS CLI 명령은 새 트러스트 스토어 버전을 사용하도록 사용자 지정 도메인 이름을 업데이트합니다.

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreVersion',value='abcdef123'

상호 TLS 비활성화

사용자 지정 도메인 이름에 상호 TLS를 사용하지 않도록 설정하려면 다음 명령과 같이 사용자 지정 도메인 이름에서 해당 트러스트 스토어를 제거합니다.

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreUri',value=''

REST API의 상호 TLS 문제 해결

아래에서는 상호 TLS를 켤 때 발생할 수 있는 오류 및 문제를 해결하는 방법을 조언합니다.

인증서 경고 문제 해결

상호 TLS가 포함된 사용자 지정 도메인 이름을 만들 때 트러스트 스토어의 인증서가 유효하지 않을 경우 API Gateway 에서 경고가 반환됩니다. 이는 새 트러스트 스토어를 사용하도록 사용자 지정 도메인 이름을 업데이트할 때에도 발생할 수 있습니다. 이러한 경고는 경고를 유발한 인증서와 인증서 주체에 문제가 있음을 나타냅니다. API에 대해 상호 TLS가 계속 활성화되어 있지만 일부 클라이언트는 API에 액세스하지 못할 수 있습니다.

경고를 유발한 인증서를 식별하려면 트러스트 스토어에서 인증서를 디코딩해야 합니다. openssl 같은 도구를 사용하여 인증서를 디코딩하고 해당 주체를 식별할 수 있습니다.

다음 명령은 주체를 포함하여 인증서의 내용을 표시합니다.

openssl x509 -in certificate.crt -text -noout

경고를 유발한 인증서를 업데이트하거나 제거한 다음 새 트러스트 스토어를 Amazon S3에 업로드합니다. 새 트러스트 스토어를 업로드한 후 새 트러스트 스토어를 사용하도록 사용자 지정 도메인 이름을 업데이트합니다.

도메인 이름 충돌 문제 해결

오류 "The certificate subject <certSubject> conflicts with an existing certificate from a different issuer."은(는) 여러 인증 기관이 이 도메인에 대한 인증서를 발급했음을 의미합니다. 인증서의 각 주체에 대해 API Gateway에는 상호 TLS 도메인에 대한 발급자가 하나만 있을 수 있습니다. 해당 주제에 대한 모든 인증서는 단일 발급자를 통해서만 받아야 합니다. 본인이 제어할 수 없지만 도메인 이름의 소유권을 증명할 수는 있는 인증서에 문제가 있는 경우 AWS Support에 문의를 눌러 티켓을 엽니다.

도메인 이름 상태 메시지 문제 해결

PENDING_CERTIFICATE_REIMPORT: 이것은 인증서를 ACM으로 다시 가져왔으며, 새 인증서에 SAN(주체 대체 이름)이 ownershipVerificationCertificate에 포함되지 않거나 인증서의 주체 또는 SAN이 도메인 이름을 포함하지 않기 때문에 유효성 검사에 실패했다는 의미입니다. 잘못 구성되었거나 잘못된 인증서를 가져왔을 수 있습니다. 유효한 인증서를 ACM으로 다시 가져와야 합니다. 검증에 대한 자세한 내용은 도메인 소유권 검증을 참조하세요.

PENDING_OWNERSHIP_VERIFICATION: 이것은 이전에 확인된 인증서가 만료되어 ACM이 인증서를 자동 갱신할 수 없다는 의미입니다. 인증서를 갱신하거나 새 인증서를 요청해야 합니다. 인증서 갱신에 대한 자세한 내용은 ACM의 관리형 인증서 갱신 문제 해결 가이드를 참조하세요.

잘못 반환된 인증서 문제 해결

전용 인증서를 정규화된 도메인 이름(FQDN)에서 와일드카드 고객 도메인 이름으로 마이그레이션할 때 API Gateway가 와일드카드 도메인 이름 대신 FQDN에 대한 인증서를 반환할 수 있습니다.

다음 명령은 API Gateway에서 반환되는 인증서를 표시합니다.

openssl s_client -connect hostname:port

반환되는 인증서가 FQDN용인 경우 AWS Support에 문의하여 티켓을 엽니다.