FreeIPA PKINIT client enrollment

FreeIPA PKINIT client enrollment: when a host certificate is the right credential

A platform team enrolling many Linux hosts usually wants to avoid two things: sharing an administrator password across build pipelines, and handing out one-time passwords that someone must type or copy onto each machine. PKINIT lets a host authenticate to the Kerberos KDC with a certificate it already holds, so enrollment can rely on an identity the host already has rather than a shared secret. In FreeIPA, the MIT Kerberos KDC handles the authentication, and the integrated Dogtag certificate authority is what issues and tracks the certificates involved. That combination matters because the trust chain is controlled by your own CA, not by a password that has to be rotated or distributed. Teams usually reach for this model when they already run a certificate lifecycle for hosts, when machines are built by automation such as image pipelines or configuration management, and when no operator should sit at a console during enrollment. Check whether your hosts already receive certificates from a source that FreeIPA can trust, who issues and renews them, and how long they last. If the certificates come from a different CA, you will need to decide whether FreeIPA should trust that CA or whether certificates should be issued through Dogtag instead. Ask who owns the private key on each host and whether it can be protected at rest.

The exact enrollment flow, the required certificate profile and the client distributions that support PKINIT enrollment all depend on the FreeIPA release you run, so confirm them against the current FreeIPA documentation for that release before you design the pipeline. Test on one representative host per distribution in your estate, and record the exact ipa-client-install options and client packages that worked. Plan for failure cases as well: an expired host certificate, a certificate that does not map to the expected host principal, or a CA that is unavailable during a rebuild. Each of these can block enrollment at the moment you need it most, so decide in advance how a failed host is re-issued, which team can approve that, and how the event is logged. PKINIT is one option among several, and it does not remove the need for careful host naming, DNS and time synchronization. Compare it with one-time password enrollment for hosts that have no certificate yet, and document which path each host class uses. A short written decision per host class, covering the credential, the owner of the certificate lifecycle and the rebuild procedure, will do more for audit readiness than the enrollment command itself.

Enrollment credentials compared: password, OTP and PKINIT

This table compares the three ways a FreeIPA client can prove its identity during enrollment: a privileged user's password, a pre-created one-time password, and a certificate-based PKINIT credential. Read each row as a question to answer for your estate before choosing a method. The main takeaway is that PKINIT moves the secret from a typed or shared value into a certificate that must already exist and be trusted by the IPA server.

Factor	Privileged user password	Pre-created one-time password	PKINIT with host certificate
Who creates the credential	An administrator who already holds an enrollment-capable IPA account	An administrator who pre-creates the host entry in IPA	The certificate authority that issued the host certificate, typically the IPA CA or an approved external CA
How it reaches the host	Typed at the console or passed in an unattended install command	Passed to ipa-client-install or a kickstart file, usually by automation	Certificate and key files placed on the host before enrollment runs
How long it stays valid	Until the account password changes or the account is disabled	Confirm expiry and single-use behavior in the enrollment docs for your release	Set by the certificate validity period, confirm renewal behavior for your profile
What it leaves on the host	Host keytab and client configuration, password not stored by the client	Host keytab and client configuration, OTP consumed on use	Host keytab and client configuration, plus the certificate and key files you placed
What it needs from certificate infrastructure	Nothing beyond a working IPA CA for later host certificates	Nothing beyond a working IPA CA for later host certificates	A certificate chain the IPA server trusts, a host principal that matches the certificate, and a secure way to deliver the key
Best fit for kickstart and cloud images	Weak fit, because the password must be shared with build pipelines	Good fit when a pipeline can fetch a one-time value at build time	Good fit for images that receive a certificate at boot from an existing trust chain
Best fit for manual enrollment	Good fit for small estates with few hosts	Reasonable, but adds a pre-creation step per host	Possible, but adds certificate handling work for each host
Main risk	Credential reuse and broad exposure if the password is shared	Leftover OTPs in build logs or templates if not handled carefully	Key material exposed if the private key is copied insecurely or left in images

