Configure and operate the DMS

Define registration, authentication per operation, issuance, renewal and distributed trust.

A Device Management Service (DMS) configures admission and identity lifecycle for its devices. It acts as a registration authority; the CA selected in Enrollment CA signs certificates. This guide is for the policy administrator.

Before you begin

You need DMS management permissions, an active CA with a usable key and a tested issuance profile. Agree device ID, initial credential, consumer and renewal window with the integrator. Review Provisioning strategies before choosing registration and replacement.

Prepare EST server trust and device connectivity through Deployment. Your operator’s administrative authentication does not replace device EST authentication.

Configure a DMS

Identify the fleet

Create the DMS with a recognizable name and retain its ID. EST URLs use this identifier, not the display name. Each device retains one owning DMS.

Select the enrollment CA

Choose Enrollment CA and an explicit profile appropriate for the end-entity identity. Keep CN compatible with Device ID. The test certificate should allow its intended purpose and expire within issuer validity.

Configure EST

Select initial enrollment registration and authentication. Separately configure re-enrollment authentication, thresholds and previous certificate retirement. Leave ServerKeyGen disabled if the client generates its key.

Distribute trust

Select certificates returned by /cacerts. Explicitly include required intermediates and roots, keeping distribution distinct from automatic trust installation.

Verify the endpoints

Save and read configuration again. Query /cacerts, perform an allowed and a rejected enrollment, and inspect device, serial and history. Creating the DMS or downloading cacerts does not establish working authentication and issuance.

Enrollment configuration

Enrollment Device Registration

settings.enrollment_settings.registration_mode accepts JITP or PRE_REGISTRATION. JITP creates an unknown device with the CSR CN as ID and the DMS as owner. device_provisioning_profile supplies tags, metadata and icon for that registration.

PRE_REGISTRATION requires an existing ID. In the inspected code, an existing device encounters replacement checks first, even without an identity. Review preregistration conditions before using this mode.

Enrollment Settings

settings.enrollment_settings fieldDecision
protocolEST_RFC7030 for these operations.
enrollment_caID of the signing CA.
verify_csr_signatureKeep true to verify CSR key possession.
enable_replaceable_enrollmentAllows /simpleenroll for an existing ID in the same DMS. It can attempt previous certificate revocation even if a later phase fails; this is not atomic.
est_rfc7030_settings.auth_modeOne of the four authentication modes.

Initial enrollment rejects an ID owned by another DMS. Do not automatically enable replacement in response to an error; Troubleshooting distinguishes repeated IDs, ownership and partial changes.

Authentication per operation

The blocks are independent:

  • settings.enrollment_settings.est_rfc7030_settings for /simpleenroll and /serverkeygen.
  • settings.reenrollment_settings.est_rfc7030_settings for /simplereenroll.
auth_modeControl applied in the configured operation
CLIENT_CERTIFICATEPresented certificate validation.
EXTERNAL_WEBHOOKConfigured webhook authorization.
CLIENT_CERTIFICATE_AND_EXTERNAL_WEBHOOKCertificate validation followed by webhook approval.
NO_AUTHNo DMS requester authentication.

Webhook and combined modes also execute during re-enrollment when configured in its block. They do not implicitly degrade to NO_AUTH. An absent or unrecognized mode fails.

For initial mTLS, client_certificate_settings contains validation_cas, allow_expired and chain_level_validation. The inspected flow receives one certificate credential; it does not guarantee forwarding every handshake intermediate to the validator. For a direct case, configure the bootstrap’s direct issuer as validation CA and test the actual Gateway path.

For certificate re-enrollment, the validator tries the enrollment CA first and then the CAs listed in reenrollment_settings.est_rfc7030_settings.client_certificate_settings.validation_cas; those are the re-enrollment validation CAs. That list is optional because the enrollment CA is always trusted for re-enrollment, and each settings block consults only its own validation_cas. CAs listed only in the initial block's validation_cas do not extend re-enrollment acceptance; during a CA rotation, add the old issuance CA to the re-enrollment block's list. The re-enrollment validator compares the presented TLS leaf against those CAs; the re-enrollment block's chain_level_validation and allow_expired values are stored but not consulted, and expiry is governed by enable_expired_renewal.

For a webhook, configure destination, Lamassu-to-service authentication, method and timeout. The authentication contract explains the device credential and request body. NO_AUTH does not establish ownership of the requested ID.

External webhook settings

