PKI & trust

EAP-TLS authenticates a user or device by their certificate instead of a password. For that to work Taranac has to do two things: decide which certificates it trusts (the issuing CAs), and — optionally — issue the certificates itself. Settings → PKI / Certificates covers both. It lets you stand up an internal Certificate Authority, issue and revoke user and device certificates, enroll devices automatically over EST, and pull in external CAs you already operate (a corporate AD CS, a partner’s CA). Two sibling pages complete the picture: Settings → PKI Settings (EST, certificate defaults, public endpoints) and Settings → Trusted CAs.

If you are running EAP-TLS at all, every certificate path on your network passes through here. This page explains the pieces, how to configure them in the admin UI, and when to lean on Taranac’s built-in PKI versus an external one you already have.

PKI & Certificates page: Certificate Authorities on the left, issued certificates on the right, CA bundle below The PKI page — a CA tree on the left, the issued-certificate table on the right, and the live CA bundle composition at the bottom.

pki · ca bundle & trust

Internal CAs Taranac issues

Trusted CAs uploaded (AD CS)

LDAP / AD CAs auto-pulled

ca_clients.pem combined trust list · enabled CAs

EAP-TLS · clientAuth chains to enabled CA accept

EAP-TLS · clientAuth on the CRL · revoked reject

Three independent sources feed one CA bundle (ca_clients.pem); a client certificate is accepted when it chains to an enabled CA, and rejected when it is on the CRL.

Key concepts

Term	What it means in Taranac
Internal CA	A Certificate Authority that Taranac generates (or imports) and uses to sign certificates. Can be a self-signed Root or an Intermediate signed by a parent CA.
Issued certificate	An end-entity certificate signed by an Internal CA. Type is user, device, or server.
Server certificate	The certificate FreeRADIUS presents to clients during EAP (its TLS identity). Exactly one is active at a time.
Trusted CA	An external CA certificate you upload so Taranac trusts client certificates issued by it — without Taranac issuing anything.
CA bundle	The combined trust list (`ca_clients.pem`) FreeRADIUS uses to verify client certificates. Assembled from Internal CAs, Trusted CAs, and the CAs of LDAP/AD domains.
CRL	Certificate Revocation List — the signed list of revoked certificates that FreeRADIUS checks so revoked credentials stop authenticating.
EST	Enrollment over Secure Transport (RFC 7030) — a REST API devices and MDM use to request and renew certificates automatically.
Enrollment request	An EST enrollment waiting on a human, when Require admin approval is on. Deliberately not a certificate: it has its own record and its own states — `pending` → `approved` / `rejected` / `expired`.

Where trust comes from

The CA bundle that FreeRADIUS uses to validate a client certificate is built from three independent sources. The panel at the bottom of the PKI page shows exactly what is in it:

Internal CAs — CAs Taranac runs itself (this page).
Trusted CAs — external CA certificates you uploaded on the Trusted CAs page.
LDAP / AD domain CAs — the EAP-TLS CA certificate of every LDAP configuration that has EAP-TLS enabled, pulled in automatically.

A client certificate authenticates if it chains to any enabled CA in the bundle. You do not have to issue certificates from Taranac to use EAP-TLS — you can trust an external issuer and never touch the Internal CA features at all.

Certificate Store, on the PKI Settings page, opens the same thing in detail: every certificate currently in ca_clients.pem with its source (Internal CA / Trusted CA / LDAP) and validity, plus a CRL Status tab that names the CAs with no revocation list on disk.

An LDAP configuration holds two CA certificates, for opposite directions of two different handshakes. The one on its EAP-TLS tab checks the certificates client devices present during 802.1X — that is the one this bundle is built from. The one on its Connection tab checks the certificate the directory server presents over LDAPS. In a Windows domain the same enterprise CA usually issues both, which is why they are easy to mistake for one setting entered twice.

Until 1.2.4 the TACACS+ and RADIUS services quietly used the EAP-TLS certificate for the LDAPS connection whenever the connection’s own field was empty. That substitution is gone — each field is now used for its own job and nothing else.

Who is affected: an LDAP configuration whose CA certificate field (Connection tab) is empty, with Validate TLS certificates on, reached over ldaps:// or StartTLS, while its EAP-TLS CA certificate is filled in. For those, TACACS+ and RADIUS logins against that directory stop working after the update. Nothing else changes: configurations with their own CA certificate, configurations without encryption, and the EAP-TLS certificate’s real job — feeding this bundle — are untouched.

