Certificate and device identity reference
Technical description of the certificates Firezone accepts as device identities, how it selects and validates them, and how each platform supplies the private key. For the concepts behind these values, see Device Trust. For configuration steps, see Set up Device Trust.
Certificate requirements
These requirements apply to the certificate profile or CA template that issues the device identity.
| Field | Requirement |
|---|---|
| Subject | Common name is CN=dev.firezone.device-trust. |
| Extended Key Usage | Includes TLS Web Client Authentication (clientAuth, OID 1.3.6.1.5.5.7.3.2). |
| Key Usage | Omitted, or includes digitalSignature. |
| Key algorithm | RSA, or ECDSA with the P-256, P-384, or P-521 curve. |
| Private key | Non-exportable and hardware-backed where the platform and enrollment method support it. |
| Validity | Any lifetime. The renewal window is set by the issuer. |
| Subject Alternative Name | Contains at least one supported device identifier as a URI SAN. |
The subject common name is fixed for every device. Firezone does not use the subject as the device identifier; the fixed value lets Clients select the correct identity, and the per-device claim lives in the SAN.
Device identifiers
A device identifier is a typed URI SAN of the form:
firezone://<type>/<value>
| Claim | URI SAN example |
|---|---|
| Serial number | firezone://serial/C02ABC123XYZ |
| UDID | firezone://udid/00008110-001234560E91801E |
| SMBIOS UUID | firezone://smbios-uuid/01234567-89ab-cdef-0123-456789abcdef |
| Microsoft Intune device ID | firezone://intune-id/<device-id> |
| Workspace ONE UUID | firezone://ws1-uuid/<device-id> |
| Jamf Pro device ID | firezone://jamf-id/<device-id> |
| Iru/Kandji device ID | firezone://kandji-id/<device-id> |
A certificate may carry multiple typed URI SANs, such as both an MDM inventory ID and a hardware serial. An MDM inventory ID is scoped to and controlled by the management provider; a hardware serial is not. Empty, placeholder, and shared values are not valid device identifiers.
On personally owned Android work profiles, Android 12 and later restrict access
to hardware serial numbers, so firezone://serial/<serial-number> is
unavailable on those devices.
Platform key storage
Each platform supplies the certificate and private-key operations differently.
| Platform | How Firezone uses the device identity |
|---|---|
| Windows | The Client finds the certificate in the local computer personal store (LocalMachine\My). The tunnel service runs as LocalSystem and signs through Windows CNG. The key can be protected by a TPM. |
| macOS | The Client uses the Keychain identity referenced by the managed VPN configuration. The certificate and VPN payloads must be linked. The network extension needs access to the private key without an interactive Keychain prompt. |
| iOS and iPadOS | The Client uses the managed identity referenced by the VPN configuration. The certificate payload supplies the identity, and the VPN payload selects it for Firezone. |
| Android | The Client uses an identity in Android KeyChain, selected by a managed keychain alias for corporate-owned devices or selected by the user for personally owned devices. The MDM grants Firezone access to the private key. The certificate and app must be installed in the same Android profile. |
| Linux | The Client uses a configured PKCS#11 identity. The certificate and signing key can be held by a TPM, smart card, hardware security module, or software token. Signing is delegated to the PKCS#11 provider. |
Certificate selection
When more than one usable certificate is present, the Client selects the one
with the most recent validity start date (NotBefore).
On platforms where the MDM or the user selects the identity, that selection determines which certificate the Client uses, and it must be pointed at the renewed certificate when one is issued.
Renewal
A renewed certificate that preserves its device identifier continues to satisfy Policies matching that device. A certificate that expires, or whose private key becomes inaccessible, causes the Client to connect without attestation rather than to fail the connection.
Revocation
The Firezone portal supports both Certificate Revocation Lists (CRLs) and the Online Certificate Status Protocol (OCSP). It discovers the revocation endpoints advertised in certificates when devices connect.
- CRLs publish the certificate serial numbers revoked by an issuing CA.
- OCSP responders report the status of individual certificates.
Revocation checks run in the background. When Firezone detects a revoked certificate, it disconnects Clients using that certificate and blocks reconnection with it. Revocation takes effect once the CA has published the updated status and Firezone has retrieved it.
Scope of a trust anchor
A trust anchor applies to the entire Firezone account. Any certificate chaining to it is eligible to serve as a device identity for any Client in that account.
Need help? See all support options.