Preparing host certificates and the CA trust chain for PKINIT

Before any host enrolls with PKINIT, the host certificate has to be right on five points: the subject and subject alternative name must carry the host's fully qualified domain name, the key usage and extended key usage must allow the use the enrollment needs, the issuing CA must be trusted by the FreeIPA KDC, the certificate must be valid for longer than your change window, and the private key must sit where the enrollment tooling can read it. Treat these as a checklist to run against each certificate, not as assumptions about what a generic internal CA issues. Confirm the required certificate profile, including the expected key usage and extended key usage values for Kerberos PKINIT, in the FreeIPA PKI documentation before you issue anything. The exact values depend on your FreeIPA version and on how the KDC is configured, so do not copy them from an older internal template.

The most common failure is a CA that FreeIPA does not trust. The KDC can only validate a PKINIT client certificate if the signing chain leads to a CA it has been told to accept, so the root and any intermediate certificates must be in place on the FreeIPA side before enrollment is tested. A second failure is a name mismatch: a certificate issued for a short name, an old alias or an address will not match the DNS record the client resolves, and the enrollment will fail in ways that look like authentication errors. Check forward and reverse DNS for the host, then compare them with the certificate. Expired or near-expiry certificates fail the same way, so build a renewal date into your provisioning plan rather than discovering it during a rebuild.

The third group of mistakes concerns the private key. If the key file is owned by the wrong user, sits on a path the enrollment process cannot open, or is stored in a format the tooling does not expect, enrollment will fail even when the certificate itself is correct. Keep the key readable only by the account that performs enrollment, and record where each key lives. For a fleet, ask your team which provisioning tool reads the key, under which account, and whether the key is encrypted. Test one host end to end, including a host rebuild, before you scale the process. Verification and the enrollment steps themselves are covered elsewhere on this page.

Setup sequence for PKINIT enrollment, with a check at each step

This sequence takes a Linux host from an existing certificate and key to a FreeIPA-enrolled client that obtains Kerberos tickets and resolves identities through SSSD, with a check after each step so failures are caught where they start.

