Scenario: Create a Digital Twin Instance that uses a mTLS Certificate

If you receive data from a device, then you must use authentication with your digital twin instance. This scenario explains how to use a certificate to authenticate when you create a digital twin instance for a device.

Mutual TLS (mTLS) is a security protocol that ensures both the client and server authenticate each other's identity during communication. Unlike standard TLS, which authenticates only the server, mTLS adds a layer of trust by requiring both client and server to present valid certificates.
  1. Create a Certificate Authority
  2. Generate a new private key
  3. Create a certificate that's managed externally
  4. Create a digital twin instance that uses a certificate
  5. Get a digital twin's instance details
  6. Subscribe to a topic using MQTTx
  7. View device data in APEX

Best practices
  • Rotate certificates often.
  • Limit certificate validity periods.
  • Store private keys using Vaults.
  • Monitor and audit connection attempts.

Before you Begin

Make sure you have the required permissions. An administrator grants access by creating the required policies. For more information, see Prerequisites and Policy Details for the Internet of Things (IoT) Platform.

Step 1: Create a Certificate Authority

Use the Certificates service to create a root certificate authority (CA) or a subordinate CA. For more information, see Creating a Certificate Authority.

Creating a CA requires you to have access to an existing hardware-protected, asymmetric encryption key from the Oracle Cloud Infrastructure (OCI) Vault service. For more information, see Overview of Vault.

This example task explains how to issue a certificate with a private key that you manage externally using a subordinate CA.

You must already have a root CA to create a subordinate CA.

  1. Log in as an Administrator, with the correct policies to perform these actions. You must have the appropriate level of security access to create a CA. For more information, see Required IAM Policy.
  2. On the Certificate Authorities list page, select Create Certificate Authority. If you need help finding the list page, see Listing Certificate Authorities.
  3. Select Compartment, and then select the compartment where you want to create the CA.
  4. Under Certificate Authority Type, select the type Subordinate Certificate Authority: any CA that's not the root CA in a hierarchy containing other CAs.
  5. (Optional) Enter a unique display name for the CA. This name helps you identify the CA for administrative purposes but doesn't appear as part of the CA certificate. Avoid entering confidential information.
    Note

    No two CAs in a tenancy can share the same name, including CAs pending deletion.
  6. (Optional) To apply tags, select Show Tagging Options. For more information about tags, see Resource Tags.
  7. Select Next.
  8. Enter subject information. Subject information includes at least a common name (CN) to identify the owner of the CA certificate. Depending on the certificate's intended use, the subject might identify a person, organization, computer endpoint, or a device. The format of the subject information must conform to RFC 5280 standards. You can use wildcards to issue a certificate for multiple domain or subdomain names.
  9. Select Next.
  10. Under Authority Configuration, confirm or select the vault that contains the encryption key that you want to use for the CA certificate. Optionally, select Change Compartment to specify a different compartment. For information about creating and managing vaults, see Managing Vaults.
  11. Under Key, select the key in the vault that you want to use. The list includes only the asymmetric keys in the vault because Certificates only supports asymmetric keys. You can select from Rivest-Shamir-Adleman (RSA) keys that are 2,048 bits or 4,096 bits. You can also select elliptic curve cryptography digital signature algorithm (ECDSA) keys that have an elliptic curve ID of NIST_P384. Specifically, the list includes only these types of asymmetric keys that are protected by a hardware security module (HSM). Certificates don't support the use of software-protected keys. For more information about creating and managing keys, see Managing Keys.
  12. Under Signing Algorithm, depending on the key algorithm family select one of the following options:
    • SHA256_WITH_RSA: RSA key with a SHA-256 hash function
    • SHA384_WITH_RSA: RSA key with a SHA-384 hash function
    • SHA512_WITH_RSA: RSA key with a SHA-512 hash function
    • SHA256_WITH_ECDSA: ECDSA key with a SHA-256 hash function
    • SHA384_WITH_ECDSA: ECDSA key with a SHA-384 hash function
    • SHA512_WITH_ECDSA: ECDSA key with a SHA-512 hash function
  13. Select Next.
  14. Configure the expiry rule. Under Maximum Validity Duration for Certificates (Days), specify the maximum number of days that a certificate issued by this CA can be valid. We strongly recommend a validity period of no more than 90 days.
  15. On the Revocation Configuration page, if you don't want to configure a certificate revocation list (CRL), select the Skip Revocation checkbox.
  16. Select Next.
  17. Confirm that the information is correct, and then select Create Certificate Authority. It can take a few minutes to create certificate-related resources.
  18. If the Certificate Authority was successfully created, then the summary details is displayed.

Step 2: Generate a New Private Key

Create a private key and a certificate signing request (CSR) using OpenSSL.

Note

