Troubleshoot Device Trust

Find the symptom below and work through its checks. Most Device Trust problems come from certificate provisioning rather than from Firezone, so the fix usually belongs in your MDM or CA.

Start with the Client

Open Settings → Device Trust in the Firezone Client. It reports the four things that have to be true, and it tells you which one is failing:

1. A certificate was found and selected.
2. Its chain validates against your trust anchors.
3. Its private key is usable for signing.
4. Its device identifiers are the values you expect.

Read that screen before changing anything. It distinguishes between problems that look identical from the portal side.

If the screen is unavailable or the Client will not start, collect diagnostic logs.

The Client finds no certificate

The Client selects an identity by its subject, which must be exactly CN=dev.firezone.device-trust.

• Confirm the profile is assigned to the test device's group and that the device has synced. Check the certificate is installed on the device itself, not just that the profile exists.
• Check the subject on the issued certificate. A CA template that rewrites or appends to the subject produces a certificate the Client will not select.
• macOS and Apple platforms: the certificate payload and the VPN payload must be in the same profile, and the VPN payload must reference the certificate payload's PayloadUUID. Deploy through the Device channel with PayloadScope set to System.
• Android: the certificate and the Firezone app must be installed in the same profile. An identity in the personal profile is invisible to an app in the work profile.
• Linux: confirm the Client is configured with the PKCS#11 provider and identity holding the certificate.

The certificate is found but the chain is not valid

Firezone builds the chain from the leaf the Client presents up to a configured trust anchor.

• Add every intermediate CA as well as the root under Settings → Trust Anchors. A missing intermediate is the most common cause.
• Confirm the anchors were added to the account the Client signs in to. A trust anchor applies to one Firezone account.
• Confirm the uploaded CA certificate is the one that actually issued the leaf. Cloud PKI and similar services can host several issuing CAs.

The private key cannot be used for signing

The certificate is present and valid, but the Client cannot produce a signature. This is an access-control problem, and on Apple platforms it is almost always decided when the key is created.

• Windows: the tunnel service runs as LocalSystem. Verify that SYSTEM can use the CNG private key, and that the identity is in LocalMachine\My rather than a user store.
• macOS: the SCEP payload must have AllowAllAppsAccess=true at the time the key is created. The Firezone system extension cannot display a Keychain authorization prompt, so a key that requires one fails silently.
• Android: the MDM must grant Firezone access to the key. On corporate devices set the managed keychain alias; on personally owned devices the user selects the certificate when prompted.
• Linux: confirm the PKCS#11 provider is reachable and that the token is unlocked.

The device identifier is wrong or empty

The Client shows the URI SANs it read from the certificate.

• A literal {{DeviceId}}, $DEVICE_ID, or $SERIAL_NUMBER means the variable was not substituted. Inspect the issued certificate rather than the profile: the profile can be correct while the CA drops or ignores the requested SANs.
• Confirm the CA template is configured to issue the SANs supplied in the request. Many templates discard them by default.
• Confirm each identifier is a real per-device value. Empty, placeholder, and shared values are not valid identifiers.
• Personally owned Android work profiles: Android 12 and later restrict hardware serial numbers, which can fail provisioning. Omit firezone://serial/<serial-number> and keep the MDM inventory ID.

See device identifiers for the supported claims.

The Client connects but is not attested

An expired certificate, or one whose private key has become inaccessible, does not fail the connection. The Client connects without attestation, so Resources behind an attestation condition stop being reachable while everything else keeps working.

• Check the certificate's validity period and whether renewal is still running.
• Work through the private key checks above.
• On platforms where the MDM or the user selects the identity, confirm the selection still points at a current certificate.

The Client is attested but access is still denied

Attestation succeeded, so the problem is in the Policy.

• Confirm the Policy granting access to that Resource carries the Require attestation condition.
• The condition is evaluated on the current connection. A Client that reconnected without its certificate does not keep an earlier attested state. Reconnect and re-check.

An unattested device can still reach the Resource

Policies are additive, so any Policy that grants access is sufficient on its own.

• Find every Policy that grants the same Group access to that Resource and add the condition to each, or remove the ones that should not apply. One overlapping Policy without the condition defeats the others.

Access worked and then stopped

• The certificate expired or was renewed incorrectly. A renewal must preserve both the device identifier and the exact subject common name. Some automatic redistribution workflows alter the subject, which makes the Client stop selecting the identity.
• The certificate was revoked. Firezone checks CRL and OCSP endpoints in the background, disconnects Clients using a revoked certificate, and blocks reconnection with it.
• A newer certificate was installed. When several usable certificates are present, the Client selects the one with the most recent NotBefore. If that one is wrong, remove it rather than reordering.

Nothing above matches

Collect diagnostic logs, note what Settings → Device Trust reports, and export the issued certificate so its subject, SANs, extended key usage, and chain can be inspected directly.

Need help? See all support options.