When you use mutual TLS in verify mode, the load balancer performs X.509v3 client
certificate authentication for clients when it negotiates TLS connections.
To utilize mutual TLS verify mode, perform the following:
-
Create a new trust store resource.
-
Upload your certificate authority (CA) bundle and, optionally, revocation
lists.
-
Attach the trust store to the listener that is configured to verify client
certificates.
Use the following procedures to configure mutual TLS verify mode on your
Network Load Balancer.
Create a trust store
If you add a trust store when you create a load balancer or listener, the trust
store is automatically associated with the new listener. Otherwise, you must
associate it with a listener yourself.
Prerequisites
- AWS Management Console
-
The following example creates a trust store using the Trust Store
portion of the console. Alternatively, you can create
the trust store when you create a TLS listener.
To create a trust store
Open the Amazon EC2 console at
https://console.aws.amazon.com/ec2/.
-
On the navigation pane, choose Trust
Stores.
-
Choose Create trust store.
-
Trust store configuration
-
For Trust store name, enter a
name for your trust store.
-
For Certificate authority bundle,
enter the Amazon S3 path to the ca certificate bundle to
use.
-
(Optional) Use Object version to
select a previous version of the ca certificate bundle.
Otherwise, the current version is used.
-
(Optional) For Revocations, you can add a
certificate revocation list to your trust store.
-
Choose Add new CRL and enter the
location of the certificate revocation list in
Amazon S3.
-
(Optional) Use Object version to
select a previous version of the certificate revocation
list. Otherwise, the current version is used.
-
(Optional) Expand Trust store tags and
enter up to 50 tags for your trust store.
-
Choose Create trust store.
- AWS CLI
-
To create a trust store
Use the create-trust-store command.
aws elbv2 create-trust-store \
--name my-trust-store \
--ca-certificates-bundle-s3-bucket amzn-s3-demo-bucket \
--ca-certificates-bundle-s3-key certificates/ca-bundle.pem
- AWS CloudFormation
-
To create a trust store
Define a resource of type
AWS::ElasticLoadBalancingV2::TrustStore.
Resources:
myTrustStore:
Type: 'AWS::ElasticLoadBalancingV2::TrustStore'
Properties:
Name: my-trust-store
CaCertificatesBundleS3Bucket: amzn-s3-demo-bucket
CaCertificatesBundleS3Key: certificates/ca-bundle.pem
Associate a trust store
After you create a trust store, you must associate it with a listener before your
Network Load Balancer can begin using the trust store. You can have only one trust store associated
to each of your TLS listeners, but one trust store can be associated to multiple
listeners.
- AWS Management Console
-
To associate a trust store with a listener
Open the Amazon EC2 console at
https://console.aws.amazon.com/ec2/.
-
In the navigation pane, choose Load
Balancers.
-
Select the name of the load balancer to open its details
page.
-
On the Listeners and rules tab, select
the TLS listener, and then choose Edit
listener.
-
Under Client certificate handling, select
Mutual authentication (mTLS), and then
choose Verify with trust store.
-
For Trust store, choose your trust
store.
-
Choose Save changes.
- AWS CLI
-
To associate a trust store with an existing listener
Use the modify-listener command with the
--mutual-authentication argument.
aws elbv2 modify-listener \
--listener-arn listener-arn \
--mutual-authentication Mode=verify,TrustStoreArn=trust-store-arn
- AWS CloudFormation
-
Update the AWS::ElasticLoadBalancingV2::Listener
resource.
Resources:
myTLSListener:
Type: 'AWS::ElasticLoadBalancingV2::Listener'
Properties:
LoadBalancerArn: !Ref myLoadBalancer
Protocol: TLS
Port: 443
DefaultActions:
- Type: "forward"
TargetGroupArn: !Ref myTargetGroup
SslPolicy: ELBSecurityPolicy-TLS13-1-2-2021-06
Certificates:
- CertificateArn: certificate-arn
MutualAuthentication:
Mode: verify
TrustStoreArn: trust-store-arn
Replace a CA certificate bundle
The CA certificate bundle is a required component of the trust store. It is a
collection of trusted root and intermediate certificates that have been validated by
a certificate authority. These validated certificates ensure that the client can
trust that the certificate being presented is owned by the load balancer. A trust
store can only contain one CA certificate bundle at a time, but you can replace the
CA certificate bundle at any time after the trust store is created.
- AWS Management Console
-
To replace a CA certificate bundle
Open the Amazon EC2 console at
https://console.aws.amazon.com/ec2/.
-
In the navigation pane, under Load
Balancing, choose Trust Stores.
-
Select your trust store.
-
Choose Actions, and then choose
Replace CA bundle.
-
For CA certificate bundle, enter the Amazon S3
path to the new bundle.
-
Choose Replace CA bundle.
- AWS CLI
-
To replace a CA certificate bundle
Use the modify-trust-store command.
aws elbv2 modify-trust-store \
--trust-store-arn trust-store-arn \
--ca-certificates-bundle-s3-bucket amzn-s3-demo-bucket \
--ca-certificates-bundle-s3-key certificates/ca-bundle.pem
- AWS CloudFormation
-
Define a resource of type
AWS::ElasticLoadBalancingV2::TrustStore.
Resources:
myTrustStore:
Type: 'AWS::ElasticLoadBalancingV2::TrustStore'
Properties:
Name: my-trust-store
CaCertificatesBundleS3Bucket: amzn-s3-demo-bucket-new
CaCertificatesBundleS3Key: certificates/new-ca-bundle.pem
Add a certificate revocation list
Optionally, you can create a certificate revocation list (CRL) for a trust store.
Revocation lists are released by certificate authorities and contain data for
certificates that have been revoked. Network Load Balancers only support certificate revocation
lists in the PEM format. When a certificate revocation list is added to a trust
store, it is given a revocation ID. The revocation IDs increase for every revocation
list added to the trust store, and they can't be changed.
Network Load Balancers do not support revoking certificates that have a negative serial
number. If a CRL contains a negative serial number, Network Load Balancers ignore that entry and
do not revoke the certificate it identifies. To revoke such a certificate,
reissue it with a non-negative serial number.
- AWS Management Console
-
To add a certificate revocation list
Open the Amazon EC2 console at
https://console.aws.amazon.com/ec2/.
-
In the navigation pane, under Load
Balancing, choose Trust Stores.
-
Select your trust store.
-
On the Certificate revocation lists tab,
choose Actions, and then choose
Add revocation list.
-
For Certificate revocation list, enter the
Amazon S3 path to your revocation list.
-
Choose Add.
- AWS CLI
-
To add a certificate revocation list
Use the add-trust-store-revocations command.
aws elbv2 add-trust-store-revocations \
--trust-store-arn trust-store-arn \
--revocation-contents "RevocationType=CRL,S3Bucket=amzn-s3-demo-bucket,S3Key=crl/revoked-list.pem"
- AWS CloudFormation
-
Define a resource of type
AWS::ElasticLoadBalancingV2::TrustStoreRevocation.
Resources:
myRevocationContents:
Type: 'AWS::ElasticLoadBalancingV2::TrustStoreRevocation'
Properties:
TrustStoreArn: !Ref myTrustStore
RevocationContents:
- RevocationType: CRL
S3Bucket: amzn-s3-demo-bucket
S3Key: crl/revoked-list.pem
Delete a certificate revocation list
When you no longer need a certificate revocation list, you can delete it. When you
delete a certificate revocation list from a trust store, its revocation ID is also
deleted and is not reused for the life of the trust store.
- AWS Management Console
-
To delete a certificate revocation list
Open the Amazon EC2 console at
https://console.aws.amazon.com/ec2/.
-
In the navigation pane, under Load
Balancing, choose Trust Stores.
-
Select your trust store.
-
On the Certificate revocation lists tab,
select the revocation list.
-
Choose Actions, and then choose
Remove revocation list.
-
When prompted for confirmation, enter
confirm, and then choose
Delete.
- AWS CLI
-
To delete a certificate revocation list
Use the remove-trust-store-revocations command.
aws elbv2 remove-trust-store-revocations \
--trust-store-arn trust-store-arn \
--revocation-ids 1
Delete a trust store
When you no longer have use for a trust store, you can delete it. You can't delete
a trust store that is associated with a listener.
- AWS Management Console
-
To delete a trust store
Open the Amazon EC2 console at
https://console.aws.amazon.com/ec2/.
-
Before you delete the trust store, remove its listener
association. Open the listener, choose
Edit, and turn off Mutual
authentication (mTLS). You can also remove the
association from the Associations tab of
the trust store.
-
In the navigation pane, under Load
Balancing, choose Trust Stores.
-
Select your trust store.
-
Choose Actions, and then choose
Delete.
-
When prompted for confirmation, enter
confirm, and then choose
Delete.
- AWS CLI
-
To remove the listener association
Before you delete the trust store, use the modify-listener command to turn off mutual
authentication, which disassociates the trust store.
aws elbv2 modify-listener \
--listener-arn listener-arn \
--mutual-authentication Mode=off
To delete a trust store
Use the delete-trust-store command.
aws elbv2 delete-trust-store \
--trust-store-arn trust-store-arn
Create a TLS listener with mTLS
You can enable mutual authentication when you create a TLS listener, instead of
modifying an existing listener.
- AWS Management Console
-
To create a TLS listener with mTLS
Open the Amazon EC2 console at
https://console.aws.amazon.com/ec2/.
-
In the navigation pane, choose Load
Balancers.
-
Select the name of the load balancer to open its details
page.
-
On the Listeners and rules tab, choose
Add listener.
-
For Protocol, choose
TLS, and then enter the port.
-
For Default SSL/TLS server certificate,
choose a certificate.
-
Under Client certificate handling, select
Mutual authentication (mTLS), and then
choose Verify with trust store.
-
For Trust store, choose your trust
store.
-
For Default action, choose a target group
to forward traffic to.
-
Choose Add.
- AWS CLI
-
To create a TLS listener with mTLS
Use the create-listener command, specifying the TLS protocol
and verify mode.
aws elbv2 create-listener \
--load-balancer-arn load-balancer-arn \
--protocol TLS \
--port 443 \
--certificates CertificateArn=certificate-arn \
--ssl-policy ELBSecurityPolicy-TLS13-1-2-2021-06 \
--mutual-authentication Mode=verify,TrustStoreArn=trust-store-arn \
--default-actions Type=forward,TargetGroupArn=target-group-arn
- AWS CloudFormation
-
Use the AWS::ElasticLoadBalancingV2::Listener resource
with a MutualAuthentication property.
Resources:
MyTlsListener:
Type: AWS::ElasticLoadBalancingV2::Listener
Properties:
LoadBalancerArn: load-balancer-arn
Protocol: TLS
Port: 443
Certificates:
- CertificateArn: certificate-arn
MutualAuthentication:
Mode: verify
TrustStoreArn: trust-store-arn
DefaultActions:
- Type: forward
TargetGroupArn: target-group-arn
Modify a TLS listener with mTLS
You can enable or change mutual authentication on an existing TLS listener.
- AWS Management Console
-
To modify a TLS listener with mTLS
Open the Amazon EC2 console at
https://console.aws.amazon.com/ec2/.
-
In the navigation pane, choose Load
Balancers.
-
Select the name of the load balancer to open its details
page.
-
On the Listeners and rules tab, select
the TLS listener, and then choose Edit
listener.
-
Under Client certificate handling, select
Mutual authentication (mTLS), and then
choose Verify with trust store.
-
For Trust store, choose your trust
store.
-
Choose Save changes.
- AWS CLI
-
To modify a TLS listener with mTLS
Use the modify-listener command with the
--mutual-authentication argument.
aws elbv2 modify-listener \
--listener-arn listener-arn \
--mutual-authentication Mode=verify,TrustStoreArn=trust-store-arn
- AWS CloudFormation
-
Update the MutualAuthentication property of the
AWS::ElasticLoadBalancingV2::Listener resource, and then
deploy the updated stack.
Resources:
MyTlsListener:
Type: AWS::ElasticLoadBalancingV2::Listener
Properties:
LoadBalancerArn: load-balancer-arn
Protocol: TLS
Port: 443
Certificates:
- CertificateArn: certificate-arn
MutualAuthentication:
Mode: verify
TrustStoreArn: trust-store-arn
DefaultActions:
- Type: forward
TargetGroupArn: target-group-arn
Advanced mTLS listener settings
You can change two optional mTLS behaviors on a TLS listener. Both settings travel
in the MutualAuthenticationAttributes structure on the listener.
ClientCertificateIdentityFilters is also part of the
MutualAuthenticationAttributes structure. To restrict which client
identities the load balancer admits, see Client certificate identity filters.
- Expired client certificate handling
-
The IgnoreClientCertificateExpiry attribute controls
whether the load balancer accepts a client certificate whose validity
period has passed. By default, the load balancer rejects expired
certificates. To accept expired certificates that otherwise chain to a
trusted CA, set IgnoreClientCertificateExpiry to
true.
- Advertise trust store CA subject names
-
The AdvertiseTrustStoreCaNames attribute controls whether
the load balancer tells connecting clients which CAs it trusts. When you
enable this attribute, the load balancer includes the distinguished names
of the trusted CAs in the TLS CertificateRequest message
during the handshake. A client can then automatically select a
certificate that a trusted CA issued. By default, this attribute is off.
You can enable it on new and existing TLS listeners.
- AWS Management Console
-
To accept expired certificates and advertise CA names
Open the Amazon EC2 console at
https://console.aws.amazon.com/ec2/.
-
In the navigation pane, choose Load
Balancers.
-
Select the name of the load balancer to open its details
page.
-
On the Listeners and rules tab, select
the TLS listener, and then choose Edit
listener.
-
In the mutual authentication (mTLS) settings, select
Allow expired client certificates to accept
expired certificates that are still trusted.
-
Select Advertise trust store CA subject
names to advertise trusted CA names to
clients.
-
Choose Save changes.
- AWS CLI
-
To accept expired certificates and advertise CA names
Use the modify-listener command.
aws elbv2 modify-listener \
--listener-arn listener-arn \
--mutual-authentication Mode=verify,TrustStoreArn=trust-store-arn,IgnoreClientCertificateExpiry=true,AdvertiseTrustStoreCaNames=on
- CloudFormation
-
Use the AWS::ElasticLoadBalancingV2::Listener resource
with a MutualAuthentication property.
Resources:
MyTlsListener:
Type: AWS::ElasticLoadBalancingV2::Listener
Properties:
Protocol: TLS
Port: 443
MutualAuthentication:
Mode: verify
TrustStoreArn: trust-store-arn
IgnoreClientCertificateExpiry: true
AdvertiseTrustStoreCaNames: "on"