For security, consider performing this step on the device to keep the key private and never share the key externally.
  1. Use this command to generate a new private key private.pem and a certificate signing request csr.pem with RSA 2048-bit encryption. This example shows using the -nodes parameter that specifies without password protection and uses the v3_req extensions.
    openssl req -nodes -newkey rsa:2048 -keyout private.pem -out csr.pem -extensions v3_req
  2. This example shows the certificate request input fields and example values. Enter information that will be incorporated into your certificate report, as a Distinguished Name (DN).

    Enter the common name. You can find the common name on the Subject Information tab of the Certificate details page, see step 8 Create a Certificate Authority or for help finding the certificate details page, see Listing Certificates:
    Country Name (2 letter code) []: US
    State or Province Name (full name) [Some-State]:
    Locality Name (eg, city) []:
    Organization Name (eg, company) []:
    Organizational Unit Name (eg, section) []:
    Common Name (Enter common name from the certificate details.) []:common-name
    Email Address [your@email.com]:
    
    Please enter the following 'extra' attributes
    to be sent with your certificate request
    A challenge password []:
    An optional company name []:

Step 3: Create a Certificate that's Managed Externally

You can generate a certificate signing request (CSR) and private key on the server where you plan to install the certificate, and then submit that CSR to a CA to issue a certificate, while managing the private key externally.

This task describes how to issue a certificate with a private key that you manage externally. For more information on other ways to use a certificate, see Creating a Certificate to Manage Externally and Managing Certificates.
  1. In the Console, open the navigation menu, select Identity & Security.
  2. On the Certificates list page, the list of Certificate Authority for a specific compartment is displayed.
  3. Find the Certificate you want to work with, select the Actions menu at the end of the row.
  4. Select Issue Certificate.
  5. Under Certificate Type, to issue a certificate from a Certificates service CA that's managed by an external, third-party CA, select Issued by internal CA, managed externally.
  6. Enter a unique display name for the certificate. Avoid entering confidential information.
    Note

    No two certificates in the tenancy can share the same name, including certificates pending deletion.
  7. (Optional) Enter a description to help identify the certificate. Avoid entering confidential information.
  8. For certificates that a third-party CA manages, you don't need to provide subject information. Instead, select Next.
  9. Under Certificate Signing Request, provide certificate contents by selecting Upload File, and then select Select One to upload the certificate as a file in PEM format.
  10. Or select Paste Content, and then select the text box to paste the certificate contents directly.
  11. Select Next.
  12. You can't configure automatic renewal for certificates that the Certificates service doesn't manage. Select Next to continue.
  13. Verify the summary information is correct, and then select Create Certificate.
  14. View the Certificate details page opens. Under the Versions, find the name of the certificate you want to view, go to the Actions menu at the end of the row, select View Content. For more information, see Viewing Certificate Details.
  15. For both the Certificate PEM and the Certificate Chain PEM select Download and Save to save the files.
  16. On the Certificate details page, go to the Subject information tab, copy the Common Name for the certificate to use in the next step.

Step 4: Create a Digital Twin Instance that uses a Certificate

To authenticate a device to send data you can create a digital twin instance using the --auth-id parameter and the <certificate-OCID> created in the previous step.

Use this command and parameters to create a digital twin instance. Replace the <common-name-for-the-certificate>. Replace the <certificate-OCID> with the Certificate OCID for your environment. Find these values on the Certificate details. For more information, see Viewing Certificate Details:

iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --auth-id <certificate-OCID> --external-key <common-name-from-certificate-details>

For a complete list of CLI parameters, see oci iot digital-twin-instance create and see Creating a Digital Twin Instance for more information.

Optional Step 5: Get a Digital Twin's Instance Details

Use this command to view the details for a digital twin instance. The response contains the digital twin's instance OCID.
oci iot digital-twin-instance get --digital-twin-instance-id <digital-twin-instance-OCID>
For more information, see Getting a Digital Twin's Instance Details.

Step 6: Subscribe to a topic using MQTTx

Depending on your scenario, you can connect to the digital twin instance using MQTT, HTTPs, or using WebSocket. This example shows how to connect using MQTTX. For more example scenarios, see Connecting a Device.

To test the connection:

  1. Enter the device host as the host, for example:
    mqtts://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com
  2. Enter the port: 8883
  3. Client ID: your-client-id
  4. Clean Start: True
  5. Turn on the toggle to enable TLS.
  6. Select the option: CA or Self signed certificates
  7. Enter the client certificate file location, from step 15 in Create a Certificate that's Managed Externally: your-certificate.pem
  8. Enter the client key file location, from step 1 in Generate a New Private Key: your-private-key.pem
  9. Select Connect.

    MQTTx

    Connect using MQTTx.

  10. Select New Subscription to receive data from a device.
  11. Enter the endpoint as the Topic.
  12. This example shows messages published to the /endpoints/4321 topic, at Quality of Service (QoS) level 1. topic:
    {
      "pulse": 300,
      "s02": 400
    }
    {
      "test": 100
    }

    Subscribe to a topic in MQTTx.

Optional Step 7: Monitor the IoT Data in APEX

If you configured access to view your data in APEX and the device sent raw data, then you can use this SQL statement to view digital twin instance raw data response in APEX.
select * from <domain-short-id-from-device-host>__IOT.RAW_DATA
where digital_twin_instance_id = '<digital-twin-instance-ocid>'