# Client authentication
AWS IoT supports three types of identity principals for device or client authentication:
+ [X.509 client certificates](x509-client-certs.md)
+ [IAM users, groups, and roles](iam-users-groups-roles.md)
+ [Amazon Cognito identities](cognito-identities.md)
These identities can be used with devices, mobile, web, or desktop applications. They can even be used by a user typing AWS IoT command line interface (CLI) commands. Typically, AWS IoT devices use X.509 certificates, while mobile applications use Amazon Cognito identities. Web and desktop applications use IAM or federated identities. AWS CLI commands use IAM. For more information about IAM identities, see [Identity and access management for AWS IoT](security-iam.md).
# X.509 client certificates
X.509 certificates provide AWS IoT with the ability to authenticate client and device connections. Client certificates must be registered with AWS IoT before a client can communicate with AWS IoT. A client certificate can be registered in multiple AWS accounts in the same AWS Region to facilitate moving devices between your AWS accounts in the same region. See [Using X.509 client certificates in multiple AWS accounts with multi-account registration](#multiple-account-cert) for more information.
We recommend that each device or client be given a unique certificate to enable fine-grained client management actions, including certificate revocation. Devices and clients must also support rotation and replacement of certificates to help ensure smooth operation as certificates expire.
For information about using X.509 certificates to support more than a few devices, see [Device provisioning](iot-provision.md) to review the different certificate management and provisioning options that AWS IoT supports.
**AWS IoT supports these types of X.509 client certificates:**
+ X.509 certificates generated by AWS IoT
+ X.509 certificates signed by a CA registered with AWS IoT.
+ X.509 certificates signed by a CA that is not registered with AWS IoT.
This section describes how to manage X.509 certificates in AWS IoT. You can use the AWS IoT console or AWS CLI to perform these certificate operations:
+ [Create AWS IoT client certificates](device-certs-create.md)
+ [Create your own client certificates](device-certs-your-own.md)
+ [Register a client certificate](register-device-cert.md)
+ [Activate or deactivate a client certificate](activate-or-deactivate-device-cert.md)
+ [Revoke a client certificate](revoke-ca-cert.md)
For more information about the AWS CLI commands that perform these operations, see [AWS IoT CLI Reference](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/index.html).
## Using X.509 client certificates
X.509 certificates authenticate client and device connections to AWS IoT. X.509 certificates provide several benefits over other identification and authentication mechanisms. X.509 certificates enable asymmetric keys to be used with devices. For example, you could burn private keys into secure storage on a device so that sensitive cryptographic material never leaves the device. X.509 certificates provide stronger client authentication over other schemes, such as user name and password or bearer tokens, because the private key never leaves the device.
AWS IoT authenticates client certificates using the TLS protocol's client authentication mode. TLS support is available in many programming languages and operating systems and is commonly used for encrypting data. In TLS client authentication, AWS IoT requests an X.509 client certificate and validates the certificate's status and AWS account against a registry of certificates. It then challenges the client for proof of ownership of the private key that corresponds to the public key contained in the certificate. AWS IoT requires clients to send the [Server Name Indication (SNI) extension](https://tools.ietf.org/html/rfc3546#section-3.1) to the Transport Layer Security (TLS) protocol. For more information on configuring the SNI extension, see [Transport security in AWS IoT Core](transport-security.md).
To facilitate a secure and consistent client connection to AWS IoT core, a X.509 client certificate must possess the following:
+ Registered in AWS IoT Core. For more information, see [Register a client certificate](register-device-cert.md).
+ Have a status state of `ACTIVE`. For more information, see [Activate or deactivate a client certificate](activate-or-deactivate-device-cert.md).
+ Not yet reached the certificate expiration date.
You can create client certificates that use the Amazon Root CA and you can use your own client certificates signed by another certificate authority (CA). For more information about using the AWS IoT console to create certificates that use the Amazon Root CA, see [Create AWS IoT client certificates](device-certs-create.md). For more information about using your own X.509 certificates, see [Create your own client certificates](device-certs-your-own.md).
The date and time when certificates signed by a CA certificate expire are set when the certificate is created. X.509 certificates generated by AWS IoT expire at midnight UTC on December 31, 2049 (2049-12-31T23:59:59Z).
AWS IoT Device Defender can perform audits on your AWS account and devices supporting common IoT security best practices. This includes managing the expiration dates of X.509 certificates signed by your CA or the Amazon Root CA. For more information on managing a certificate's expiration date, see [Device certificate expiring](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/audit-chk-device-cert-approaching-expiration.html) and [CA certificate expiring](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/audit-chk-ca-cert-approaching-expiration.html).
On the official AWS IoT blog, a deeper dive into the management of device certificate rotation and security best practices is explored in [How to manage IoT device certificate rotation using AWS IoT](https://aws.amazon.com/blogs/iot/how-to-manage-iot-device-certificate-rotation-using-aws-iot/).
## Using X.509 client certificates in multiple AWS accounts with multi-account registration
Multi-account registration makes it possible to move devices between your AWS accounts in the same Region or in different Regions. You can register, test, and configure a device in a pre-production account, and then register and use the same device and device certificate in a production account. You can also register the client certificate on the device or the device certificates without a CA that is registered with AWS IoT. For more information, see [Register a client certificate signed by an unregistered CA (CLI).](manual-cert-registration.md#manual-cert-registration-noca-cli)
**Note**
Certificates used for multi-account registration are supported on the `iot:Data-ATS`, `iot:Data` (legacy), `iot:Jobs`, and `iot:CredentialProvider` endpoint types. For more information about AWS IoT device endpoints, see [AWS IoT device data and service endpoints](iot-connect-devices.md#iot-connect-device-endpoints).
Devices that use multi-account registration must send the [Server Name Indication (SNI) extension](https://tools.ietf.org/html/rfc3546#section-3.1) to the Transport Layer Security (TLS) protocol and provide the complete endpoint address in the `host_name` field, when they connect to AWS IoT. AWS IoT uses the endpoint address in `host_name` to route the connection to the correct AWS IoT account. Existing devices that don't send a valid endpoint address in `host_name` will continue to work, but they will not be able to use the features that require this information. For more information about the SNI extension and to learn how to identify the endpoint address for the `host_name` field, see [Transport security in AWS IoT Core](transport-security.md).
**To use multi-account registration**
1. You can register the device certificates with a CA. You can register the signing CA in multiple accounts in `SNI_ONLY` mode and use that CA to register the same client certificate to multiple accounts. For more information, see [Register a CA certificate in SNI\$1ONLY mode (CLI) - Recommended](manage-your-CA-certs.md#register-CA-cert-SNI-cli).
1. You can register the device certificates without a CA. See [Register a client certificate signed by an unregistered CA (CLI)](manual-cert-registration.md#manual-cert-registration-noca-cli). Registering a CA is optional. You're not required to register the CA that signed the device certificates with AWS IoT.
## Certificate signing algorithms supported by AWS IoT
AWS IoT supports the following certificate-signing algorithms:
+ SHA256WITHRSA
+ SHA384WITHRSA
+ SHA512WITHRSA
+ SHA256WITHRSAANDMGF1 (RSASSA-PSS)
+ SHA384WITHRSAANDMGF1 (RSASSA-PSS)
+ SHA512WITHRSAANDMGF1 (RSASSA-PSS)
+ DSA\$1WITH\$1SHA256
+ ECDSA-WITH-SHA256
+ ECDSA-WITH-SHA384
+ ECDSA-WITH-SHA512
For more information about certificate authentication and security, see [Device certificate key quality](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/audit-chk-device-cert-key-quality.html).
**Note**
The certificate signing request (CSR) must include a public key. The key can be either an RSA key with a length of at least 2,048 bits or an ECC key from NIST P-256, NIST P-384, or NIST P-521 curves. For more information, see [CreateCertificateFromCsr](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCertificateFromCsr.html) in the *AWS IoT API Reference Guide*.
## Key algorithms supported by AWS IoT
The table below shows how key algorithms are supported:
****
| Key algorithm | Certificate signing algorithm | TLS version | Supported? Yes or No |
| --- | --- | --- | --- |
| RSA with a key size of at least 2048 bits | All | TLS 1.2 TLS 1.3 | Yes |
| ECC NIST P-256/P-384/P-521 | All | TLS 1.2 TLS 1.3 | Yes |
| RSA-PSS with a key size of at least 2048 bits | All | TLS 1.2 | No |
| RSA-PSS with a key size of at least 2048 bits | All | TLS 1.3 | Yes |
To create a certificate using [CreateCertificateFromCSR](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateCertificateFromCsr.html), you can use a supported key algorithm to generate a public key for your CSR. To register your own certificate using [RegisterCertificate](https://docs.aws.amazon.com//iot/latest/apireference/API_RegisterCertificate.html) or [RegisterCertificateWithoutCA](https://docs.aws.amazon.com//iot/latest/apireference/API_RegisterCertificateWithoutCA.html), you can use a supported key algorithm to generate a public key for the certificate.
For more information, see [Security policies](https://docs.aws.amazon.com//iot/latest/developerguide/transport-security.html#tls-policy-table).
# Create AWS IoT client certificates
AWS IoT provides client certificates that are signed by the Amazon Root certificate authority (CA).
This topic describes how to create a client certificate signed by the Amazon Root certificate authority and download the certificate files. After you create the client certificate files, you must install them on the client.
**Note**
Each X.509 client certificate provided by AWS IoT holds issuer and subject attributes that you set at the time of certificate creation. The certificate attributes are immutable only after the certificate is created.
You can use the AWS IoT console or the AWS CLI to create an AWS IoT certificate signed by the Amazon Root certificate authority.
## Create an AWS IoT certificate (console)
**To create an AWS IoT certificate using the AWS IoT console**
1. Sign in to the AWS Management Console and open the [AWS IoT console](https://console.aws.amazon.com/iot/home).
1. In the navigation pane, choose **Security**, then choose **Certificates**, and then choose **Create**.
1. Choose **One-click certificate creation (recommended)** - **Create certificate**.
1. From the **Certificate created** page, download the client certificate files for the thing, public key, and private key to a secure location. These certificates generated by AWS IoT are only available for use with AWS IoT services.
If you also need the Amazon Root CA certificate file, this page also has the link to the page where you can download it.
1. A client certificate has now been created and registered with AWS IoT. You must activate the certificate before you use it in a client.
To activate the client certificate now, choose **Activate**. If you don't want to activate the certificate now, see [Activate a client certificate (console)](activate-or-deactivate-device-cert.md#activate-device-cert-console) to learn how to activate the certificate later.
1. If you want to attach a policy to the certificate, choose **Attach a policy**.
If you don't want to attach a policy now, choose **Done** to finish. You can attach a policy later.
After you complete the procedure, install the certificate files on the client.
## Create an AWS IoT certificate (CLI)
The AWS CLI provides the **[create-keys-and-certificate](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/create-keys-and-certificate.html)** command to create client certificates signed by the Amazon Root certificate authority. This command, however, does not download the Amazon Root CA certificate file. You can download the Amazon Root CA certificate file from [CA certificates for server authentication](server-authentication.md#server-authentication-certs).
This command creates private key, public key, and X.509 certificate files and registers and activates the certificate with AWS IoT.
```
aws iot create-keys-and-certificate \
--set-as-active \
--certificate-pem-outfile certificate_filename.pem \
--public-key-outfile public_filename.key \
--private-key-outfile private_filename.key
```
If you don't want to activate the certificate when you create and register it, this command creates private key, public key, and X.509 certificate files and registers the certificate, but it does not activate it. [Activate a client certificate (CLI)](activate-or-deactivate-device-cert.md#activate-device-cert-cli) describes how to activate the certificate later.
```
aws iot create-keys-and-certificate \
--no-set-as-active \
--certificate-pem-outfile certificate_filename.pem \
--public-key-outfile public_filename.key \
--private-key-outfile private_filename.key
```
Install the certificate files on the client.
# Create your own client certificates
AWS IoT supports client certificates signed by any root or intermediate certificate authorities (CA). AWS IoT uses CA certificates to verify the ownership of certificates. To use device certificates signed by a CA that’s not Amazon’s CA, the CA’s certificate must be registered with AWS IoT so that we can verify the device certificate’s ownership.
AWS IoT supports multiple ways for bringing your own certificates (BYOC):
+ First, register the CA that’s used for signing the client certificates and then register individual client certificates. If you want to register the device or client to its client certificate when it first connects to AWS IoT (also known as [Just-in-Time Provisioning](https://docs.aws.amazon.com//iot/latest/developerguide/jit-provisioning.html)), you must register the signing CA with AWS IoT and activate auto-registration.
+ If you can’t register the signing CA, you can choose to register client certificates without CA. For devices registered without CA, you’ll need to present [Server Name Indication (SNI)](https://www.rfc-editor.org/rfc/rfc3546#section-3.1) when you connect them to AWS IoT.
**Note**
To register client certificates using CA, you must register the signing CA with AWS IoT, not any other CAs in the hierarchy.
**Note**
A CA certificate can be registered in `DEFAULT` mode by only one account in a Region. A CA certificate can be registered in `SNI_ONLY` mode by multiple accounts in a Region.
For more information about using X.509 certificates to support more than a few devices, see [Device provisioning](iot-provision.md) to review the different certificate management and provisioning options that AWS IoT supports.
**Topics**
+ [Manage your CA certificates](manage-your-CA-certs.md)
+ [Create a client certificate using your CA certificate](create-device-cert.md)
# Manage your CA certificates
This section describes common tasks for managing your own certificate authority (CA) certificates.
You can register your certificate authority (CA) with AWS IoT if you are using client certificates signed by a CA that AWS IoT doesn't recognize.
If you want clients to automatically register their client certificates with AWS IoT when they first connect, the CA that signed the client certificates must be registered with AWS IoT. Otherwise, you don't need to register the CA certificate that signed the client certificates.
**Note**
A CA certificate can be registered in `DEFAULT` mode by only one account in a Region. A CA certificate can be registered in `SNI_ONLY` mode by multiple accounts in a Region.
**Topics**
+ [Create a CA certificate](#create-your-CA-cert)
+ [Register your CA certificate](#register-CA-cert)
+ [Deactivate a CA certificate](#deactivate-ca-cert)
## Create a CA certificate
If you do not have a CA certificate, you can use [OpenSSL v1.1.1i](https://www.openssl.org/) tools to create one.
**Note**
You can't perform this procedure in the AWS IoT console.
**To create a CA certificate using [OpenSSL v1.1.1i](https://www.openssl.org/) tools**
1. Generate a key pair.
```
openssl genrsa -out root_CA_key_filename.key 2048
```
1. Use the private key from the key pair to generate a CA certificate.
```
openssl req -x509 -new -nodes \
-key root_CA_key_filename.key \
-sha256 -days 1024 \
-out root_CA_cert_filename.pem
```
## Register your CA certificate
These procedures describe how to register a certificate from a certificate authority (CA) that's not Amazon's CA. AWS IoT Core uses CA certificates to verify the ownership of certificates. To use device certificates signed by a CA that's not Amazon's CA, you must register the CA certificate with AWS IoT Core so that it can verify the device certificate's ownership.
### Register a CA certificate (console)
**Note**
To register a CA certificate in the console, start in the console at [Register CA certificate](https://console.aws.amazon.com//iot/home#/create/cacertificate). You can register your CA in Multi-account mode and without the need to provide a verification certificate or access to the private key. A CA can be registered in Multi-account mode by multiple AWS accounts in the same AWS Region. You can register your CA in Single-account mode by providing a verification certificate and proof of ownership of CA’s private key.
### Register a CA certificate (CLI)
You can register a CA certificate in `DEFAULT` mode or `SNI_ONLY` mode. A CA can be registered in `DEFAULT` mode by one AWS account in one AWS Region. A CA can be registered in `SNI_ONLY` mode by multiple AWS accounts in the same AWS Region. For more information about CA certificate mode, see [certificateMode](https://docs.aws.amazon.com//iot/latest/apireference/API_CACertificateDescription.html#iot-Type-CACertificateDescription-certificateMode).
**Note**
We recommend that you register a CA in `SNI_ONLY` mode. You don't need to provide a verification certificate or access to the private key, and you can register the CA by multiple AWS accounts in the same AWS Region.
#### Register a CA certificate in SNI\$1ONLY mode (CLI) - Recommended
**Prerequisites**
Make sure you have the following available on your computer before you continue:
+ The root CA's certificate file (referenced in the following example as `root_CA_cert_filename.pem`)
+ [OpenSSL v1.1.1i](https://www.openssl.org/) or later
**To register a CA certificate in `SNI_ONLY` mode using the AWS CLI**
1. Register the CA certificate with AWS IoT. Using the **register-ca-certificate** command, enter the CA certificate file name. For more information, see [register-ca-certificate](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/register-ca-certificate.html) in the *AWS CLI Command Reference*.
```
aws iot register-ca-certificate \
--ca-certificate file://root_CA_cert_filename.pem \
--certificate-mode SNI_ONLY
```
If successful, this command returns the *certificateId*.
1. At this point, the CA certificate has been registered with AWS IoT but is inactive. The CA certificate must be active before you can register any client certificates that it has signed.
This step activates the CA certificate.
To activate the CA certificate, use the **update-certificate** command as follows. For more information, see [update-certificate](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-certificate.html) in the *AWS CLI Command Reference*.
```
aws iot update-ca-certificate \
--certificate-id certificateId \
--new-status ACTIVE
```
To see the status of the CA certificate, use the **describe-ca-certificate** command. For more information, see [describe-ca-certificate](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-ca-certificate.html) in the *AWS CLI Command Reference*.
#### Register a CA certificate in `DEFAULT` mode (CLI)
**Prerequisites**
Make sure you have the following available on your computer before you continue:
+ The root CA's certificate file (referenced in the following example as `root_CA_cert_filename.pem`)
+ The root CA certificate's private key file (referenced in the following example as `root_CA_key_filename.key`)
+ [OpenSSL v1.1.1i](https://www.openssl.org/) or later
**To register a CA certificate in `DEFAULT` mode using the AWS CLI**
1. To get a registration code from AWS IoT, use **get-registration-code**. Save the returned `registrationCode` to use as the `Common Name` of the private key verification certificate. For more information, see [get-registration-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/get-registration-code.html) in the *AWS CLI Command Reference*.
```
aws iot get-registration-code
```
1. Generate a key pair for the private key verification certificate:
```
openssl genrsa -out verification_cert_key_filename.key 2048
```
1. Create a certificate signing request (CSR) for the private key verification certificate. Set the `Common Name` field of the certificate to the `registrationCode` returned by **get-registration-code**.
```
openssl req -new \
-key verification_cert_key_filename.key \
-out verification_cert_csr_filename.csr
```
You are prompted for some information, including the `Common Name` for the certificate.
```
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) []:
Locality Name (for example, city) []:
Organization Name (for example, company) []:
Organizational Unit Name (for example, section) []:
Common Name (e.g. server FQDN or YOUR name) []:your_registration_code
Email Address []:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
```
1. Use the CSR to create a private key verification certificate:
```
openssl x509 -req \
-in verification_cert_csr_filename.csr \
-CA root_CA_cert_filename.pem \
-CAkey root_CA_key_filename.key \
-CAcreateserial \
-out verification_cert_filename.pem \
-days 500 -sha256
```
1. Register the CA certificate with AWS IoT. Pass in the CA certificate file name and the private key verification certificate file name to the **register-ca-certificate** command, as follows. For more information, see [register-ca-certificate](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/register-ca-certificate.html) in the *AWS CLI Command Reference*.
```
aws iot register-ca-certificate \
--ca-certificate file://root_CA_cert_filename.pem \
--verification-cert file://verification_cert_filename.pem
```
This command returns the *certificateId*, if successful.
1. At this point, the CA certificate has been registered with AWS IoT but is not active. The CA certificate must be active before you can register any client certificates it has signed.
This step activates the CA certificate.
To activate the CA certificate, use the **update-certificate** command as follows. For more information, see [update-certificate](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-certificate.html) in the *AWS CLI Command Reference*.
```
aws iot update-ca-certificate \
--certificate-id certificateId \
--new-status ACTIVE
```
To see the status of the CA certificate, use the **describe-ca-certificate** command. For more information, see [describe-ca-certificate](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-ca-certificate.html) in the *AWS CLI Command Reference*.
### Create a CA verification certificate to register the CA certificate in the console
**Note**
This procedure is only for use if you are registering a CA certificate from the AWS IoT console.
If you did not come to this procedure from the AWS IoT console, start the CA certificate registration process in the console at [Register CA certificate](https://console.aws.amazon.com//iot/home#/create/cacertificate).
Make sure you have the following available on the same computer before you continue:
+ The root CA's certificate file (referenced in the following example as `root_CA_cert_filename.pem`)
+ The root CA certificate's private key file (referenced in the following example as `root_CA_key_filename.key`)
+ [OpenSSL v1.1.1i](https://www.openssl.org/) or later
**To use the command line interface to create a CA verification certificate to register your CA certificate in the console**
1. Replace `verification_cert_key_filename.key` with the name of the verification certificate key file that you want to create (for example, **verification\$1cert.key**). Then run this command to generate a key pair for the private key verification certificate:
```
openssl genrsa -out verification_cert_key_filename.key 2048
```
1. Replace `verification_cert_key_filename.key` with the name of the key file that you created in step 1.
Replace `verification_cert_csr_filename.csr` with the name of the certificate signing request (CSR) file that you want to create. For example, **verification\$1cert.csr**.
Run this command to create the CSR file.
```
openssl req -new \
-key verification_cert_key_filename.key \
-out verification_cert_csr_filename.csr
```
The command prompts you for additional information that's explained later.
1. In the AWS IoT console, in the **Verification certificate** container, copy the registration code.
1. The information that the **openssl** command prompts you for is shown in the following example. Except for the `Common Name` field, you can enter your own values or keep them blank.
In the `Common Name` field, paste the registration code that you copied in the previous step.
```
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) []:
Locality Name (for example, city) []:
Organization Name (for example, company) []:
Organizational Unit Name (for example, section) []:
Common Name (e.g. server FQDN or YOUR name) []:your_registration_code
Email Address []:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
```
After you finish, the command creates the CSR file.
1. Replace `verification_cert_csr_filename.csr` with the `verification_cert_csr_filename.csr` you used in the previous step.
Replace `root_CA_cert_filename.pem` with the file name of the CA certificate that you want to register.
Replace `root_CA_key_filename.key` with the file name of the CA certificate's private key file.
Replace `verification_cert_filename.pem` with the file name of the verification certificate that you want to create. For example, **verification\$1cert.pem**.
```
openssl x509 -req \
-in verification_cert_csr_filename.csr \
-CA root_CA_cert_filename.pem \
-CAkey root_CA_key_filename.key \
-CAcreateserial \
-out verification_cert_filename.pem \
-days 500 -sha256
```
1. After the OpenSSL command completes, you should have these files ready to use for when you return to the console.
+ Your CA certificate file (`root_CA_cert_filename.pem` used in the previous command)
+ The verification certificate that you created in the previous step (*verification\$1cert\$1filename.pem* used in the previous command)
## Deactivate a CA certificate
When a certificate authority (CA) certificate is enabled for automatic client certificate registration, AWS IoT checks the CA certificate to make sure the CA is `ACTIVE`. If the CA certificate is `INACTIVE`, AWS IoT doesn't allow the client certificate to be registered.
By setting the CA certificate to `INACTIVE`, you prevent any new client certificates issued by the CA from being registered automatically.
**Note**
Any registered client certificates that were signed by the compromised CA certificate continue to work until you explicitly revoke each one of them.
### Deactivate a CA certificate (console)
**To deactivate a CA certificate using the AWS IoT console**
1. Sign in to the AWS Management Console and open the [AWS IoT console](https://console.aws.amazon.com/iot/home).
1. In the left navigation pane, choose **Secure**, choose **CAs**.
1. In the list of certificate authorities, find the one that you want to deactivate, and choose the ellipsis icon to open the option menu.
1. On the option menu, choose **Deactivate**.
The certificate authority should show as **Inactive** in the list.
**Note**
The AWS IoT console does not provide a way to list the certificates that were signed by the CA you deactivated. For an AWS CLI option to list those certificates, see [Deactivate a CA certificate (CLI)](#deactivate-ca-cert-cli).
### Deactivate a CA certificate (CLI)
The AWS CLI provides the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-ca-certificate.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-ca-certificate.html) command to deactivate a CA certificate.
```
aws iot update-ca-certificate \
--certificate-id certificateId \
--new-status INACTIVE
```
Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-certificates-by-ca.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-certificates-by-ca.html) command to get a list of all registered client certificates that were signed by the specified CA. For each client certificate signed by the specified CA certificate, use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-certificate.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-certificate.html) command to revoke the client certificate to prevent it from being used.
Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-ca-certificate.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-ca-certificate.html) command to see the status of the CA certificate.
# Create a client certificate using your CA certificate
You can use your own certificate authority (CA) to create client certificates. The client certificate must be registered with AWS IoT before use. For information about the registration options for your client certificates, see [Register a client certificate](register-device-cert.md).
## Create a client certificate (CLI)
**Note**
You can't perform this procedure in the AWS IoT console.
**To create a client certificate using the AWS CLI**
1. Generate a key pair.
```
openssl genrsa -out device_cert_key_filename.key 2048
```
1. Create a CSR for the client certificate.
```
openssl req -new \
-key device_cert_key_filename.key \
-out device_cert_csr_filename.csr
```
You are prompted for some information, as shown here:
```
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) []:
Locality Name (for example, city) []:
Organization Name (for example, company) []:
Organizational Unit Name (for example, section) []:
Common Name (e.g. server FQDN or YOUR name) []:
Email Address []:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
```
1. Create a client certificate from the CSR.
```
openssl x509 -req \
-in device_cert_csr_filename.csr \
-CA root_CA_cert_filename.pem \
-CAkey root_CA_key_filename.key \
-CAcreateserial \
-out device_cert_filename.pem \
-days 500 -sha256
```
At this point, the client certificate has been created, but it has not yet been registered with AWS IoT. For information about how and when to register the client certificate, see [Register a client certificate](register-device-cert.md).
# Register a client certificate
Client certificates must be registered with AWS IoT to enable communications between the client and AWS IoT. You can register each client certificate manually, or you can configure the client certificates to register automatically when the client connects to AWS IoT for the first time.
If you want your clients and devices to register their client certificates when they first connect, you must [Register your CA certificate](manage-your-CA-certs.md#register-CA-cert) used to sign the client certificate with AWS IoT in the Regions in which you want to use it. The Amazon Root CA is automatically registered with AWS IoT.
Client certificates can be shared by AWS accounts and Regions. The procedures in these topics must be performed in each account and Region in which you want to use the client certificate. The registration of a client certificate in one account or Region is not automatically recognized by another.
**Note**
Clients that use the Transport Layer Security (TLS) protocol to connect to AWS IoT must support the [Server Name Indication (SNI) extension](https://tools.ietf.org/html/rfc3546#section-3.1) to TLS. For more information, see [Transport security in AWS IoT Core](transport-security.md).
**Topics**
+ [Register a client certificate manually](manual-cert-registration.md)
+ [Register a client certificate when the client connects to AWS IoT just-in-time registration (JITR)](auto-register-device-cert.md)
# Register a client certificate manually
You can register a client certificate manually by using the AWS IoT console and AWS CLI.
The registration procedure to use depends on whether the certificate will be shared by AWS accounts and Regions. The registration of a client certificate in one account or Region is not automatically recognized by another.
The procedures in this topic must be performed in each account and Region in which you want to use the client certificate. Client certificates can be shared by AWS accounts and Regions.
## Register a client certificate signed by a registered CA (console)
**Note**
Before you perform this procedure, make sure that you have the client certificate's .pem file and that the client certificate was signed by a CA that you have [registered with AWS IoT](manage-your-CA-certs.md#register-CA-cert).
**To register an existing certificate with AWS IoT using the console**
1. Sign in to the AWS Management Console and open the [AWS IoT console](https://console.aws.amazon.com/iot/home).
1. In the navigation pane, under the **Manage** section, choose **Security**, and then choose **Certificates**.
1. On the **Certificates** page in the **Certificates** dialog box, choose **Add certificate**, and then choose **Register certificates**.
1. On the **Register certificate** page in the **Certificates to upload** dialog box, do the following:
+ Choose **CA is registered with AWS IoT**.
+ From **Choose a CA certificate**, select your **Certification authority**.
+ Choose **Register a new CA** to register a new **Certification authority** that's not registered with AWS IoT.
+ Leave **Choose a CA certificate** blank if **Amazon Root certificate authority** is your certification authority.
+ Select up to 10 certificates to upload and register with AWS IoT.
+ Use the certificate files you created in [Create AWS IoT client certificates](device-certs-create.md) and [Create a client certificate using your CA certificate](create-device-cert.md).
+ Choose **Activate** or **Deactivate**. If you choose **Deactive**, [Activate or deactivate a client certificate](activate-or-deactivate-device-cert.md) explains how to activate your certificate after certificate registration.
+ Choose **Register**.
On the **Certificates** page in the **Certificates** dialog box, your registered certificates will now appear.
## Register a client certificate signed by an unregistered CA (console)
**Note**
Before you perform this procedure, make sure that you have the client certificate's .pem file.
**To register an existing certificate with AWS IoT using the console**
1. Sign in to the AWS Management Console and open the [AWS IoT console](https://console.aws.amazon.com/iot/home).
1. In the left navigation pane, choose **Secure**, choose **Certificates**, and then choose **Create**.
1. On **Create a certificate**, locate the **Use my certificate** entry, and choose **Get started**.
1. On **Select a CA**, choose **Next**.
1. On **Register existing device certificates**, choose **Select certificates**, and select up to 10 certificate files to register.
1. After closing the file dialog box, select whether you want to activate or revoke the client certificates when you register them.
If you don't activate a certificate when it is registered, [Activate a client certificate (console)](activate-or-deactivate-device-cert.md#activate-device-cert-console) describes how to activate it later.
If a certificate is revoked when it is registered, it can't be activated later.
After you choose the certificate files to register, and select the actions to take after registration, select **Register certificates**.
The client certificates that are registered successfully appear in the list of certificates.
## Register a client certificate signed by a registered CA (CLI)
**Note**
Before you perform this procedure, make sure that you have the certificate authority (CA) .pem and the client certificate's .pem file. The client certificate must be signed by a certificate authority (CA) that you have [registered with AWS IoT](manage-your-CA-certs.md#register-CA-cert).
Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/register-certificate.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/register-certificate.html) command to register, but not activate, a client certificate.
```
aws iot register-certificate \
--certificate-pem file://device_cert_filename.pem \
--ca-certificate-pem file://ca_cert_filename.pem
```
The client certificate is registered with AWS IoT, but it is not active yet. See [Activate a client certificate (CLI)](activate-or-deactivate-device-cert.md#activate-device-cert-cli) for information on how to activate it later.
You can also activate the client certificate when you register it by using this command.
```
aws iot register-certificate \
--set-as-active \
--certificate-pem file://device_cert_filename.pem \
--ca-certificate-pem file://ca_cert_filename.pem
```
For more information about activating the certificate so that it can be used to connect to AWS IoT, see [Activate or deactivate a client certificate](activate-or-deactivate-device-cert.md)
## Register a client certificate signed by an unregistered CA (CLI)
**Note**
Before you perform this procedure, make sure that you have the certificate's .pem file.
Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/register-certificate-without-ca.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/register-certificate-without-ca.html) command to register, but not activate, a client certificate.
```
aws iot register-certificate-without-ca \
--certificate-pem file://device_cert_filename.pem
```
The client certificate is registered with AWS IoT, but it is not active yet. See [Activate a client certificate (CLI)](activate-or-deactivate-device-cert.md#activate-device-cert-cli) for information on how to activate it later.
You can also activate the client certificate when you register it by using this command.
```
aws iot register-certificate-without-ca \
--status ACTIVE \
--certificate-pem file://device_cert_filename.pem
```
For more information about activating the certificate so that it can be used to connect to AWS IoT, see [Activate or deactivate a client certificate](activate-or-deactivate-device-cert.md).
# Register a client certificate when the client connects to AWS IoT just-in-time registration (JITR)
You can configure a CA certificate to enable client certificates it has signed to register with AWS IoT automatically the first time the client connects to AWS IoT.
To register client certificates when a client connects to AWS IoT for the first time, you must enable the CA certificate for automatic registration and configure the first connection by the client to provide the required certificates.
## Configure a CA certificate to support automatic registration (console)
**To configure a CA certificate to support automatic client certificate registration using the AWS IoT console**
1. Sign in to the AWS Management Console and open the [AWS IoT console](https://console.aws.amazon.com/iot/home).
1. In the left navigation pane, choose **Secure**, choose **CAs**.
1. In the list of certificate authorities, find the one for which you want to enable automatic registration, and open the option menu by using the ellipsis icon.
1. On the option menu, choose **Enable auto-registration**.
**Note**
The auto-registration status is not shown in the list of certificate authorities. To see the auto-registration status of a certificate authority, you must open the **Details** page of the certificate authority.
## Configure a CA certificate to support automatic registration (CLI)
If you have already registered your CA certificate with AWS IoT, use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-ca-certificate.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-ca-certificate.html) command to set `autoRegistrationStatus` of the CA certificate to `ENABLE`.
```
aws iot update-ca-certificate \
--certificate-id caCertificateId \
--new-auto-registration-status ENABLE
```
If you want to enable `autoRegistrationStatus` when you register the CA certificate, use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/register-ca-certificate.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/register-ca-certificate.html) command.
```
aws iot register-ca-certificate \
--allow-auto-registration \
--ca-certificate file://root_CA_cert_filename.pem \
--verification-cert file://verification_cert_filename.pem
```
Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-ca-certificate.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-ca-certificate.html) command to see the status of the CA certificate.
## Configure the first connection by a client for automatic registration
When a client attempts to connect to AWS IoT for the first time, the client certificate signed by your CA certificate must be present on the client during the Transport Layer Security (TLS) handshake.
When the client connects to AWS IoT, use the client certificate you created in [Create AWS IoT client certificates](https://docs.aws.amazon.com/iot/latest/developerguide/device-certs-create.html) or [Create your own client certificates](https://docs.aws.amazon.com/iot/latest/developerguide/device-certs-your-own.html). AWS IoT recognizes the CA certificate as a registered CA certificate, registers the client certificate, and sets its status to `PENDING_ACTIVATION`. This means that the client certificate was automatically registered and is awaiting activation. The client certificate's state must be `ACTIVE` before it can be used to connect to AWS IoT. See [Activate or deactivate a client certificate](activate-or-deactivate-device-cert.md) for information on activating a client certificate.
**Note**
You can provision devices using AWS IoT Core just-in-time registration (JITR) feature without having to send the entire trust chain on devices' first connection to AWS IoT Core. Presenting the CA certificate is optional but the device is required to send the [Server Name Indication (SNI)](https://datatracker.ietf.org/doc/html/rfc3546#section-3.1) extension when they connect.
When AWS IoT automatically registers a certificate or when a client presents a certificate in the `PENDING_ACTIVATION` status, AWS IoT publishes a message to the following MQTT topic:
`$aws/events/certificates/registered/caCertificateId`
Where `caCertificateId` is the ID of the CA certificate that issued the client certificate.
The message published to this topic has the following structure:
```
{
"certificateId": "certificateId",
"caCertificateId": "caCertificateId",
"timestamp": timestamp,
"certificateStatus": "PENDING_ACTIVATION",
"awsAccountId": "awsAccountId",
"certificateRegistrationTimestamp": "certificateRegistrationTimestamp"
}
```
You can create a rule that listens on this topic and performs some actions. We recommend that you create a Lambda rule that verifies the client certificate is not on a certificate revocation list (CRL), activates the certificate, and creates and attaches a policy to the certificate. The policy determines which resources the client can access. If the policy you are creating requires the client ID from the connecting devices, you can use rule's clientid() function to retrieve the client ID. An example rule definition can look like the following:
```
SELECT *,
clientid() as clientid
from $aws/events/certificates/registered/caCertificateId
```
In this example, the rule subscribes to the JITR topic `$aws/events/certificates/registered/caCertificateID` and uses the clientid() function to retrieve the client ID. The rule then appends the client ID to the JITR payload. For more information about rule's clientid() function, see [clientid()](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-clientid).
For more information about how to create a Lambda rule that listens on the `$aws/events/certificates/registered/caCertificateID` topic and performs these actions, see [just-in-time registration of Client Certificates on AWS IoT](https://aws.amazon.com/blogs/iot/just-in-time-registration-of-device-certificates-on-aws-iot/).
If any error or exception occurs during the auto-registration of the client certificates, AWS IoT sends events or messages to your logs in CloudWatch Logs. For more information about setting up the logs for your account, see the [Amazon CloudWatch documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/).
# Manage client certificates
AWS IoT provides capabilities for you to manage client certificates.
**Topics**
+ [Activate or deactivate a client certificate](activate-or-deactivate-device-cert.md)
+ [Attach a thing or policy to a client certificate](attach-to-cert.md)
+ [Revoke a client certificate](revoke-ca-cert.md)
+ [Transfer a certificate to another account](transfer-cert.md)
# Activate or deactivate a client certificate
AWS IoT verifies that a client certificate is active when it authenticates a connection.
You can create and register client certificates without activating them so they can't be used until you want to use them. You can also deactivate active client certificates to disable them temporarily. Finally, you can revoke client certificates to prevent them from any future use.
## Activate a client certificate (console)
**To activate a client certificate using the AWS IoT console**
1. Sign in to the AWS Management Console and open the [AWS IoT console](https://console.aws.amazon.com/iot/home).
1. In the left navigation pane, choose **Secure**, choose **Certificates**.
1. In the list of certificates, locate the certificate that you want to activate, and open the option menu by using the ellipsis icon.
1. In the option menu, choose **Activate**.
The certificate should show as **Active** in the list of certificates.
## Deactivate a client certificate (console)
**To deactivate a client certificate using the AWS IoT console**
1. Sign in to the AWS Management Console and open the [AWS IoT console](https://console.aws.amazon.com/iot/home).
1. In the left navigation pane, choose **Secure**, choose **Certificates**.
1. In the list of certificates, locate the certificate that you want to deactivate, and open the option menu by using the ellipsis icon.
1. In the option menu, choose **Deactivate**.
The certificate should show as **Inactive** in the list of certificates.
## Activate a client certificate (CLI)
The AWS CLI provides the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-certificate.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-certificate.html) command to activate a certificate.
```
aws iot update-certificate \
--certificate-id certificateId \
--new-status ACTIVE
```
If the command was successful, the certificate's status will be `ACTIVE`. Run [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-certificate.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-certificate.html) to see the certificate's status.
```
aws iot describe-certificate \
--certificate-id certificateId
```
## Deactivate a client certificate (CLI)
The AWS CLI provides the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-certificate.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-certificate.html) command to deactivate a certificate.
```
aws iot update-certificate \
--certificate-id certificateId \
--new-status INACTIVE
```
If the command was successful, the certificate's status will be `INACTIVE`. Run [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-certificate.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-certificate.html) to see the certificate's status.
```
aws iot describe-certificate \
--certificate-id certificateId
```
# Attach a thing or policy to a client certificate
When you create and register a certificate separate from an AWS IoT thing, it will not have any policies that authorize any AWS IoT operations, nor will it be associated with any AWS IoT thing object. This section describes how to add these relationships to a registered certificate.
**Important**
To complete these procedures, you must have already created the thing or policy that you want to attach to the certificate.
The certificate authenticates a device with AWS IoT so that it can connect. Attaching the certificate to a thing resource establishes the relationship between the device (by way of the certificate) and the thing resource. To authorize the device to perform AWS IoT actions, such as to allow the device to connect and publish messages, an appropriate policy must be attached to the device's certificate.
## Attach a thing to a client certificate (console)
You will need the name of the thing object to complete this procedure.
**To attach a thing object to a registered certificate**
1. Sign in to the AWS Management Console and open the [AWS IoT console](https://console.aws.amazon.com/iot/home).
1. In the left navigation pane, choose **Secure**, choose **Certificates**.
1. In the list of certificates, locate the certificate to which you want to attach a policy, open the certificate's option menu by choosing the ellipsis icon, and choose **Attach thing**.
1. In the pop-up, locate the name of the thing you want to attach to the certificate, choose its check box, and choose **Attach**.
The thing object should now appear in the list of things on the certificate's details page.
## Attach a policy to a client certificate (console)
You will need the name of the policy object to complete this procedure.
**To attach a policy object to a registered certificate**
1. Sign in to the AWS Management Console and open the [AWS IoT console](https://console.aws.amazon.com/iot/home).
1. In the left navigation pane, choose **Secure**, choose **Certificates**.
1. In the list of certificates, locate the certificate to which you want to attach a policy, open the certificate's option menu by choosing the ellipsis icon, and choose **Attach policy**.
1. In the pop-up, locate the name of the policy you want to attach to the certificate, choose its check box, and choose **Attach**.
The policy object should now appear in the list of policies on the certificate's details page.
## Attach a thing to a client certificate (CLI)
The AWS CLI provides the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/attach-thing-principal.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/attach-thing-principal.html) command to attach a thing object to a certificate.
```
aws iot attach-thing-principal \
--principal certificateArn \
--thing-name thingName
```
## Attach a policy to a client certificate (CLI)
The AWS CLI provides the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/attach-policy.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/attach-policy.html) command to attach a policy object to a certificate.
```
aws iot attach-policy \
--target certificateArn \
--policy-name policyName
```
# Revoke a client certificate
If you detect suspicious activity on a registered client certificate, you can revoke it so that it can't be used again.
**Note**
Once a certificate is revoked, it's status can't be changed. That is, the certificate status can't be changed to `Active` or any other status.
## Revoke a client certificate (console)
**To revoke a client certificate using the AWS IoT console**
1. Sign in to the AWS Management Console and open the [AWS IoT console](https://console.aws.amazon.com/iot/home).
1. In the left navigation pane, choose **Secure**, choose **Certificates**.
1. In the list of certificates, locate the certificate that you want to revoke, and open the option menu by using the ellipsis icon.
1. In the option menu, choose **Revoke**.
If the certificate was successfully revoked, it will show as **Revoked** in the list of certificates.
## Revoke a client certificate (CLI)
The AWS CLI provides the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-certificate.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-certificate.html) command to revoke a certificate.
```
aws iot update-certificate \
--certificate-id certificateId \
--new-status REVOKED
```
If the command was successful, the certificate's status will be `REVOKED`. Run [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-certificate.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-certificate.html) to see the certificate's status.
```
aws iot describe-certificate \
--certificate-id certificateId
```
# Transfer a certificate to another account
X.509 certificates that belong to one AWS account can be transferred to another AWS account.
**To transfer an X.509 certificate from one AWS account to another**
1. [Begin a certificate transfer](#transfer-cert-init)
The certificate must be deactivated and detached from all policies and things before initiating the transfer.
1. [Accept or reject a certificate transfer](#transfer-cert-accept)
The receiving account must explicitly accept or reject the transferred certificate. After the receiving account accepts the certificate, the certificate must be activated before use.
1. [Cancel a certificate transfer](#transfer-cert-cancel)
The originating account can cancel a transfer, if the certificate has not been accepted.
## Begin a certificate transfer
You can begin to transfer a certificate to another AWS account by using the [AWS IoT console](https://console.aws.amazon.com/iot/home) or the AWS CLI.
### Begin a certificate transfer (console)
To complete this procedure, you'll need the ID of the certificate that you want to transfer.
Do this procedure from the account with the certificate to transfer.
**To begin to transfer a certificate to another AWS account**
1. Sign in to the AWS Management Console and open the [AWS IoT console](https://console.aws.amazon.com/iot/home).
1. In the left navigation pane, choose **Secure**, choose **Certificates**.
Choose the certificate with an **Active** or **Inactive** status that you want to transfer and open its details page.
1. On the certificate's **Details** page, in the **Actions** menu, if the **Deactivate** option is available, choose the **Deactivate** option to deactivate the certificate.
1. On the certificate's **Details** page, in the left menu, choose **Policies**.
1. On the certificate's **Policies** page, if there are any policies attached to the certificate, detach each one by opening the policy's options menu and choosing **Detach**.
The certificate must not have any attached policies before you continue.
1. On the certificate's **Policies** page, in the left menu, choose **Things**.
1. On the certificate's **Things** page, if there are any things attached to the certificate, detach each one by opening the thing's options menu and choosing **Detach**.
The certificate must not have any attached things before you continue.
1. On the certificate's **Things** page, in the left menu, choose **Details**.
1. On the certificate's **Details** page, in the **Actions** menu, choose **Start transfer** to open the **Start transfer** dialog box.
1. In the **Start transfer** dialog box, enter the AWS account number of the account to receive the certificate and an optional short message.
1. Choose **Start transfer** to transfer the certificate.
The console should display a message that indicates the success or failure of the transfer. If the transfer was started, the certificate's status is updated to **Transferred**.
### Begin a certificate transfer (CLI)
To complete this procedure, you'll need the *certificateId* and the *certificateArn* of the certificate that you want to transfer.
Do this procedure from the account with the certificate to transfer.
**To begin to transfer a certificate to another AWS account**
1. Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-certificate.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-certificate.html) command to deactivate the certificate.
```
aws iot update-certificate --certificate-id certificateId --new-status INACTIVE
```
1. Detach all policies.
1. Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-attached-policies.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-attached-policies.html) command to list the policies attached to the certificate.
```
aws iot list-attached-policies --target certificateArn
```
1. For each attached policy, use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/detach-policy.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/detach-policy.html) command to detach the policy.
```
aws iot detach-policy --target certificateArn --policy-name policy-name
```
1. Detach all things.
1. Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-principal-things.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-principal-things.html) command to list the things attached to the certificate.
```
aws iot list-principal-things --principal certificateArn
```
1. For each attached thing, use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/detach-thing-principal.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/detach-thing-principal.html) command to detach the thing.
```
aws iot detach-thing-principal --principal certificateArn --thing-name thing-name
```
1. Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/transfer-certificate.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/transfer-certificate.html) command to start the certificate transfer.
```
aws iot transfer-certificate --certificate-id certificateId --target-aws-account account-id
```
## Accept or reject a certificate transfer
You can accept or reject a certificate transferred to you AWS account from another AWS account by using the [AWS IoT console](https://console.aws.amazon.com/iot/home) or the AWS CLI.
### Accept or reject a certificate transfer (console)
To complete this procedure, you'll need the ID of the certificate that was transferred to your account.
Do this procedure from the account receiving the certificate that was transferred.
**To accept or reject a certificate that was transferred to your AWS account**
1. Sign in to the AWS Management Console and open the [AWS IoT console](https://console.aws.amazon.com/iot/home).
1. In the left navigation pane, choose **Secure**, choose **Certificates**.
Choose the certificate with a status of **Pending transfer** that you want to accept or reject and open its details page.
1. On the certificate's **Details** page, in the **Actions** menu,
+ To accept the certificate, choose **Accept transfer**.
+ To not accept the certificate, choose **Reject transfer**.
### Accept or reject a certificate transfer (CLI)
To complete this procedure, you'll need the *certificateId* of the certificate transfer that you want to accept or reject.
Do this procedure from the account receiving the certificate that was transferred.
**To accept or reject a certificate that was transferred to your AWS account**
1. Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/accept-certificate-transfer.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/accept-certificate-transfer.html) command to accept the certificate.
```
aws iot accept-certificate-transfer --certificate-id certificateId
```
1. Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/reject-certificate-transfer.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/reject-certificate-transfer.html) command to reject the certificate.
```
aws iot reject-certificate-transfer --certificate-id certificateId
```
## Cancel a certificate transfer
You can cancel a certificate transfer before it has been accepted by using the [AWS IoT console](https://console.aws.amazon.com/iot/home) or the AWS CLI.
### Cancel a certificate transfer (console)
To complete this procedure, you'll need the ID of the certificate transfer that you want to cancel.
Do this procedure from the account that initiated the certificate transfer.
**To cancel a certificate transfer**
1. Sign in to the AWS Management Console and open the [AWS IoT console](https://console.aws.amazon.com/iot/home).
1. In the left navigation pane, choose **Secure**, choose **Certificates**.
Choose the certificate with **Transferred** status whose transfer you want to cancel and open its options menu.
1. On the certificate's options menu, choose the **Revoke transfer** option to cancel the certificate transfer.
**Important**
Be careful not to mistake the **Revoke transfer** option with the **Revoke** option.
The **Revoke transfer** option cancels the certificate transfer, while the **Revoke** option makes the certificate irreversibly unusable by AWS IoT.
### Cancel a certificate transfer (CLI)
To complete this procedure, you'll need the *certificateId* of the certificate transfer that you want to cancel.
Do this procedure from the account that initiated the certificate transfer.
Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/cancel-certificate-transfer.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/cancel-certificate-transfer.html) command to cancel the certificate transfer.
```
aws iot cancel-certificate-transfer --certificate-id certificateId
```
# Custom client certificate validation
AWS 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 AWS 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)](https://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol) or [Certificate Revocation Lists (CRL)](https://en.wikipedia.org/wiki/Certificate_revocation_list) 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](protocols.md#connection-protocol-auth-mode) must be X.509 certificate. In addition, clients must provide the [Server Name Indication (SNI)](https://www.rfc-editor.org/rfc/rfc3546#section-3.1) extension when connecting to AWS IoT Core.
**Note**
This feature is not supported in the AWS GovCloud (US) Regions.
**Topics**
+ [Step 1: Register your X.509 client certificates with AWS IoT Core](#client-auth-cert-verification)
+ [Step 2: Create a Lambda function](#customize-client-auth-lambda)
+ [Step 3: Authorize AWS IoT to invoke your Lambda function](#customize-client-configuration-grant-permission)
+ [Step 4: Set authentication configuration for a domain](#customize-client-configuration)
## Step 1: Register your X.509 client certificates with AWS IoT Core
If you haven't done this already, register and activate your [X.509 client certificates](https://docs.aws.amazon.com//iot/latest/developerguide/x509-client-certs.html) with AWS IoT Core. Otherwise, skip to the next step.
To register and activate your client certificates with AWS IoT Core, follow the steps:
1. If you [create client certificates directly with AWS IoT](https://docs.aws.amazon.com//iot/latest/developerguide/device-certs-create.html). These client certificates will be automatically registered with AWS IoT Core.
1. If you [create your own client certificates](https://docs.aws.amazon.com//iot/latest/developerguide/device-certs-your-own.html), follow [these instructions to register them with AWS IoT Core](https://docs.aws.amazon.com//iot/latest/developerguide/register-device-cert.html).
1. To activate your client certificates, follow [these instructions](https://docs.aws.amazon.com//iot/latest/developerguide/activate-or-deactivate-device-cert.html).
## 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](https://docs.aws.amazon.com//lambda/latest/dg/getting-started.html). 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"
]
}
```
`connectionMetadata`
Metadata or additional information related to the client's connection to AWS IoT Core.
`principalId`
The principal identifier associated with the client in the TLS connection.
`serverName`
The [Server Name Indication (SNI)](https://www.rfc-editor.org/rfc/rfc3546#section-3.1) hostname string. AWS IoT Core requires devices to send the [SNI extension](https://www.rfc-editor.org/rfc/rfc3546#section-3.1) to the Transport Layer Security (TLS) protocol and provide the complete endpoint address in the `host_name` field.
`clientCertificateChain`
The array of strings that represents the client's X.509 certificate chain.
**Lambda function response example**
```
{
"isAuthenticated": "boolean"
}
```
`isAuthenticated`
A Boolean value that indicates whether the request is authenticated.
**Note**
In the Lambda response, `isAuthenticated` must be `true` to proceed to further authentication and authorization. Otherwise, the IoT client certificate can be disabled and custom authentication with X.509 client certificates can be blocked for further authentication and authorization.
## Step 3: Authorize AWS IoT to invoke your Lambda function
After creating the Lambda function, you must grant permission for AWS IoT to invoke it, by using the [add-permission](https://docs.aws.amazon.com//cli/latest/reference/lambda/add-permission.html) CLI command. Note that this Lambda function will be invoked for every connect attempt to your configured endpoint. For more information, see [Authorizing AWS IoT to invoke your Lambda function](custom-auth-authorize.md).
## Step 4: Set authentication configuration for a domain
The following section describes how to set authentication configuration for a custom domain using the AWS CLI.
### Set client certificate configuration for a domain (CLI)
If you don't have a domain configuration, use the [https://docs.aws.amazon.com//cli/latest/reference/iot/create-domain-configuration.html](https://docs.aws.amazon.com//cli/latest/reference/iot/create-domain-configuration.html) CLI command to create one. If you already have a domain configuration, use the [https://docs.aws.amazon.com//cli/latest/reference/iot/update-domain-configuration.html](https://docs.aws.amazon.com//cli/latest/reference/iot/update-domain-configuration.html) 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"}'
```
`domain-configuration-name`
The name of the domain configuration.
`authentication-type`
The authentication type of the domain configuration. For more information, see [choosing an authentication type](protocols.md#connection-protocol-auth-mode).
`application-protocol`
The application protocol which devices use to communicate with AWS IoT Core. For more information, see [choosing an application protocol](protocols.md#protocol-selection).
`client-certificate-config`
An object that specifies the client authentication configuration for a domain.
`clientCertificateCallbackArn`
The Amazon Resource Name (ARN) of the Lambda function that AWS IoT invokes in TLS layer when new connection is being established. To customize client authentication to perform custom client certificate validation, you must add the ARN of the Lambda function that you've created in the previous step.
For more information, see [CreateDomainConfiguration](https://docs.aws.amazon.com//iot/latest/apireference/API_CreateDomainConfiguration.html) and [UpdateDomainConfiguration](https://docs.aws.amazon.com//iot/latest/apireference/API_UpdateDomainConfiguration.html) from the *AWS IoT API Reference*. For more information about domain configurations, see [Domain configurations](https://docs.aws.amazon.com//iot/latest/developerguide/iot-custom-endpoints-configurable.html).
# IAM users, groups, and roles
IAM users, groups, and roles are the standard mechanisms for managing identity and authentication in AWS. You can use them to connect to AWS IoT HTTP interfaces using the AWS SDK and AWS CLI.
IAM roles also allow AWS IoT to access other AWS resources in your account on your behalf. For example, if you want to have a device publish its state to a DynamoDB table, IAM roles allow AWS IoT to interact with Amazon DynamoDB. For more information, see [IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html).
For message broker connections over HTTP, AWS IoT authenticates users, groups, and roles using the Signature Version 4 signing process. For information, see [Signing AWS API Requests](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html).
When authenticating requests using query parameters with [temporary security credentials provided by AWS Security Token Service (AWS STS)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html), do not include `X-Amz-Security-Token` in the canonical query string when calculating the signature. Instead, append `X-Amz-Security-Token` as a query parameter after the signature has been computed. This differs from some other AWS services that require the security token to be part of the canonical request. For more information, see [ Signing requests with temporary security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html#temporary-security-credentials).
**Note**
The AWS IoT Device SDKs handle this signing behavior automatically. If you are implementing custom signing code, refer to the SDK source for reference:
[AWS IoT Device SDK for Python v2](https://github.com/aws/aws-iot-device-sdk-python-v2/blob/main/awsiot/mqtt_connection_builder.py) — see `websockets_with_default_aws_signing()`, which sets `omit_session_token=True`
[AWS IoT Device SDK for Java v2](https://github.com/aws/aws-iot-device-sdk-java-v2/blob/main/sdk/src/main/java/software/amazon/awssdk/iot/AwsIotMqttConnectionBuilder.java) — see `setOmitSessionToken(true)`
When using AWS Signature Version 4 with AWS IoT, clients must support the following in their TLS implementation:
+ TLS 1.2
+ SHA-256 RSA certificate signature validation
+ One of the cipher suites from the TLS cipher suite support section
For information, see [Identity and access management for AWS IoT](security-iam.md).
# Amazon Cognito identities
Amazon Cognito Identity enables you to create temporary, limited privilege AWS credentials for use in mobile and web applications. When you use Amazon Cognito Identity, create identity pools that create unique identities for your users and authenticate them with identity providers like Login with Amazon, Facebook, and Google. You can also use Amazon Cognito identities with your own developer authenticated identities. For more information, see [ Amazon Cognito Identity](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html).
To use Amazon Cognito Identity, define an Amazon Cognito identity pool that is associated with an IAM role. The IAM role is associated with an IAM policy that grants identities from your identity pool permission to access AWS resources like calling AWS services.
Amazon Cognito Identity creates unauthenticated and authenticated identities. Unauthenticated identities are used for guest users in a mobile or web application who want to use the app without signing in. Unauthenticated users are granted only those permissions specified in the IAM policy associated with the identity pool.
When you use authenticated identities, in addition to the IAM policy attached to the identity pool, you must attach an AWS IoT policy to an Amazon Cognito Identity. To attach an AWS IoT policy, use the [ AttachPolicy](https://docs.aws.amazon.com/iot/latest/apireference/API_AttachPolicy.html) API and give permissions to an individual user of your AWS IoT application. You can use the AWS IoT policy to assign fine-grained permissions for specific customers and their devices.
Authenticated and unauthenticated users are different identity types. If you don't attach an AWS IoT policy to the Amazon Cognito Identity, an authenticated user fails authorization in AWS IoT and doesn't have access to AWS IoT resources and actions. For more information about creating policies for Amazon Cognito identities, see [Publish/Subscribe policy examples](pub-sub-policy.md) and [Authorization with Amazon Cognito identities](cog-iot-policies.md).
![\[Application accessing a device with Amazon Cognito Identity.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/device-cognito.png)