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 field | Decision |
|---|---|
protocol | EST_RFC7030 for these operations. |
enrollment_ca | ID of the signing CA. |
verify_csr_signature | Keep true to verify CSR key possession. |
enable_replaceable_enrollment | Allows /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_mode | One 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_settingsfor/simpleenrolland/serverkeygen.settings.reenrollment_settings.est_rfc7030_settingsfor/simplereenroll.
auth_mode | Control applied in the configured operation |
|---|---|
CLIENT_CERTIFICATE | Presented certificate validation. |
EXTERNAL_WEBHOOK | Configured webhook authorization. |
CLIENT_CERTIFICATE_AND_EXTERNAL_WEBHOOK | Certificate validation followed by webhook approval. |
NO_AUTH | No 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 field | Decision |
|---|---|
url | Absolute http or https URL of the receiver. It must be the final URL; redirects are not followed. |
method | POST or PUT; POST by default. |
name | Label used in service logs. |
config.auth_mode | noauth, apikey, jwt or mtls. An absent or unknown value behaves as noauth. |
config.log_level | Log level of the webhook call: debug, info, warn or error; info by default. |
config.apikey_options | Required for apikey: header and key. Reserved header names are rejected. |
config.jwt_options | Required for jwt: oidc_client_id, oidc_client_secret and an absolute http or https oidc_well_known. |
config.mtls_options | Required 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_verify | Skips verification of the receiver certificate when true. Verification is on by default. Unlike alert channels, this flag is honored here. |
config.call_timeout | Maximum 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_modeuses the webhook validates the block and returns HTTP 400 — the body starts withstruct validation error:and continues withinvalid enrollment external webhook configorinvalid reenrollment external webhook config— when the URL, method or options are invalid. That includes anmtls_options.cert_content/key_contentpair 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 inmtls_options.cert_contentandkey_content, or as plain PEM. - A custom
apikey_options.headermay not use names that the platform or the receiving service trusts — for exampleX-Principal-Id,X-Request-Id,Host,Content-TypeorForwarded— and no name may start withX-Forwarded-,X-Envoy-orX-Lms-(case-insensitive). The DMS API reference documents theWebhookCallandWebhookCallHttpClientschemas and that reserved API-key headers are rejected. - The nested
http_clientkey exists only in alert channel configurations; in a DMS body it is ignored. The DMS key isexternal_webhook_settings.config. - A body with
config.auth_modeset toapikey,jwtormtlsmust carry its corresponding option block (apikey_options,jwt_optionsormtls_options) — and nothing else. Bodies with those auth modes carrying onlyapikey,oidcormtlsfail validation with 400, andvalidate_server_certis always ignored: useinsecure_skip_verify. Only bodies without option blocks are accepted asnoauth, 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 field | Purpose |
|---|---|
reenrollment_delta | Opens the window at the active certificate’s NotAfter minus this delta. |
preventive_delta | Preventive operational monitoring threshold. |
critical_delta | Critical operational monitoring threshold. |
enable_expired_renewal | Accepts 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_cas | Re-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_reenrollment | If 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
| Option | Published material |
|---|---|
| Include Lamassu System CA | Available downstream TLS certificate; it can be a leaf, not an issuing CA. |
| Include Enrollment CA | Selected issuing CA certificate. |
| Managed CAs | Explicitly 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.