The webhook authentication modes read external_webhook_settings in the same est_rfc7030_settings block:

external_webhook_settings fieldDecision
urlAbsolute http or https URL of the receiver. It must be the final URL; redirects are not followed.
methodPOST or PUT; POST by default.
nameLabel used in service logs.
config.auth_modenoauth, apikey, jwt or mtls. An absent or unknown value behaves as noauth.
config.log_levelLog level of the webhook call: debug, info, warn or error; info by default.
config.apikey_optionsRequired for apikey: header and key. Reserved header names are rejected.
config.jwt_optionsRequired for jwt: oidc_client_id, oidc_client_secret and an absolute http or https oidc_well_known.
config.mtls_optionsRequired for mtls: cert_content and key_content as Base64-encoded PEM, like certificates elsewhere in the API; plain PEM is also accepted.
config.insecure_skip_verifySkips verification of the receiver certificate when true. Verification is on by default. Unlike alert channels, this flag is honored here.
config.call_timeoutMaximum duration of the authorization call (for example 10s); 10 seconds by default.

Rules for that configuration:

  • Creating or updating a DMS whose enrollment or reenrollment auth_mode uses the webhook validates the block and returns HTTP 400 — the body starts with struct validation error: and continues with invalid enrollment external webhook config or invalid reenrollment external webhook config — when the URL, method or options are invalid. That includes an mtls_options.cert_content/key_content pair that does not decode to a matching certificate and private key. File references (ca_cert_file, mtls_options.cert_file, mtls_options.key_file) are always invalid: the service does not read files, so enter the certificate and key as Base64-encoded PEM in mtls_options.cert_content and key_content, or as plain PEM.
  • A custom apikey_options.header may not use names that the platform or the receiving service trusts — for example X-Principal-Id, X-Request-Id, Host, Content-Type or Forwarded — and no name may start with X-Forwarded-, X-Envoy- or X-Lms- (case-insensitive). The DMS API reference documents the WebhookCall and WebhookCallHttpClient schemas and that reserved API-key headers are rejected.
  • The nested http_client key exists only in alert channel configurations; in a DMS body it is ignored. The DMS key is external_webhook_settings.config.
  • A body with config.auth_mode set to apikey, jwt or mtls must carry its corresponding option block (apikey_options, jwt_options or mtls_options) — and nothing else. Bodies with those auth modes carrying only apikey, oidc or mtls fail validation with 400, and validate_server_cert is always ignored: use insecure_skip_verify. Only bodies without option blocks are accepted as noauth, and their credentials are dropped.
  • The authorization response must be JSON of at most 1 MiB; a larger body fails the call.

Credentials over http://

With credentials configured, they are sent regardless of the URL scheme: an http:// webhook receives the API key or bearer token in cleartext, and mTLS has no effect because no TLS handshake takes place, so the client certificate is never presented. Prefer https:// for url, oidc_well_known and the token endpoint it advertises.

Initial authentication and renewal settings are stored independently. If a DMS only has the initial authentication block, renewal reuses it: read both blocks before editing. The console exposes independent editors for the enrollment and re-enrollment authentication, with the same Log Level, Call Timeout, HTTP Authentication and credential fields as the webhook channels, plus a Skip TLS Verification switch (off by default, so verification stays on; the console warns when you enable it).

Webhook credentials must be stored as PEM content. File references (ca_cert_file, mtls_options.cert_file, mtls_options.key_file) are never valid in a stored webhook config: delivery rejects any webhook config that references files, whatever its auth mode, so every enroll and reenroll that calls that webhook fails until the certificate and key are entered as Base64-encoded or plain PEM in mtls_options.cert_content and key_content, or the file fields are removed if the webhook does not use mTLS. If a stored config holds file paths in mtls_options.cert_content or key_content, every full settings update (POST /v1/dms, PUT /v1/dms/:id) fails validation — settings are replaced wholesale, so the stored config must be resent — until the values are replaced by PEM content or the webhook stops being used. Meanwhile, delivery of that webhook fails on every call; a metadata-only update through PUT or PATCH on /v1/dms/:id/metadata still succeeds. To fix it in the console, open the DMS, replace any file-path value with PEM content — the editor rejects file paths with an inline field error — and save. Saving rewrites external_webhook_settings.config with the current keys, and the console reads both plain and Base64-encoded PEM from migrated configurations and stores the material Base64-encoded. If your stored config previously relied on validate_server_cert: false, it now carries insecure_skip_verify: true: receiver-certificate verification stays skipped until you set that flag to false. See 3.8.0 to 4.0.0 for the upgrade notes and the operator checklist.

