Skip to main content

Certificate Onboarding

Certificate-based device onboarding using EST and the Glaze CA — from shared keys to manufacturer birth certificates.

The shared-secret onboarding flow (documented in Device Onboarding) provisions devices with MQTT username/password credentials. Certificate-based onboarding replaces those credentials with X.509 certificates issued by the Glaze CA, enabling mTLS connections to the MQTT broker.

Use certificate-based onboarding when you need:

  • Stronger device identity — certificates are cryptographically bound to a device, not just a shared secret
  • Automatic rotation — EST re-enrollment renews certificates before expiry without manual key distribution
  • Zero-trust broker access — the broker verifies the Glaze CA chain on every connection, not just a password hash
  • Tenant isolation — the certificate's OU field encodes the tenant, enforcing ACLs at the TLS layer

Decision Matrix​

Choose a flow based on your integration model and the device's attestation capability:

Tier 1 — Shared KeyTier 2 — OTPTier 3 — Birth Certificate
Consumer / AppApp + shared key + ESTApp + OTP + ESTApp + birth cert + EST
B2B / IndustrialPre-provisioned + shared key + ESTPre-provisioned + OTP + ESTPre-provisioned + birth cert + EST

Consumer / App flows — A customer app (mobile or web) scans the device, provisions it to a tenant via the Provision API, and hands the device WiFi credentials over BLE or SoftAP. Best for retail products where an end user sets up the device.

B2B / Industrial flows — Devices are pre-provisioned during manufacturing or deployment. No customer app is involved. The device self-onboards when it first connects to the network. Best for commercial appliances, industrial sensors, connected chargers, and fleet deployments.

Attestation tiers — Higher tiers provide stronger identity guarantees:

TierAttestationKey GenerationManufacturer Requirement
1Shared key from GlazeServer-side (EST)None — Glaze provides the key
2One-time passwordServer-side (EST)Register devices, flash OTP
3Birth certificateOn-device (chip)Operate own PKI, sign birth certs

How It Works​

All certificate flows share the same four-step lifecycle:

1. Provision​

The device is registered with a tenant via an enrollment group. In consumer flows, a customer app calls POST /api/provisioning. In B2B flows, this happens during manufacturing or via a deployment pipeline.

The provision call is a success-acknowledgement only — the response is {deviceId, created} with no credentials. Onboarding orchestrates the registration (creating the ProviderClient row in core-management, dispatching the provision over the bus to the provider service), but credential delivery is a separate step the device itself performs (see step 2 for Tier 1; EST for Tier 2/3).

2. EST Enrollment​

The device authenticates to the Beacon Tower EST server using its tier-specific credential (shared key, OTP, or birth certificate). EST issues an operational certificate signed by the Glaze CA.

3. Connect​

The device connects to the Mosquitto broker using mTLS with its Glaze-issued certificate. The broker verifies the certificate chain and extracts the device identity and tenant from the certificate fields.

4. Renew​

Before the certificate expires, the device re-enrolls with EST using its current operational certificate. A new certificate is issued without requiring the original attestation credential.

Key Concepts​

EST (Enrollment over Secure Transport)​

RFC 7030 — a standard protocol for certificate enrollment. Beacon Tower's EST server supports:

  • GET /.well-known/est/cacerts — Retrieve the Glaze CA chain
  • POST /.well-known/est/simpleenroll — Enroll with a CSR (Tier 1 and Tier 3)
  • POST /.well-known/est/serverkeygen — Enroll with server-generated key (Tier 2)
  • POST /.well-known/est/simplereenroll — Renew an existing certificate (all tiers)

Glaze CA​

The platform certificate authority that issues operational certificates. The Mosquitto broker trusts only the Glaze CA root — a valid Glaze certificate is both the device's identity and its access token.

Device Registry​

Tracks device lifecycle state: registered, enrolled, active. Stores device metadata (serial, hardware revision, batch) and attestation credentials (shared keys, OTPs, birth certificate fingerprints).

Provisioning API​

POST /api/provisioning — binds a device to a tenant via an enrollment group. Accepts device_id and enrollment_group_id. The enrollment group defines the tenant, attestation type, and provider configuration. Called by the customer app (consumer flows) or automation (B2B flows). The response is an ack only ({deviceId, created}); credentials are not returned here.

Settings API (Tier 1 credential delivery)​

GET /get_settings — the device's path for retrieving its own MQTT credentials. Authenticates with HTTP Basic Auth using the device id plus the enrollment group's bootstrap key (Tier 1) or with mTLS using a Glaze-issued certificate (Tier 3). Returns whatever the enrollment group's response_template renders against the per-device variable set (primary key, secondary key, broker URL, etc.). Tier 2 devices skip this — their credentials come from EST.

mTLS (Mutual TLS)​

Both the broker and the device present certificates during the TLS handshake. The broker verifies the device's Glaze certificate; the device verifies the broker's server certificate. This replaces username/password authentication.

Birth Certificates (Tier 3)​

X.509 certificates issued by the manufacturer's own PKI during production. Proves hardware authenticity — the device was manufactured by a known, trusted party. Used only for initial EST enrollment; operational access uses Glaze certificates.

OTP (One-Time Password, Tier 2)​

A unique token generated when the manufacturer registers a device with the registry. Flashed onto the device or printed on a label. Single-use — invalidated after the first successful EST enrollment.

Shared-Secret Onboarding​

For devices that don't need certificate-based authentication, the shared-secret onboarding flow provisions devices with MQTT username/password credentials. It's simpler to set up but doesn't provide the security properties of mTLS.

Next Steps​