Confirm server and client versions support PKINIT
Before changing anything, confirm that your FreeIPA server release and the client OS packages both support enrollment with PKINIT and host certificates. The FreeIPA 4.13.x release notes and the client packaging for your distribution are the sources to check, since PKINIT behavior depends on the Kerberos and SSSD builds on the host, not only on the server. Record the server version, client OS release and krb5 and SSSD package versions in your change record. Done means every version is written down and matched against the release documentation, and any gap is raised before the next step. Confirm the exact option names for PKINIT enrollment in the ipa-client-install man page for your release rather than relying on examples from older guides.
Prepare the trusted CA chain on the server
The FreeIPA server must trust the certificate authority that signed the host certificate, so the full chain, root and any intermediate, has to be present in the IPA trust store and the host certificate must chain to it. Obtain the chain from the issuing team as PEM files, verify it offline with openssl verify against the root, and confirm the host certificate's subject or subject alternative name carries the fully qualified host name that FreeIPA will use. Check that the certificate is within its validity period and that its key usage permits client authentication. Done means openssl verify returns OK for the host certificate against the supplied chain, and the chain is recorded alongside the change so an auditor can trace it.
Pre-create the host record in FreeIPA
Create the host entry on the FreeIPA server with an administrator account before enrollment, so the enrollment does not depend on a shared password or a one-time password typed on the client. Use the host add command with the fully qualified name and the same name that appears in the certificate, and record who created it and when. Confirm the host entry exists and that its name matches the certificate subject, because a mismatch is a common reason certificate-based enrollment fails. Done means ipa host-show returns the expected host record with no keytab yet issued, and the name is identical to the certificate's identity.
Place the host certificate and key with restricted permissions
Copy the host certificate, the private key and the CA chain to the client, into a directory readable only by root, such as a dedicated path under /etc/pki with the key set to mode 0600 and owned by root. Avoid leaving copies in home directories, configuration management working trees or shared repositories. Confirm with ls -l and stat that the key is not group or world readable, and confirm the certificate and key match by comparing their modulus or public key fingerprints with openssl. Done means the key permissions are restricted, the certificate and key pair match, and the file paths are recorded for use in the enrollment command.
Run the enrollment command with PKINIT options
Run the client installation with the PKINIT options for your release, pointing it at the certificate, key and CA chain, and with the explicit server, domain and realm so the host does not guess them. Confirm the option names and their required combinations in the ipa-client-install documentation for your version before running it, and use a test host first. Keep the output log, since it records the steps the installer completed. Done means the command exits successfully, the installer reports the host as enrolled, and no password or one-time password was needed on the command line.
Verify the keytab and Kerberos ticket
Check that the host obtained its keytab and that the host principal can authenticate. Run klist -k on the client to confirm the host principal is present in /etc/krb5.keytab, then use kinit with the host principal and the keytab, or a test user, to acquire a ticket and confirm it with klist. The exact host principal and any PKINIT-specific flags for kinit should be confirmed in the MIT Kerberos documentation for your distribution. Done means klist -k lists the host principal and a ticket is obtained and shown as valid, with the expiry time matching the configured policy.
Confirm SSSD lookups resolve identities
Verify that SSSD is running and resolving directory identities from FreeIPA. Check the service status with systemctl, then run id on a known FreeIPA user and getent passwd and getent group for the same user and a group. Confirm that the host can resolve the IPA server through DNS, since SSSD lookups depend on it. Done means the id command returns the expected UID, GID and groups for the test user, and getent returns the same entries, which shows that SSSD and the FreeIPA server are both working.
Remove certificate-based credentials from unattended paths
Once the host principal and keytab work, remove any copies of the host certificate and key from locations used by unattended jobs, such as automation staging directories, image build paths and backup sets that do not need them, and keep only the copy the host requires under its restricted path. Document where the credential now lives, who can read it and how it is rotated, and check that cron jobs and configuration management no longer reference the removed files. Done means a search of the build and automation paths finds no stray copies, and the remaining credential location is recorded in the host runbook.

Where PKINIT fits in kickstart, image builds and manual enrollment

Unattended installs suit PKINIT when each host can receive its own host certificate and key at build time, usually from a provisioning server or a secrets store the installer can reach. The installer fetches or places the material during the post-install phase, so the key never has to be stored in the kickstart file itself. This keeps the enrollment credential tied to one machine and avoids putting a reusable secret in version control.

Per-host material: The build system generates or retrieves a certificate and key for each host name, not one for a group of hosts.
Secret handling: Kickstart files and ks.cfg templates should reference the material by path or lookup, never embed the private key.
Host record first: Create the host entry in FreeIPA, and the certificate's subject must match that host's fully qualified name.
Fallback path: If the build cannot deliver certificates on time, a one-time password enrollment is usually the simpler choice for this build.

Before rollout, confirm with your FreeIPA and SSSD versions that the client install options you use support the enrollment method you chose, and test one host end to end.

Security risks of certificate-based enrollment and how to contain them

Certificate-based enrollment removes the shared password from host builds, but it moves the trust into a private key, a certificate lifetime and the FreeIPA servers that issue both. Each card below names one risk, the containment step to design in and what to confirm in your own environment before rollout.

Private key exposure on the host

The host's private key is the credential. If it lands in a golden image, a backup, a configuration management repository or a build artifact, anyone who copies it can enroll or impersonate that machine. Restrict the key file to root-only permissions, keep it out of images and templates, and check that your provisioning tool never writes it to logs. Confirm how your kickstart, cloud-init or Ansible workflow handles the key before the first build.

Separate keys for build pipelines

A key created for an image build should not also be the key used by production hosts. If a build system is compromised, a shared key exposes every machine it touched. Issue distinct, narrowly scoped certificates for each build pipeline, record which pipeline holds which key, and retire the key once the image is sealed. Ask your team to document the owner of every enrollment certificate in use.

