Certs

Provisioning is a process of configuration of an IoT platform in which system operator creates and sets-up different entities used in the platform - users, groups, channels and devices.

Certs Service

Issues certificates for entities (devices, gateways, etc). Certs service can create certificates to be used when Magistrala is deployed to support mTLS. Certs service will create a certificate for a valid entity ID if a valid user token is passed and the user is authorized for the provided entity ID.

Certificate service can create certificates in PKI mode - where certificates issued by PKI, when you deploy OpenBao as PKI certificate management cert service will proxy requests to the configured PKI previously checking access rights and saving info on successfully created certificate.

PKI mode

When MG_CERTS_VAULT_HOST is set, it is presumed that OpenBao is installed and certs service will issue certificates using the configured PKI API.

First you'll need to set up OpenBao.

To setup OpenBao follow the PKI secrets engine setup and usage guide.

To setup certs service with OpenBao following environment variables must be set:

MG_CERTS_VAULT_HOST=vault-domain.com
MG_CERTS_VAULT_PKI_PATH=<vault_pki_path>
MG_CERTS_VAULT_ROLE=<vault_role>
MG_CERTS_VAULT_TOKEN=<openbao_access_token>

Make sure you have an already running instance of Magistrala, OpenBao and Certs service.

To start Magistrala run:

make run_latest args="-d"

OpenBao deployment and PKI bootstrap steps are documented separately. Until then, configure OpenBao PKI before starting certs.

To start certs service run:

make run_addons certs up args="-d"

To stop certs service run:

make run_addons certs down

You'll need an entity ID (a device or gateway ID) and a user token before issuing a certificate.

The real command surface, from cli/certs.go (subject to the CLI-wiring caveat above):

certs [issue | get | revoke | renew | ocsp | view | download-ca | view-ca | csr | issue-csr | issue-csr-internal | crl | entity-id]

1. Issue a certificate

magistrala-cli certs issue <entity_id> <common_name> <ip_addrs_json> [<options_json>] <workspace_id> <token> [--ttl=8760h]

For example:

magistrala-cli certs issue f13f0f30-f923-4504-8a7a-6aa45bcb4866 my-device '[]' <workspace_id> $USER_TOKEN --ttl=8760h

2. Retrieve a certificate

magistrala-cli certs get [all | <entity_id>] <workspace_id> <token>
magistrala-cli certs view <serial_number> <workspace_id> <token>

3. Revoke or renew a certificate

magistrala-cli certs revoke <serial_number> <workspace_id> <token>
magistrala-cli certs renew <serial_number> <workspace_id> <token>

Other subcommands exist for CA inspection (view-ca, download-ca, crl), CSR-based issuance (csr, issue-csr, issue-csr-internal), OCSP status (ocsp), and looking up the entity behind a serial (entity-id) — see cli/certs.go for exact arguments.

For more information about the Certification service, please check out the Certs documentation.