What to do, before updating: open Settings → LDAP → your configuration → Connection and paste the CA that issued the directory server’s certificate into CA certificate. If it is the same enterprise CA as on the EAP-TLS tab, the Use the EAP-TLS CA button next to the field copies it across. Nothing is copied automatically, on purpose — the two are the same only in a Windows domain. See LDAP directories for that side of it.

The Internal CA

Root vs Intermediate

An Internal CA is either a Root (self-signed, the top of a chain) or an Intermediate (signed by a parent Root or Intermediate). A two-tier hierarchy — one offline-style Root, one issuing Intermediate — is the textbook design, but for a lab, pilot, or small site a single Root that issues directly is perfectly fine.

Field	Root	Intermediate
Signed by	itself	a parent Internal CA
Default key algorithm	`rsa4096`	`rsa4096`
Default validity	10 years (1–30)	5 years (1–20), clipped to the parent’s remaining life
Supported key algorithms	`rsa2048`, `rsa4096`, `ec256`, `ec384`	same

Creating a CA

On the PKI page, the left panel lists your Certificate Authorities as a tree. Use Root CA to create a self-signed root, or Import to bring in a CA you already have.

When creating a Root you supply a display name and the subject fields — Common Name plus optional Organization, Organizational Unit, Country, State, Locality — along with the key algorithm and validity in years. To build a hierarchy, create an Intermediate and pick its parent CA.

Importing an existing CA

Import brings in a CA you already operate: paste the CA certificate (PEM) and its private key (with the key password if it is encrypted), choose whether it is a root or intermediate, and — for an intermediate — point it at its parent. On import Taranac validates the material strictly and rejects anything that is not a usable CA:

the PEM must parse;
it must carry BasicConstraints with CA = true;
if it carries KeyUsage, keyCertSign must be set (a CA certificate with no KeyUsage extension at all is accepted, with a warning in the log);
it must not be expired;
if a private key is supplied, it must match the certificate;
an intermediate must actually be signed by the parent CA you reference.

CA status and lifecycle

Each CA has a status — active, expired, revoked, or disabled. Only active CAs can issue certificates, and only active, enabled CAs are written into the FreeRADIUS bundle. Disable a CA to pull it out of the trust bundle without deleting it. A CA can only be deleted once it has no active issued certificates and no child CAs — which protects you from orphaning live credentials or cutting a chain in half.

Issued certificates

The right panel lists everything an Internal CA has issued, filterable by Status (active / revoked / expired) and Type (user / device / server). Each row shows the name, type, subject, serial, issue date, and expiry.

Issuing a certificate

Use Issue Certificate to have Taranac generate a key pair and sign the certificate in one step, or From CSR to sign a Certificate Signing Request from a device that generated its own key (the private key never leaves the device — Taranac stores only the signed certificate).

Field	Notes
CA	Which Internal CA signs it (must be `active`).
Name	Admin label, e.g. “John — Laptop”.
Type	`user`, `device`, or `server`. User/device get `clientAuth`; server gets `serverAuth`.
Subject CN	e.g. `john@company.com` or `LAPTOP-001.company.local`.
Key algorithm	`rsa2048`, `rsa4096`, `ec256` (default), `ec384`.
Validity (days)	Default 365, capped at the CA’s own expiry.
SAN — UPN / email	For user certificates (e.g. `john@company.com`).
SAN — DNS / IP	For device certificates: FQDNs, and IP addresses for a device reached by address. Up to 20 of each.
Linked user / endpoint	Optionally tie the certificate to a Taranac user or endpoint for tracking and lifecycle.

Downloading

Download an issued certificate as a password-protected PKCS#12 (.p12) archive — the usual choice for installing on a laptop or phone — or as PEM. You can include the CA chain in the download. For user-facing delivery, Taranac can instead email a one-time download link (see Delivering certificates to users below) so you never handle key material by hand.

Revoking, reassigning, reissuing

Revoke marks a certificate revoked with an RFC 5280 reason (key_compromise, ca_compromise, affiliation_changed, superseded, cessation_of_operation, certificate_hold, unspecified) and immediately regenerates the CA’s CRL so the credential stops authenticating.
Reassign applies only to device certificates: hand a device certificate to a different user, or unlink it entirely. User certificates cannot be reassigned.
Reissue and send revokes the old certificate (reason superseded), issues a replacement from the same CA with the same label, type, subject and key algorithm — carrying over its email and DNS SANs, with a new key, and dated to expire when the old one would have — then emails the user a download link. The clean recovery path when a certificate is lost or suspected compromised.

