Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Custom client certificate validation

Amazon IoT Core supports custom client certificate validation for X.509 client certificates, which enhances client authentication management. This certificate validation method is also known as pre-authentication certificate checks, in which you evaluate client certificates based on your own criteria (defined in a Lambda function) and revoke client certificates or the certificates' signing certificate authority (CA) certificate to prevent clients to connect to Amazon IoT Core. For example, you can create your own certificate revocation checks that validate the certificates' status against validation authorities that support Online Certificate Status Protocol (OCSP) or Certificate Revocation Lists (CRL) endpoints, and prevent connections for clients with revoked certificates. The criteria used to evaluate client certificates are defined in a Lambda function (also known as pre-authentication Lambda). You must use the endpoints set in domain configurations and the authentication type must be X.509 certificate. In addition, clients must provide the Server Name Indication (SNI) extension when connecting to Amazon IoT Core.

Step 1: Register your X.509 client certificates with Amazon IoT Core

If you haven't done this already, register and activate your X.509 client certificates with Amazon IoT Core. Otherwise, skip to the next step.

To register and activate your client certificates with Amazon IoT Core, follow the steps:

Step 2: Create a Lambda function

You need to create a Lambda function that will perform certificate verification and be called for every client connect attempt for the configured endpoint. When creating this Lambda function, follow the general guidance from Create your first Lambda function. Additionally, ensure that the Lambda function adheres to the expected request and response formats as follows:

Lambda function event example

{
	"connectionMetadata": {
		"id": "string"
	},
	"principalId": "string",
	"serverName": "string",
	"clientCertificateChain": [
		"string",
		"string"
	]
}

Lambda function response example

{
	"isAuthenticated": "boolean"
}

Step 3: Authorize Amazon IoT to invoke your Lambda function

After creating the Lambda function, you must grant permission for Amazon IoT to invoke it, by using the add-permission CLI command. Note that this Lambda function will be invoked for every connect attempt to your configured endpoint. For more information, see Authorizing Amazon IoT to invoke your Lambda function.

Step 4: Set authentication configuration for a domain

The following section describes how to set authentication configuration for a custom domain using the Amazon CLI.

Set client certificate configuration for a domain (CLI)

If you don't have a domain configuration, use the create-domain-configuration CLI command to create one. If you already have a domain configuration, use the update-domain-configuration CLI command to update the client certificate configuration for a domain. You must add the ARN of the Lambda function that you've created in the previous step.

aws iot create-domain-configuration \
    --domain-configuration-name domainConfigurationName \
    --authentication-type AWS_X509|CUSTOM_AUTH_X509 \
    --application-protocol SECURE_MQTT|HTTPS \
    --client-certificate-config 'clientCertificateCallbackArn":"arn:aws:lambda:us-east-2:123456789012:function:my-function:1"}'

aws iot update-domain-configuration \
    --domain-configuration-name domainConfigurationName \
    --authentication-type AWS_X509|CUSTOM_AUTH_X509 \
    --application-protocol SECURE_MQTT|HTTPS \
    --client-certificate-config '{"clientCertificateCallbackArn":"arn:aws:lambda:us-east-2:123456789012:function:my-function:1"}'

For more information, see CreateDomainConfiguration and UpdateDomainConfiguration from the Amazon IoT API Reference. For more information about domain configurations, see Domain configurations.