The re-enrollment trust set lives in reenrollment_settings.est_rfc7030_settings.client_certificate_settings.validation_cas. The flat field reenrollment_settings.additional_validation_cas is not part of the API: bodies that carry it are accepted but the value is silently ignored — unknown JSON fields are dropped — and GET responses do not include it. Read the DMS before sending API edits: an update body built with that flat field silently empties validation_cas.

Issuance profile

settings.issuance_profile_id takes precedence over settings.issuance_profile; without either, the CA default profile is used. The resolved profile — including the CA default used as fallback when the DMS defines none — must define an end-entity certificate: a Sign as CA profile is rejected at enrollment and re-enrollment time. Rules are documented once in Profiles. DMS changes affect future requests; they do not modify signed certificates or install client trust.

Re-enrollment configuration

settings.reenrollment_settings fieldPurpose
reenrollment_deltaOpens the window at the active certificate’s NotAfter minus this delta.
preventive_deltaPreventive operational monitoring threshold.
critical_deltaCritical operational monitoring threshold.
enable_expired_renewalAccepts an expired presented certificate in the renewal mTLS validator. Does not authorize another mode or remove Gateway constraints by itself.
est_rfc7030_settings.client_certificate_settings.validation_casRe-enrollment validation CAs for the renewal mTLS credential, tried after the enrollment CA; optional, because the enrollment CA is always trusted. Typically populated during CA rotation while old-CA cohorts renew.
revoke_on_reenrollmentIf the previous certificate is ACTIVE, attempts Superseded revocation before binding its successor.

Monitoring does not renew: the client must schedule the request and installation. Webhook and NO_AUTH modes do not use the same mTLS expired-credential validator; the webhook must explicitly authorize permitted recovery. Review Renewal and recovery for operation order and partial failures.

ServerKeyGen

settings.server_keygen_settings.enabled enables software key generation on the server. The console exposes it through an Enable server-side key generation switch and a Key type selection: ECDSA P-256, P-384 or P-521, or RSA with 2048, 3072 or 4096 bits; the defaults are P-256 for ECDSA and 4096 bit for RSA. Algorithm and size come from its key field, stored as {type,bits} where P-256, P-384 and P-521 map to bits 256, 384 and 521; key is omitted when disabled. The profile must permit them. The response contains an unencrypted PKCS#8 key inside TLS alongside the certificate. See format and extraction in EST reference.

Trust distribution

OptionPublished material
Include Lamassu System CAAvailable downstream TLS certificate; it can be a leaf, not an issuing CA.
Include Enrollment CASelected issuing CA certificate.
Managed CAsExplicitly selected CA certificates.

All ancestors are not added automatically. Trust distribution distinguishes trusted roots, intermediates and initial server trust.

Operate the DMS inventory

Edit changes name, settings and metadata. Updates go through the DMS API. PUT /v1/dms/{id} always targets the DMS identified by the URL path: the body carries no id field, and any id or creation_ts in it is silently ignored — authorization is evaluated against the same URL identifier. The body must include a non-empty name and a settings object; missing either returns HTTP 400 and leaves the stored DMS unchanged. name and settings are always full replacements, so read the DMS before sending API edits to avoid losing fields. metadata is optional: omitting it or sending null keeps the stored metadata, a supplied object replaces it entirely, and {} clears it (a later GET returns an empty object, not null). Old-style bodies that carry the full DMS object keep working while they include name and settings; unknown fields are ignored. Updates reject an empty name with HTTP 400: a DMS whose stored name was zeroed by an earlier update must be renamed before any client round-trips it — the AWS IoT connector’s JITP writeback included. If the object does not include the AWS IoT connector key (lamassu.io/iot/{connector_id}), the connector ignores the DMS's later events.

Go to DMS owned devices restricts inventory by owner. Show/Edit Metadata contains operational and integration data; consult the integration guide before changing it. EST (RFC-7030) helps locate URLs.

Delete removes the DMS record and configuration; it does not itself cascade revocation across every device and certificate. Migrate dependencies and retain audit references before retirement.

Integrate the devices

Continue with EST client or the enrollment and mTLS tutorial. EST reference covers formats; Troubleshooting covers failures.

On this page