The server certificate

EAP-TLS and PEAP both require the RADIUS server to present its own certificate to clients. The Server Certificate card manages that identity — it lives on Settings → NAC, not on the PKI page itself. Exactly one server certificate is active at a time, and it has three possible sources:

Source	When to use it
`self_signed`	Default on first boot. Fine for a lab or closed pilot; clients must be told to trust it (or skip server validation).
`internal_ca`	Issue the server certificate from one of your Internal CAs — clients that already trust the CA validate the server automatically.
`uploaded`	Upload a certificate from a public or corporate CA (cert + key + chain). Best when clients should validate the server against a CA they already trust.

After uploading or issuing, press Deploy to FreeRADIUS. The material is written into the RADIUS service’s config volume and the daemon is restarted in place — a sub-second restart, with nothing to restart by hand. The card then reports In use by the service: Applied (and since when), Awaiting service restart while the running process is still presenting a different certificate, or Unknown on a node whose daemon has not yet reported. That badge describes what FreeRADIUS actually loaded, not what was written to disk.

A CSR for an external CA can be generated through the API (POST /api/v1/nac/server-cert/csr); the card itself offers upload, self-signed generation, issuance from an Internal CA, and deploy.

Uploading or issuing one wrote it to a directory the RADIUS service could not read, and every layer above reported success — the file was written, the record was stamped deployed, the card said Deployed — while supplicants kept being shown the built-in certificate. This had never worked, in any release. Updating repairs it: a certificate already marked as deployed is re-delivered at start-up. Other 802.1X material — trusted CAs, revocation lists — was never affected.

The same release stopped the 802.1X private key being world-readable inside the RADIUS container. The retired nac_certs volume is detached but left behind untouched; once the update is confirmed working it can be removed (docker volume rm taranac_nac_certs — the name carries your compose project prefix). The key inside it is the built-in one, not an uploaded key, and it is replaced by the update.

Trusted CAs — trust without issuing

The Trusted CAs page is for the case where certificates are issued elsewhere and you only need Taranac to trust them. Upload the CA’s PEM certificate and Taranac adds it to the bundle. Per trusted CA you also configure:

Setting	Values	Purpose
Identity source	`cert_cn`, `cert_san_upn`, `cert_san_email`, `cert_subject`	Which field of the client certificate becomes the authenticated identity for policy.
Cert type	`user`, `computer`, `both`	What kind of certificates this CA is allowed to authenticate.
CRL checking	on/off + CRL URL or uploaded CRL	Whether revocation is enforced for this CA.
OCSP	on/off + OCSP URL	Optional OCSP revocation checking.

This is the typical path for a Windows estate that already issues machine and user certificates from Active Directory Certificate Services (AD CS) — you trust the AD CS CA and let domain-joined devices authenticate with the certificates they already hold.

Taranac re-fetches CRLs from configured URLs on a schedule (every 6 hours by default). Since 1.2.2 the fetcher validates the target before connecting, pins the connection to the address it validated, verifies TLS, caps the download at 5 MB and follows at most three redirects — and it refuses any URL that resolves to a loopback, private, link-local or reserved address, redirects included. There is no override.

So a CA whose distribution point sits inside your own network — the usual case for AD CS — cannot be fetched by URL. Upload the CRL on the Trusted CA instead (PEM or base64 DER), or publish it somewhere with a globally routable address. Fetch failures surface as a reason on the Trusted CA itself, deliberately without describing what was found on the other end.

CRL — keeping revocation enforced

When you revoke a certificate, Taranac re-signs the issuing CA’s CRL and writes it where FreeRADIUS reads it, then reloads. A daily worker also re-signs every active CA’s CRL so the nextUpdate timestamp stays fresh, and a status worker marks expired certificates as expired.

CRL checking is a single global toggle — CRL Control on Settings → NAC, which also sets how often CRLs are fetched from configured URLs. When it is on, FreeRADIUS requires a valid CRL for every CA in the bundle — Internal, Trusted, and LDAP alike. If any CA is missing a CRL, client certificates from that CA are rejected. Taranac’s pipeline deploys CRLs for all three sources to keep this consistent, but it is the thing to check first if certificates from one issuer suddenly stop authenticating after you enable CRL checking — the CRL Status tab of the Certificate Store names exactly which CAs have none.

