Create an MQTT cloud gateway

Add a cloud gateway

1. Log on to the IoT Platform console.

2. On the Instance Overview page, click the target Enterprise instance of the Exclusive Edition.

3. In the navigation pane on the left, choose Device Management > Cloud Gateway, and then click Add Cloud Gateway.

4. Configure the Basic Information parameters and click Next.

   Parameter	Description
   Cloud Gateway Name	Enter a name for the cloud gateway. The name must be unique within the instance. The name can be 4 to 30 characters in length and can contain Chinese characters, Japanese characters, letters, digits, and underscores (_). A Chinese or Japanese character is counted as two characters.
   Protocol	Select MQTT.
   Custom Port Number	The value must be an integer from 1024 to 65535. The default port number is 1883.
   Enable Data Parsing	Specify whether to enable data parsing for cloud gateway devices. IoT Platform transmits data from cloud gateway devices in pass-through mode. If needed, you can enable data parsing and implement the transformPayload() method in the data parsing script to convert raw device data into standard JSON or the Alink protocol format of a Thing Specification Language (TSL) model. For more information, see What is message parsing?.
   Authentication Type	One-party Authentication Import device authentication information (UserName, Password, and SN) into IoT Platform, which then authenticates devices based on this information. Third-party Authentication Select Alibaba Cloud Function Compute or an external HTTPS authentication method. For more information about Alibaba Cloud Function Compute (FC), see What is Function Compute? Alibaba Cloud FC: Set the Device Authentication FC Service, Device Authentication FC Function, and Authorization parameters. You can select an existing FC function or create a new one. The request and response parameters of the authentication function must comply with the specifications. You can specify a custom function name. For a description of the request and response parameters of the authentication function, see Table 1. FC authentication function description. Click Create Service to go to the Function Compute console and create a service. For more information about services, see Manage services. Click Create Function to go to the Function Compute console and create a function. For more information about functions, see Manage functions. If you have not created the AliyunIOTAccessingFCRole role, click Create RAM Role to go to the Resource Access Management (RAM) console. For more information about how to create a role and an authorization policy, see Create a RAM role. External HTTPS: You must configure the Device Authentication HTTPS URL. You can also configure Custom Authentication Parameters. The device authentication URL must start with https://. IoT Platform calls your custom device authentication service over HTTPS. The request and response parameters of the HTTPS call must comply with the specifications. For more information, see Table 2. HTTPS authentication parameter description. You can configure up to 10 custom authentication parameters in Key:Value format. Parameter Key: The parameter name. The name can be up to 64 characters in length. Parameter Value: The parameter value. The value can be up to 64 characters in length. You can set this to a variable in the ${Variable name} format. The following variables are supported: ${username}: The MQTT userName that the device uploads when it establishes a connection. ${password}: The MQTT password that the device uploads when it establishes a connection. ${clientId}: The MQTT Client ID information that the device uploads when it establishes a connection. ${cert.***}: The certificate information. `***` can be `cn`, `serial`, or `issuer`. ${userProperties.***}: The custom `UserProperty` data in the Connect message. `***` is a custom field identifier.
   Enable X.509 certificate-based device verification	Enable X.509 certificate-based device verification Configure Enable OCSP: Disable OCSP Verification for Server Certificate OCSP Verification for Client Certificate Client and Server-side OCSP Verification Note Online Certificate Status Protocol (OCSP) is an Internet protocol used to query a certificate authority (CA) about the revocation status of a certificate. OCSP verification for a client certificate is performed when the client sends a message. If the certificate is revoked, the server actively closes the connection. The default cache duration for the server-side OCSP Stapling feature is 5 to 60 minutes. After the cache expires, OCSP Stapling does not take effect for the first access request until the OCSP Stapling information is obtained again. Disable X.509 certificate-based device verification Configure Enable OCSP: Disabled OCSP Verification for Server Certificate Note Online Certificate Status Protocol (OCSP) is an Internet protocol used to query a certificate authority (CA) about the revocation status of a certificate. OCSP verification for a client certificate is performed when the client sends a message. If the certificate is revoked, the server actively closes the connection. The default cache duration for the server-side OCSP Stapling feature is 5 to 60 minutes. After the cache expires, OCSP Stapling does not take effect for the first access request until the OCSP Stapling information is obtained again.

   Table 1. FC authentication function description

   Parameter type	Parameter name	Data type	Required	Description
   Request parameters	userName	String	Yes	The MQTT userName that the device uploads when it establishes a connection. The userName must be 4 to 32 characters in length and can contain letters, digits, hyphens (-), underscores (_), at signs (@), periods (.), and colons (:). The userName must be unique for the product.
   	password	String	Yes	The MQTT password that the device uploads when it establishes a connection. The password must be 1 to 32 characters in length and can contain letters, digits, hyphens (-), underscores (_), at signs (@), periods (.), and colons (:).
   	clientId	String	Yes	The MQTT Client ID information that the device uploads when it establishes a connection.
   	certificateCommonName	String	No	The commonName field in the X.509 certificate specification. Upload this parameter when you use an X.509 digital certificate for device identity authentication.
   Response parameters	result	String	Yes	Indicates whether the authentication is successful. `true` indicates success. `false` indicates failure.
   	message	String	No	The error message that is returned if the authentication fails.
   	deviceName	String	No	The device name that corresponds to the userName if the authentication is successful. When a device establishes a connection for the first time, IoT Platform automatically creates a device based on the returned deviceName value.

   Sample response parameters for the FC authentication function:

   {
       "result":"true",
       "deviceName":"device_TH",
       "message":""
   }

   Table 2. HTTPS authentication parameter description

   Parameter type	Parameter name	Data type	Required	Description	Example
   Request method	Method	String	Yes	The request method is POST.	POST Content-Type: application/json body:{ "username": "UN001", "password": "PW001", "certificateCommonName": "CN001" }
   Header	Content-Type	String	Yes	The data encoding format in the HTTPS header. Only application/json is supported. If you use another encoding format, a parameter error is returned.
   Request parameter Body	username	String	Yes	The MQTT username that the device uploads when it establishes a connection. The username must be 4 to 32 characters in length and can contain letters, digits, hyphens (-), underscores (_), at signs (@), periods (.), and colons (:). The username must be unique for the product.
   	password	String	Yes	The MQTT password that the device uploads when it establishes a connection. The password must be 1 to 32 characters in length and can contain letters, digits, hyphens (-), underscores (_), at signs (@), periods (.), and colons (:).
   	certificateCommonName	String	No	The commonName field in the X.509 certificate specification. Upload this parameter when you use an X.509 digital certificate for device identity authentication.
   Response parameter Body	deviceName	String	Yes	The device name that corresponds to the username if the authentication is successful. When a device establishes a connection for the first time, IoT Platform automatically creates a device based on the returned devicename value.	body:{ "deviceName": "device_TH" }

