Device enrolment

Provision the device sub-CA, configure an HTTPS base URL reachable by endpoints, and establish trust in that HTTPS service before enrolment. The example DNS names below are fictional; substitute your own configured namespace and service address.

Device-bound, expiring tokens.

Administrators and operators mint tokens in the portal’s /tokens page or with the CLI. Each token has a common name, DNS SAN, and expiry. A certificate request must match the pinned identity.

docker compose exec ca devica token mint \
  --cn sensor-01.devices.example.com \
  --san sensor-01.devices.example.com --days 1

Apple: signed configuration profiles.

1. Open /profiles in the portal as an administrator or operator.
2. Enter the device common name, DNS SAN under your device suffix, and token validity.
3. Build and download the signed .mobileconfig file. It contains CA trust, SCEP enrolment, and enabled network configurations.
4. Deliver it securely and install it on the device through the platform’s configuration-profile workflow.
5. The endpoint generates its key and requests its certificate through SCEP. Confirm issuance in /devices and /activity.

The profile contains an enrolment token. Its signature does not make its contents secret. User-installed profiles are not a push-management channel; network configuration changes require delivery and installation of updated profiles.

Windows: PowerShell enrolment.

1. Open /windows and generate a script for the pinned device identity.
2. Transfer the .ps1 securely and review it before execution.
3. Run it elevated using Windows PowerShell 5.1+ with .NET 4.7.2+, or a suitable PowerShell 7+ environment.
4. The script generates an RSA key and CSR on the endpoint, enrols through REST, imports the credential into LocalMachine\My, installs CA trust, and applies enabled network configurations.

powershell -ExecutionPolicy Bypass -File .\laptop-01.devices.example.com.ps1

The downloaded script contains a token and must be protected. A separate /windows/netcfg download applies current network settings to an already enrolled endpoint; it is not remote push management.

Android: protected credential delivery.

1. Open /android and generate a credential for the device identity.
2. Record the generated passphrase when shown. It is displayed once.
3. Securely deliver the password-protected .p12 and the CA certificate. The device private key is generated on the server for this workflow.
4. Install the PKCS#12 as a VPN/app user certificate using the device’s credential settings; menu labels vary by Android version.
5. Import supplied .sswan VPN profiles into strongSwan, or configure EAP-TLS Wi-Fi manually. See Android network delivery.

PKCS#12 and VPN files carry device credentials. Protect them and their passphrase. A user-installed CA does not change Android’s system trust store, and apps may not trust it automatically.

Linux and IoT: compatible SCEP or REST clients.

For SCEP, configure a compatible client with your /scep endpoint and token as the challenge password. Platform integration, credential installation, and renewal scheduling remain the client’s responsibility.

For REST, submit a signed PEM CSR to POST /enroll with an X-Enrollment-Token header. The endpoint returns the certificate as PEM. An invalid CSR, bad signature, expired/revoked token, mismatched identity, weak key, or invalid device hostname is rejected.

umask 077
openssl req -new -newkey rsa:2048 -nodes \
  -keyout sensor-01.key.pem -out sensor-01.csr.pem \
  -subj "/CN=sensor-01.devices.example.com" \
  -addext "subjectAltName=DNS:sensor-01.devices.example.com"

read -r -s -p "Enrolment token: " DEVICE_ENROLLMENT_TOKEN
printf '\n'
printf 'X-Enrollment-Token: %s\n' "$DEVICE_ENROLLMENT_TOKEN" |
  curl --fail-with-body --silent --show-error \
    --header @- \
    --header 'Content-Type: application/x-pem-file' \
    --data-binary @sensor-01.csr.pem \
    --output sensor-01.crt.pem \
    https://enrollment.example.com/enroll
unset DEVICE_ENROLLMENT_TOKEN

The example requires Bash, OpenSSL supporting -addext, and curl supporting --fail-with-body. Configure your endpoint to trust the HTTPS service; do not disable TLS verification. Install the resulting key and certificate using the endpoint’s own service tooling.

The REST endpoint handles token-based issuance. SCEP has a separate certificate-authenticated renewal path; see renewal behaviour.