Certificate lifetime and renewal

An enrollment certificate that expires silently can stop a host from authenticating, while one with a long lifetime keeps a stolen key useful for longer. Set the lifetime with your certificate policy team, decide who renews and how, and test renewal on a non-production host before relying on it. Confirm the default validity period and renewal behavior for your FreeIPA version in the documentation before you set any value.

Revocation after compromise

When a host is compromised, you need to know which certificate to revoke, how quickly that revocation reaches your FreeIPA servers, and what the host can still do in the meantime. Map each host to its certificate serial, and rehearse the revocation and host-disable steps as a runbook. Confirm with your FreeIPA administrators how revocation interacts with Kerberos tickets already issued to that host, since existing sessions may remain valid until they expire.

Scope of the enrollment identity

The principal a host presents during PKINIT determines what it can do after enrollment. An identity that can add arbitrary hosts or read unrelated services turns one enrollment key into a directory-wide foothold. Limit the enrollment identity to creating or enrolling the specific hosts it needs, review the access rules that apply to it, and confirm with your administrators that it cannot grant itself broader rights through delegation or role membership.

Audit of enrollments and protection of FreeIPA servers

Enrollments create a record of which host joined, when and under which identity, but only if someone reviews it. Pair regular enrollment log review with protection of the FreeIPA servers themselves, since a compromised server can issue or accept certificates for any host. Keep those servers dedicated, limit administrative access, and confirm which audit logs your installation writes and where they are forwarded before you depend on them.

What to confirm in your environment before committing to PKINIT

Before you choose PKINIT for enrollment, confirm the FreeIPA server release and the client operating system versions in your estate. PKINIT depends on the server, the Kerberos stack and SSSD on each client, so the combination you run matters more than the server version alone. Ask the vendor or project for the support statement covering each client distribution you plan to enroll, and record the source. DeployOpen confirms the server release, client inventory and version matrix during scoping, but the support position for a specific distribution has to come from that distribution's or the FreeIPA project's own documentation, not from a consultant's assumption.

Next, establish whether your existing certificate authority can issue the host certificate profile that PKINIT needs. Check who signs host certificates today, which profile and key usage they apply, whether the subject names and Subject Alternative Names match the FreeIPA host principals, and whether the CA is an internal authority, a public authority or a separate enterprise PKI. Confirm with your PKI owner whether the issuing chain is trusted by the FreeIPA server. Also settle who owns issuance and renewal: the team that signs certificates, the team that runs the automation that requests them, and the team on call when a renewal fails must be named before rollout, not after.

Finally, define how enrollment will be audited and what fallback applies when a certificate is missing or expired. Decide which logs you will keep from the FreeIPA servers and the provisioning system, who reviews them, and how a host enrolled with a certificate is traced back to the request that issued it. For the fallback, decide in advance whether an expired certificate blocks enrollment outright, whether a one-time password path is permitted for recovery, and who may approve that exception. Write these decisions down as part of the scope, because a fallback that exists only in someone's head tends to become an unreviewed shortcut.

Questions teams ask before enrolling FreeIPA clients with PKINIT

How much more effort is PKINIT enrollment than OTP enrollment?

PKINIT usually takes more up-front design work, but less repeated handling per host. OTP enrollment needs a one-time password created for each host and delivered to the build, so the work scales with every rebuild. PKINIT needs a certificate issuance path, trust configuration on the FreeIPA side and a way for the build to present the host certificate and key at enrollment. The effort drivers are how many build paths you have, whether certificates already come from an authority you control, and how much testing you need before rollout. The FreeIPA certificate authority and PKI topic covers the server side in more detail. Ask any partner for a written breakdown of the design, build, testing and handover work before accepting a quote.

Can our own team do PKINIT enrollment without a partner?