Publishing a CRL

Certificates an Internal CA issues carry a CRL distribution point so clients and network gear can fetch the revocation list themselves. Taranac serves it, without authentication:

URL	Encoding
`/api/v1/public/crl/{ca_id}.crl`	DER (`application/pkix-crl`) — what network equipment expects
`/api/v1/public/crl/{ca_id}.pem`	PEM — convenient for `openssl` and for humans

Fill in Public base URL under Public endpoints on the PKI Settings page and every CA’s distribution point is derived from it automatically — adding a CA does not mean remembering to paste a URL, and moving the hostname is one setting to edit. A CA can still carry an explicit URL of its own, which wins. With neither set, issued certificates carry no CDP extension at all.

Use plain http:// for that base URL: validating a certificate must not first require validating the certificate of the server holding the revocation list.

EST — automated enrollment

EST (RFC 7030) lets devices and MDM systems request and renew certificates over HTTPS without manual P12 handling. Taranac exposes the standard EST endpoints under /.well-known/est/ (cacerts, simpleenroll, simplereenroll, csrattrs). Configure it on the PKI Settings page, which also prints the four full URLs to paste into an enrollment profile.

Setting	Default	Description
Enable EST endpoint	off	Turns `/.well-known/est/` on. Everything below is inert until it is.
Issuing CA	—	Which Internal CA signs EST-enrolled certificates.
Certificate validity (days)	365	1–3650, clipped to the issuing CA’s own expiry.
Require admin approval	off	Requests are queued for a human decision instead of being issued on the spot.
Approval group	—	Whose members are emailed about a waiting request. Notification only — see below. LDAP groups work here.
Request lifetime (days)	30	How long an undecided request survives before it is marked `expired`.
Allowed authentication methods	Basic + TLS	Or Basic only, or TLS only.
Identity binding	`strict`	`strict` — the server writes the authenticated identity into both CN and SAN. `device` — keep the CSR’s CN and take the SAN from the CSR’s own DNS/IP names, which must be present.
mTLS proxy secret	empty	Shared secret proving that client-certificate headers came from your TLS terminator. Empty means mutual TLS is not deployed.

The SAN is always written by the server, never by the requester. EAP-TLS authorization keys off the SAN, so a client that could choose it could mint any other identity on the network. Identity binding only decides which identity goes in: the authenticated principal (strict, right for people and BYOD — the certificate is stored as a user certificate) or the device’s own names from its CSR (device, right for equipment enrolling through a shared service account — stored as a device certificate, and reassignable).

Authentication. First enrollment is HTTP Basic over TLS, verified against a Taranac local account with a local password; a directory account has no local hash and is refused. Mutual-TLS identity reaches the backend only as X-SSL-Client-* headers set by whatever terminates the client-certificate handshake, so it is believed only when that terminator also echoes the mTLS proxy secret. With no secret configured the headers are ignored outright — the safe default, and the reason leaving it empty costs nothing.

Renewal. simplereenroll requires mutual TLS, and since 1.2.2 a renewal is checked against revocation before it is granted: the presented serial must resolve to a certificate Taranac itself issued, that certificate must still be active, and the CSR must keep the same subject. A revoked certificate can no longer be used to obtain its own replacement. Taranac does not yet ship the client-certificate-verifying listener that mutual TLS needs, so until it does, renewal in practice goes back through simpleenroll and authenticates the way an enrollment does.

The approval queue

With Require admin approval on, an enrollment produces a request, not a certificate. The client is answered 202 Accepted with a Retry-After and keeps re-sending the same CSR, per RFC 7030 §4.2.3. Requests are identified by the SHA-256 of the DER CSR, so a device waiting overnight leaves one row rather than thousands.

What the next poll finds	What the client gets
`pending`	`202` — keep waiting
`approved`	`200` with the certificate the approver caused to be issued
`rejected`	`403`, so the client stops instead of polling forever
`expired`	back to `pending` — a client still asking revives its own request

The queue sits on the PKI page below the issued-certificate table, and renders itself away when nothing is queued.