5. Configure the settings on the Certificate Configuration page and click Finish.

   Important

   IoT Platform supports private CAs that use RSA, ECC, and the SM2, SM3, and SM4 Chinese cryptographic algorithms.

   Use Alibaba Cloud PCA service

   Important

   If you enabled OCSP in the previous step, you cannot use the Alibaba Cloud PCA service. You can only enter the certificate manually.

   You can use an existing Private Certificate Authority (PCA) or create a new one. For more information about the PCA service, see PCA service description and usage process.

   1. Configure Server Certificate and Private Key of Server Certificate.

   2. If you enable X.509 certificate-based device verification, you must also configure Device Certificate.

   3. If you set OCSP Verification Method to OCSP Verification for Server Certificate or Client and Server-side OCSP Verification, Trusted Certificate defaults to the server's root certificate.

   Manual Input

   You can use a self-signed CA certificate. For more information about how to issue a custom certificate, see Issue a custom certificate.

   Important

   The certificates configured in this step must be in the PEM format.

   1. Configure Server Certificate and Private Key of Server Certificate.

   2. If you enable X.509 certificate-based device verification, you must also configure Device Root Certificate.

   3. If you set OCSP Verification Method to OCSP Verification for Server Certificate or Client and Server-side OCSP Verification, Trusted Certificate defaults to the server's root certificate.

6. In the cloud gateway list, view the gateway details, including the name, ID, gateway URL, status, and associated product.

   Important

   Save the gateway URL. Replace the MQTT endpoint that the device uses to connect to IoT Platform with this URL. You can set the gateway URL as the new endpoint directly or configure a CNAME record to resolve the original endpoint to this gateway URL.

   

Optional: Edit a cloud gateway

After you create a cloud gateway, find it in the cloud gateway list and click Edit in the Actions column to modify the gateway name, certificate information, or FC authentication function.