Yes, if your team already runs FreeIPA and controls a certificate authority that can issue host certificates. The work is well defined: confirm how FreeIPA trusts your issuing CA, set certificate profiles for hosts, adjust the image or provisioning pipeline, and test enrollment on a small set of machines. Teams usually need outside help where the build system is complex, several operating systems and images are in use, or the certificate process runs through a separate PKI team with its own approvals. Whatever you choose, document the decision, because the people who build hosts later will need the same steps.

What does the work need from our side?

Plan for four inputs from your organization:

Access to the certificate authority that will issue or sign host certificates, with a named owner for approvals and renewals.
Agreed certificate profiles for hosts, including subject naming, key type and lifetime.
Changes to your build pipeline, such as kickstart, image or configuration management steps that place the certificate and key on the host before first enrollment.
Test hosts, a staging FreeIPA environment or a safe enrollment window, and someone who can check results.

If any of these sits with a different team, schedule that team early, since approvals often set the pace of the project. Confirm the exact commands and configuration keys against the FreeIPA documentation for your installed version.

How long does a PKINIT pilot take, and what drives that?

The length of a pilot depends on your environment, not on a fixed schedule. The main drivers are the number of build paths (each image, template or OS family needs its own check), how quickly the certificate authority team can issue and approve profiles, the number of hosts in the first wave, and how much change control your organization requires. A pilot with one build path and a responsive CA team is much shorter than a pilot spanning several operating systems and regulated change windows. Ask for a written plan that lists each milestone, the owner of each approval and the test evidence you will receive at the end. Do not accept a duration that is not tied to those items.

Can we safely reuse existing host certificates?

You can reuse them only when they meet the requirements FreeIPA and your policy set. Check that the certificate is issued to the host's fully qualified domain name, that its key pair and signature algorithms are accepted by your FreeIPA version, that the issuing CA is trusted by the FreeIPA realm, and that the private key is protected on the host. Certificates that are shared between hosts, issued for a generic name, or stored in a location other machines can read should not be reused for enrollment. Treat reuse as a decision with a documented owner, and have your security team review the key handling before the first host enrolls.

What happens to enrolled hosts when their certificate expires?

Expiry affects the host's ability to authenticate with the certificate, so the renewal process must be designed before rollout. Confirm how the certificate will be renewed, who receives the alert before expiry, and whether a host that cannot renew will keep working through a password or keytab-based path or stop authenticating. Test an expired-certificate scenario on a non-production host so you know the recovery steps before they are needed. The FreeIPA certificate authority and PKI topic covers renewal and recovery in more depth. Ask your provider how renewal monitoring will be handed over and who will run it after the project ends.

How DeployOpen scopes and delivers FreeIPA client enrollment

DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including FreeIPA. For PKINIT enrollment, we start from your existing host certificate process and the FreeIPA servers you already run, then deliver a tested, documented enrollment path your team can operate.

How we scope

The written scope lists which host populations, operating systems and certificate sources are covered for PKINIT enrollment.
We confirm the FreeIPA server version, certificate trust chain and host certificate lifecycle before any build work starts.
Engagements are fixed-scope, so deliverables and timelines are agreed in writing before work begins.

How we build

We configure PKINIT on the FreeIPA side and build the client enrollment steps against your existing host certificates.
Enrollment is tested on representative hosts, including a failed-enrollment and expired-certificate case, before wider rollout.
Automation for provisioning pipelines is built and reviewed alongside the manual procedure, so both paths behave the same way.

How we hand over

You receive runbooks covering enrollment, certificate renewal checks, re-enrollment and the rollback steps we tested.
Configuration, test results and known limits are documented so your engineers can repeat the procedure without us.
Handover includes a walkthrough with your identity, platform and security staff on the enrollment and troubleshooting steps.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after handover.
Retainer coverage for PKINIT enrollment should be confirmed in writing, including FreeIPA server upgrades that affect certificate handling.
Ask for a quote built from the written scope, since DeployOpen does not publish a price list.

Enrolling FreeIPA clients with PKINIT and host certificates