HTTP API에 대한 상호 TLS 인증 구성 - Amazon API Gateway

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

HTTP API에 대한 상호 TLS 인증 구성

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

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

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

중요

기본적으로 클라이언트는 API에 대해 API Gateway가 생성하는 execute-api 엔드포인트를 사용하여 API를 호출할 수 있습니다. 클라이언트가 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용해야만 API에 액세스할 수 있도록 하려면 기본 execute-api 엔드포인트를 비활성화합니다. 자세한 내용은 HTTP API에 대한 기본 엔드포인트 비활성화 단원을 참조하십시오.

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

상호 TLS를 사용하려면 API에 액세스하도록 신뢰할 수 있는 X.509 인증서의 트러스트 스토어를 생성합니다. 공인 또는 사설 인증 기관의 인증서가 포함될 수 있습니다. 인증서의 체인 길이는 최대 4개가 될 수 있습니다. 자체 서명된 인증서를 제공할 수도 있습니다. 다음 모듈을 지원합니다.

  • SHA-256 이상

  • RSA-2048 이상

  • ECDSA-256 이상

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

검증 설명

X.509 구문

인증서는 X.509 구문 요구 사항을 충족해야 합니다.

무결성

인증서 내용이 트러스트 스토어의 인증 기관에서 서명한 내용에서 변경되어서는 안 됩니다.

유효성

인증서의 유효 기간이 최신이어야 합니다.

이름 체인/키 체인

인증서의 이름과 주체는 끊어지지 않는 체인을 형성해야 합니다. 인증서의 체인 길이는 최대 4개가 될 수 있습니다.

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

예 certificates.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

트러스트 스토어를 Amazon S3에 업로드한 후 상호 TLS를 사용하도록 사용자 지정 도메인 이름을 구성할 수 있습니다.

상호 TLS가 활성화된 사용자 지정 도메인 이름을 생성하거나 새 트러스트 스토어를 사용하도록 사용자 지정 도메인을 업데이트할 때 트러스트 스토어의 인증서가 유효하지 않을 경우 API Gateway에서 경고가 반환됩니다. 상호 TLS가 계속 활성화되어 있지만 일부 클라이언트는 API에 액세스하지 못할 수 있습니다. 경고를 해결하려면 S3에 새 트러스트 스토어를 업로드한 다음 새 버전을 사용하도록 도메인 이름을 업데이트합니다. 자세한 내용은 인증서 경고 문제 해결 단원을 참조하세요.

참고

상호 TLS를 활성화하려면 도메인 이름이 AWS Certificate Manager에서 발급한 공개적으로 신뢰할 수 있는 서버 인증서를 사용해야 합니다.

aws apigatewayv2 create-domain-name \ --domain-name api.example.com \ --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \ --mutual-tls-authentication TruststoreUri=s3://bucket-name/key-name

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

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

상호 TLS가 활성화된 API를 호출하려면 클라이언트가 API 요청에서 신뢰할 수 있는 인증서를 제공해야 합니다. 다음 예제 curl 명령은 요청에 my-cert.pem을 포함하여 api.example.com,에 요청을 보냅니다. my-key.key는 인증서의 프라이빗 키입니다.

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

트러스트 스토어가 인증서를 신뢰하는 경우에만 API가 호출됩니다. 인증서가 신뢰할 수 없거나 만료되었거나 지원되는 알고리즘을 사용하지 않는 경우 403 상태 코드와 함께 요청이 거부됩니다.

참고

API Gateway에서는 인증서가 해지되었는지 여부를 확인하지 않습니다.

트러스트 스토어 업데이트

트러스트 스토어를 업데이트하려면 새 인증서 번들을 Amazon S3에 업로드한 다음 새 버전을 사용하도록 사용자 지정 도메인 이름을 업데이트합니다.

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

참고

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

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

aws apigatewayv2 update-domain-name \ --domain-name api.example.com \ --mutual-tls-authentication truststoreVersion='abcdef123'

상호 TLS 비활성화

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

aws apigatewayv2 update-domain-name \ --domain-name api.example.com \ --mutual-tls-authentication truststoreUri=''

인증서 경고 문제 해결

상호 TLS가 활성화된 사용자 지정 도메인 이름을 생성하거나 새 트러스트 스토어를 사용하도록 사용자 지정 도메인 이름을 업데이트할 때 인증서가 유효하지 않을 경우 API Gateway에서 경고가 반환됩니다. 이러한 경고는 경고를 유발한 인증서와 인증서 주체에 문제가 있음을 나타냅니다.

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

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

openssl x509 -in certificate.crt -text -noout

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