Usage

Process

Figure 1 Custom authentication process

Click to enlarge

Procedure

Use FunctionGraph to create a custom authentication function.

Figure 2 Function list - Creating a function

Figure 3 Creating a function - Parameters

Configure custom authentication on the console for storage, management, and maintenance. You can configure up to 10 custom authenticators and choose one as the default.

Figure 4 Custom authentication - Creating an authenticator

Click to enlarge

**Table 1** Custom authentication parameters
Parameter	Mandatory	Description
Authentication Name	Yes	Enter a custom authenticator name.
Function	Yes	Select the corresponding function from the list created with FunctionGraph in 1.
Status	Yes	To use an authenticator, you must first enable it as it is disabled by default.
Signature Authentication	Yes	After this function is enabled (by default), authentication information that does not meet signature requirements will be rejected to reduce invalid function calls.
Token	No	Token for signature authentication. Used to check whether a device's signature information is valid.
Public Key	No	Public key for signature authentication. Used to check whether a device's signature information is valid.
Default Mode	Yes	After this function is enabled (disabled by default), if the username in an authentication request does not contain the authorizer_name parameter, this authenticator is used.
Caching	Yes	Whether to cache FunctionGraph authentication results (disabled by default). The cache duration ranges from 300 minutes to 1 day.

The device initiates a CONNECT request using MQTT. The request must carry the username parameter, which contains optional parameters related to custom authentication.

Username format requirements: Remove braces ({}) and separate each parameter by a vertical bar (|). Do not add vertical bars (|) in the parameter content.

{device-identifier}|authorizer-name={authorizer-name}|authorizer-signature={token-signature}|signing-token={token-value}
Example:
659b70a0bd3f665a471e5ec9_auth|authorizer-name=Test_auth_1|authorizer-signature=***|signing-token=tokenValue

**Table 2** Description of the username parameter
Parameter	Mandatory	Description
device-identifier	Yes	Device identifier. You are advised to set it to the device ID.
authorizer-name	No	Custom authenticator name, which must be the same as the configured authenticator. If this parameter is not carried, the system will use either the default custom authenticator (if configured) or the original secret/certificate authentication mode.
authorizer-signature	No	This parameter is mandatory when the signature verification function is enabled. Obtain the value by encrypting the private key and signing-token. The value must be the same as the authentication name used in 2.
signing-token	No	This parameter is mandatory when the signature verification function is enabled. The value is used for signature verification and must be the same as the token value used in 2.

Run the following command to obtain authorizer-signature:

echo -n {signing-token} | openssl dgst -sha256 -sign {private key} | openssl base64

**Table 3** Command parameters
Parameter	Description
echo -n {signing-token}	Run the echo command to output the value of signing-token and use the -n parameter to remove the newline character at the end. The value of signing-token must be the same as that of the token in 2.
openssl dgst -sha256 -sign	Hash the input data with the SHA-256 algorithm.
{private key}	Private key encrypted using the RSA algorithm. You can upload a private key file in .pem or .key format.
openssl base64	Encode the signature result using Base64 for transmission and storage.

When receiving an authentication request, IoTDA determines whether to use the custom authentication mode based on the username parameter and related configuration.
1. The system checks whether the username carries the custom authentication name. If yes, the authenticator processing function is matched based on the name. If no, the default custom authenticator is used to match the authentication processing function. If no matching is found, the original key/certificate authentication mode is used.
2. The system checks whether signature verification is enabled. If yes, the system checks whether the signature information carried in the username can be verified. If the verification fails, an authentication failure message is returned.
3. After the processing function is matched, the device authentication information (that is, the input parameter event of 5) is carried and an authentication request is sent to FunctionGraph through the function URN.

Develop based on the processing function created with FunctionGraph in 1. The function return result must meet the following requirements:

exports.handler = async (event, context) => {
    console.log("username=" + event.username);
    // Enter the validation logic.
    

    // Returned JSON format (fixed)
    const authRes = {
        "result_code": 200,
        "result_desc": "successful",
        "refresh_seconds": 300,
        "device": {
            "device_id": "myDeviceId",
            "provision_enable": true,
            "provisioning_resource": {
                "device_name": "myDeviceName",
                "node_id": "myNodeId",
                "product_id": "myProductId",
                "app_id": "customization0000000000000000000",
                "policy_ids": ["657a4e0c2ea0cb2cd831d12a", "657a4e0c2ea0cb2cd831d12b"]
            }
        }
    }
    return JSON.stringify(authRes);
}

Request parameters (event, in JSON format) of the function:

{
    "username": "myUserName",
    "password": "myPassword",
    "client_id": "myClientId",
    "certificate_info": {
        "common_name": "",
        "fingerprint": "123"
    }
}

**Table 4** Request parameters
Parameter	Type	Mandatory	Description
username	String	Yes	The username field in the MQTT CONNECT message, the format of which is the same as that of the username field in 3.
password	String	Yes	password parameter in the MQTT CONNECT message.
client_id	String	Yes	clientId parameter in the MQTT CONNECT message.
certificate_info	JsonObject	No	Device certificate information in the MQTT CONNECT message.

**Table 5** certificate_info: certificate information
Parameter	Type	Mandatory	Description
common_name	String	Yes	Common name parsed from the device certificate carried by the device.
fingerprint	String	Yes	Fingerprint information parsed from the device certificate carried by the device.

**Table 6** Returned parameter information
Parameter	Type	Mandatory	Description
result_code	Integer	Yes	Authentication result code. If 200 is returned, the authentication is successful.
result_desc	String	No	Description of the authentication result.
refresh_seconds	Integer	No	Cache duration of the authentication result, in seconds.
device	JsonObject	No	Device information when the authentication is successful. When self-registration is enabled, the platform creates a device based on the device information provided if the corresponding device ID does not exist.

**Table 7** Device information
Parameter	Type	Mandatory	Description
device_id	String	Yes	A globally unique device ID. This parameter is mandatory in both self-registration and non-self-registration scenarios. If this parameter is carried, the platform sets the device ID to the value of this parameter. Recommended format: product_id + _ + node_id. The value can contain up to 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed. You are advised to use at least 4 characters.
provision_enable	Boolean	No	Whether to enable self-registration. Default value: false.
provisioning_resource	JsonObject	Mandatory in the self-registration scenario	Self-registration parameters.

**Table 8** provisioning_resource self-registration parameters
Parameter	Type	Mandatory	Description
device_name	String	No	Device name, which uniquely identifies a device in a resource space. The value can contain up to 256 characters. Only letters, digits, and special characters (_?'#().,&%@!-) are allowed. You are advised to use at least 4 characters. Min. characters: 1 Max. characters: 256
node_id	String	Yes	Device identifier. This parameter is set to the IMEI, MAC address, or serial number. It contains 1 to 64 characters (recommended length: 4), including letters, digits, hyphens (-), and underscores (_). (Note: Information cannot be modified once it is hardcoded to NB-IoT modules. Therefore, the node ID of an NB-IoT must be globally unique.)
product_id	String	Yes	Unique ID of the product associated with the device. The value is allocated by IoTDA after the product is created. The value can contain up to 256 characters. Only letters, digits, and special characters (_?'#().,&%@!-) are allowed. You are advised to use at least 4 characters. Min. characters: 1 Max. characters: 256
app_id	String	Yes	Resource space ID, which specifies the resource space to which the created device belongs. The value is a string of no more than 36 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.
policy_ids	List<String>	No	Topic policy ID.

Figure 5 Compiling a function - Deployment
Click to enlarge

After receiving the result, FunctionGraph checks whether the self-registration is required. If yes, FunctionGraph triggers automatic device registration. By default, all self-registered devices are authenticated using secrets, which are randomly generated. After receiving the authentication result, IoTDA proceeds with the subsequent process.