Certificate authority

Currently, X.509 certificate authentication in Cumulocity requires customers to manage their own PKI infrastructure, creating a significant adoption barrier. Without a built-in way to issue and manage certificates on devices, adopting this secure authentication method becomes complex and operationally burdensome. Cumulocity already supports certificate-based device authentication, ensuring secure communication through mutual authentication. However, this introduces an additional responsibility:

• Each device must have a trusted certificate, issued after legitimacy checks.
• These certificates need to be managed over time, including renewal and revocation.

To streamline certificate management, Cumulocity includes a Certificate Authority (CA), providing the following capabilities:

• Manage signing certificates
• Accept Certificate Signing Requests (CSR)
• Perform legitimacy checks as defined by each tenant
• Issue signed X.509 certificates trusted by the device tenant

This enhancement removes the need for external PKI management, allowing customers to adopt X.509 authentication more easily and seamlessly: The Cumulocity CA service is based on the EST protocol due to its simple interactions between devices and the CA service. The following REST API endpoints support the provisioning and renewal of device certificates.

• /.well-known/est/simpleenroll to be used by a device to get a fresh new certificate. The device has to authenticate itself using its tenant, identifier and security token as the BasicAuth realm, user and password. These tenant, identifier and security token must be shared with Cumulocity.
• /.well-known/est/simplereenroll to be used by a device to renew its certificate or to substitute for a certificate. The device has to authenticate itself using its password or a JWT token (obtained using its certificate over MQTT).

The Cumulocity certificate management allows Cumulocity to sign and issue certificates.

The Cumulocity signed certificates are shown in the list of certificate authority (CA) certificates for a tenant along with the trust anchor certificates. In this list, the Cumulocity signed certificates are identifiable by the words TENANT CA.

This section outlines how to create a Certificate Authority (CA) for a tenant with Cumulocity.

Prerequisites

To use the Certificate Authority API, the feature must be enabled at the tenant level, which you can verify using the following API:

GET /features/certificate-authority
Content-Type: application/json
Authorization: Basic <<Base64 encoded bootstrap credentials>>

If you get 200 with active: false then the feature is disabled for the tenant.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: ...
{
    "phase":"PUBLIC_PREVIEW",
    "active":false,
    "strategy":"TENANT",
    "key":"certificate-authority"
}

To enable the feature for the Management tenant you must have the role ROLE_TENANT_MANAGEMENT_ADMIN and call the following API:

PUT /features/certificate-authority/by-tenant/{{tenantId}}
Content-Type: application/json
Authorization: Basic <<Base64 encoded bootstrap credentials>>
...
{
   "active": true
}

This call can be done by executing the following curl statement:

curl -v -u <username>:<password> \
   -H 'Content-Type: application/json' \
   -X PUT \
   -d '{"active": true}' \
   https://<Cumulocity tenant domain>/features/certificate-authority/by-tenant/{{tenantId}}

Replace <username>, <password> with the appropriate credentials given to you when registering with Cumulocity.

To enable the feature for a subtenant you must have the role ROLE_TENANT_MANAGEMENT_ADMIN and call the following API:

PUT /features/certificate-authority/by-tenant
Content-Type: application/json
Authorization: Basic <<Base64 encoded bootstrap credentials>>
...
{
   "active": true
}

This call can be done by executing the following curl statement:

curl -v -u <username>:<password> \
   -H 'Content-Type: application/json' \
   -X PUT \
   -d '{"active": true}' \
   https://<Cumulocity tenant domain>/features/certificate-authority/by-tenant

Creating a CA certificate via REST

To create a new CA certificate for a tenant the Certificate Authority API must be called. This triggers the following actions:

• A new key pair is created and a certificate is self-signed with tenantID as the Common Name (CN).
• The private key is stored in an encrypted tenant option.
• The certificate is stored in the trusted certificate repository with auto-registration turned on by default. Devices can only be registered automatically when the administrator turns this option on.
• If a CA is already present, a respective message is returned.
• If the CA is removed from the trusted certificate list, the corresponding private key is removed from the database collection.

This is an example of a REST request:

POST /certificate-authority
Content-Type: application/json
Authorization: Basic <<Base64 encoded bootstrap credentials>>

The following response is returned:

HTTP/1.1 201 OK
Content-Type: application/json
Content-Length: ...
{
    ......
    "subject":"CN={tenantId}, O=Cumulocity, C=United States",
    "tenantCertificateAuthority":true,
    "autoRegistrationEnabled":false,
    "status":"ENABLED"
    ....
}

This certificate is identified as a TENANT CA and it has the attribute "tenantCertificateAuthority":true.

Creating a CA certificate via the UI

If the Certificate Authority feature is disabled the button Add CA certificate is not visible.

Follow the instructions in Prerequisites to enable it. After enabling the feature, the UI will show the button Add CA certificate.

1. In the Device Management application, navigate to the Management menu in the navigator and select Trusted certificates.
2. Click Add CA certificate at the top right to create the CA certificate.
3. Once the CA has been created the Add CA certificate button and the API are both disabled as only one CA is allowed per tenant. If you want to replace the certificate you need to remove the current CA.

The new CA certificate will be added to the trusted certificates list:

Auto-renewal of CA certificates

Tenant Certificate Authority (CA) is automatically renewed on 2 October at 02:00 AM every year. The renewal process ensures that existing device certificates remain valid until their expiration. This auto-renewal mechanism ensures uninterrupted certificate management while maintaining security and compliance.

• Each CA certificate has a validity of 1095 days (3 years) and undergoes automatic renewal in the background.
• All CA metadata, private keys, and public keys remain unchanged, ensuring a seamless renewal process. Only NotAfter and NotBefore wil be changed.
• Device certificates issued by the CA continue to have 1 year validity from issuance date, and new device certificates can be issued without disruption.
• If the auto-renewal process fails, and it has a near expiration date then an error banner will be displayed in the UI for those certificates.
• Optionally, an email alert can be sent to the tenant administrator for immediate action.