Deciding is the nac_pki.edit permission — not membership of the approval group. The group is a notification channel layered on top: its members are emailed what is being issued, to whom and from which address, each with a one-time link of their own, so a decision is attributed to a person rather than to whoever held the link. No group means nobody is emailed, not that nothing is checked.

The link never acts on being opened. Mail scanners, Safe Links and messenger previews follow URLs by themselves, so the GET only renders a page and the decision needs a deliberate confirmation. Any decision — by link or in the UI — spends every outstanding link for that request, so a second click cannot re-decide a settled one.

Approval gates issuance on a human; it does not bypass anything. An approved request is signed through exactly the same path an auto-issued enrollment takes, with the same identity binding and the same server-written SAN.

Taranac chose EST over the older SCEP because it runs over HTTPS with strong authentication (mutual TLS or Basic over TLS), has a clean renewal flow (simplereenroll), and is supported by modern iOS, Windows, Android, and ChromeOS. Leave Require admin approval off for demos and pilots; turn it on in production so enrollment requests are reviewed before a certificate is signed.

Delivering certificates to users

Rather than emailing key material yourself, Taranac can generate a one-time download link: a single-use URL that delivers the P12/PEM and shows its password, valid for the Download link expiry set on PKI Settings (72 hours by default, 1–720). Use Send link for one certificate, Send all certificates for every active certificate a user holds, or Reissue and send to rotate a compromised credential. Optionally, Taranac can auto-issue a certificate when a local user is created or when a new LDAP user is first synced, using your configured certificate defaults, and email the link automatically.

Certificate defaults (on PKI Settings) pre-fill the issuing CA, key algorithm, validity, and templates for the subject and label, so issuing is one click and stays consistent. The Organization (O) is inherited from the issuing CA, following standard PKI practice.

When to use what

Internal PKI vs. external / trusted CA

Situation	Recommendation
Pilot, demo, lab, or greenfield site with no existing PKI	Use the Internal CA — stand up a Root (or Root + Intermediate) and issue from it. No external infrastructure needed.
Windows estate already issuing certificates from AD CS	Add the AD CS CA as a Trusted CA (or via the LDAP/EAP-TLS source). Let domain devices use the certificates they already have.
Mixed: domain laptops via AD CS, plus BYOD / contractors / IoT	Trust AD CS and run an Internal CA for the non-domain devices. Both feed the same bundle.
You need automated, hands-off enrollment and renewal for managed devices	Use the Internal CA as the EST issuer and enroll via MDM.
Clients must validate the RADIUS server against a CA they already trust	Source the server certificate from that external/public CA (upload) rather than self-signed.

Key algorithm and validity guidance

Certificate	Suggested algorithm	Suggested validity
Root CA	`rsa4096` or `ec384`	10–20 years
Intermediate CA	`rsa4096` or `ec384`	3–5 years
User / device certificate	`ec256` (default) or `rsa2048`	1 year (365 days)
Server certificate	`rsa2048`	1–2 years

Reference

Certificate types

Type	Extended Key Usage	Typical subject / SAN
`user`	`clientAuth`	CN = `user@domain`; SAN = UPN and/or email
`device`	`clientAuth`	CN = device FQDN; SAN = DNS name(s); reassignable between users
`server`	`serverAuth`	the RADIUS server identity (one active)

Revocation reasons

key_compromise · ca_compromise · affiliation_changed · superseded · cessation_of_operation · certificate_hold · unspecified

Maintenance schedule (automatic)

Task	Cadence
Re-sign CRLs for all active Internal CAs	daily, 03:00
Mark expired certificates `expired`, and undecided EST requests `expired`	daily, 03:30
Clean up used / expired download tokens	daily, 04:15
Expiry check — server certificate, Internal CAs, issued certificates	daily, 06:00
Fetch CRLs from configured URLs (Trusted CAs and LDAP configurations)	every 6 hours, configurable

The expiry check writes warnings to the service log — server certificate at 30 days (critical at 7), Internal CA at 90 days (critical at 30). It does not send mail. What to watch instead is the dashboard’s certificate expiry widget, which lists what runs out inside 90 days with an expired / ≤7 days / ≤30 days badge and links straight back to this page.

NAC policy — how an authenticated certificate identity drives access decisions.
Endpoints — devices a certificate can be linked to.
Captive portal — onboarding flows for devices that are not yet certificate-enrolled.
Deployment bundle & docs: github.com/TaranacLabs/taranac