How FreeIPA service principals and keytabs let services use Kerberos
Your internal service needs a Kerberos identity and a keytab on a host you control. In FreeIPA, the service gets a service principal, which is the Kerberos name the rest of the environment uses to recognize it, and a *keytab* file, which holds the long-term key that lets the service prove that identity without a password prompt. Three components do the work. The MIT Kerberos KDC issues the tickets and holds the keys, 389 Directory Server stores the principal and its metadata as directory entries, and SSSD on the client host manages the local identity and keeps the service's view of the realm consistent.
The FreeIPA workshop on web application authentication and authorization shows the basic pattern. An administrator creates the service principal, retrieves its keytab with an admin ticket, and copies that keytab to the host where the service runs. Host and service permissions then decide who may create or retrieve keytabs for that service, so the person who installs the application does not need general administrative rights. The workshop is a useful first read, and the FreeIPA workshop on web application authentication and authorization walks through each step in a lab setting.
Before you copy a keytab anywhere, confirm three things in your own environment: the host that will hold the keytab is enrolled in FreeIPA, the file permissions on the keytab restrict reads to the service account, and you have a written decision on who may retrieve the key later. Treat each keytab as a credential. A copy left on a laptop or in a build log is a copy that can impersonate the service, so record which host holds each keytab and plan how you will rotate it when a host is retired or a person with access leaves.
What you need before registering a service principal
Registering a service principal touches the FreeIPA servers, the host that will hold the keytab, the account that performs the work, and the network names and clocks that Kerberos depends on. Confirm each of the items below before you create anything, because a mismatch in any one of them usually shows up later as a failed ticket request rather than a clear error.
A running FreeIPA deployment
Confirm which FreeIPA server version your deployment runs and check it against the 4.13.4 release notes, which describe fixes to LDAP access control and API authentication checks. Also confirm the service's own Kerberos library requirements, since older client libraries may not handle the encryption types your KDC issues. Record the server host names and which replica you will use, because the principal and keytab operations run against the server you target. Plan this on servers you control, with the IPA domain and realm already settled.
An enrolled client host
The keytab is written to the host that runs the service, so that host must be enrolled as an IPA client with SSSD working before you begin. Check that the host name in its Kerberos configuration matches the host you intend to register. Decide which Linux account will own the keytab file and confirm that account exists on the host. Enrollment problems are easier to fix before the keytab exists than after an application has started using it.
An administrator or delegated account
Creating a service principal and retrieving its keytab both require an authenticated FreeIPA identity with the right permissions. Name the account that will run these steps, whether it is an administrator or a user granted host and service permissions, and obtain a valid Kerberos ticket for it with kinit before running any command. Confirm in advance who is allowed to create and retrieve keytabs for this service, because those permissions are set separately from general administration rights.
DNS names that agree
The service principal includes a fully qualified host name, and Kerberos clients derive the service name from the host they connect to. Confirm that forward and reverse lookups for the service host return the same name the principal uses, and that the name resolves from every client that will reach the service. Mismatched names are a common cause of lookups that succeed for IP addresses but fail for the name the client requested. Check DNS on your FreeIPA servers and on the client before you register the principal.
Synchronized clocks
Kerberos rejects tickets when the clocks of the KDC, the client and the service differ by more than the allowed skew, which fails authentication with errors that look unrelated to time. Confirm that every FreeIPA server, the enrolled host and any intermediate systems synchronize against the same NTP source. Check the status of time synchronization on each machine before retrieving the keytab, since a clock error will look like a credential problem.
How to create a service, retrieve its keytab and install it
This sequence takes a service from an enrolled FreeIPA host to a working Kerberos service principal, with a keytab that the service reads and a test ticket that proves the handoff worked. Each step ends with a check you can run before moving on.
Confirm the host is enrolled in FreeIPA
Before creating anything, confirm that the machine running the service is an enrolled FreeIPA client with a host principal. An administrator or the team that owns enrollment runs
ipa host-showfor the fully qualified host name and checks that the entry exists and shows the expected enrollment details. On the host itself,klist -k /etc/krb5.keytabshould list the host principal. If either check fails, fix enrollment first, because a service principal is tied to a host entry and cannot be used on a machine FreeIPA does not know about.Create the service principal for the host
An administrator with rights to manage services creates the principal using the service name and the fully qualified host name, for example
HTTP/web01.example.internal, withipa service-add. Use the exact host name that clients will put in their requests, because Kerberos matches service names character for character. Confirm the result withipa service-showfor the same principal, which should show the host it belongs to and the realm. Who is allowed to do this depends on the roles and permissions in your deployment, so confirm that with the team that administers FreeIPA.Retrieve the keytab with an admin ticket
On a machine where an administrator has a valid Kerberos ticket, run
kinitas that administrator, thenipa-getkeytabwith the service principal and an output path. Write the file to a restricted location and set its permissions so that only the service account can read it, for example by creating it with mode 0600 and owned by the service user. Confirm the retrieval by runningklist -kon the keytab file, which should list the service principal with its key version number. Retrieving a keytab for a service generates or changes its key, so do this only when the service is ready to use it.Copy the keytab to the service host securely
Move the keytab to the machine that runs the service over an encrypted channel, and place it in the path the service expects, such as a directory owned by the service account. Remove any temporary copies on the administrator workstation once the transfer is verified. Check the file on the service host with
ls -lto confirm the owner and mode, and runklist -kagain there. The listed principal and key version should match what you saw before the copy, which confirms the file was not truncated or altered.Point the service configuration at the keytab
Set the service to use the keytab through its own configuration. For a web server using Kerberos, this is typically a keytab directive that names the file and a service principal that matches the one you created. Some services read the
KRB5_KTNAMEenvironment variable or a system keytab setting instead, so confirm the mechanism for the software you run. Reload or restart the service and check its logs for errors about missing keys, unknown principals or permission denied. A clean start with no keytab errors is the check for this step.Verify with a test service ticket
From an enrolled client that has a user ticket, run
kinitas a test user, thenkvnoagainst the service principal, for examplekvno HTTP/web01.example.internal. A returned key version confirms that the KDC issues a ticket for the service. Then runklistto see the service ticket in the credential cache. Finally, make a real request to the service and confirm the authenticated path works. Ifkvnofails with a message about an unknown server, check the principal name and DNS, because Kerberos depends on both.Record the principal and keytab for rotation
Write down the service principal, the host, the keytab path, the owner and the date of retrieval in your operations record, so the next person can find the credential and rotate it. Note which administrator approved the retrieval. Keytab rotation later follows the same path: retrieve a new keytab, install it, restart the service and verify with a test ticket. Ask your FreeIPA administrators how they track key versions and who may request a new keytab for this principal.
Who may create or retrieve a keytab in FreeIPA
Administrators hold the broadest rights in FreeIPA. A user with admin privileges can create service principals, retrieve their keytabs and change the permissions that govern both actions. Because this group can reach every service, membership should be small, named and reviewed on a schedule your security policy sets. Administrative accounts should be separate from everyday user accounts so that routine work never runs with keytab rights.
- Creation rights: Admins can add service principals for any host and any service type in the realm.
- Retrieval rights: Admins can fetch keytabs for services they did not create, which makes their sessions high value.
- Permission changes: Admins can grant other principals the right to manage keytabs, so this power should be limited to a few named people.
- Admin accounts: Use dedicated admin identities with strong authentication, and record who holds them.
- Break-glass access: Document how emergency admin access is granted, used and revoked.
Before go-live, list every principal with administrative rights and confirm each one still needs them, using the permission views in your FreeIPA version.
Host-level owners manage the machines that run services. In the FreeIPA model, a host can have rights tied to it, and services registered on that host inherit part of that context. A host owner may need to create a service principal for software on their own machine, such as a web server, but should not be able to reach keytabs for services on other hosts. Scoping rights to hosts keeps a compromise of one machine from exposing credentials across the realm.
- Host scope: Grant rights on the specific hosts a team operates, not on host groups that span unrelated systems.
- Enrollment first: The host must be enrolled as a client before services on it can receive keytabs.
- Local retrieval: Keytabs are typically fetched on the host that runs the service, so the file never needs to travel between machines.
- Shared hosts: Where several applications share one host, check whether their keytabs are separated by file and service name.
- Decommissioning: Remove service principals when a host is retired so that stale keys do not remain valid.
Confirm which hosts each owner can reach by running a test retrieval from an account that has only that owner's rights.
Delegated service owners are application teams who manage one service and need its keytab but no wider access. FreeIPA can grant a principal the right to manage a specific service, including retrieving its keytab, without making them an administrator. This is the right model when a team runs a web application that needs Kerberos authentication and should not touch other services.
- Narrow delegation: Grant management of only the named service principal, not of a service class or a host group.
- Creation separate from retrieval: Decide whether the team may create principals or only retrieve keytabs for principals an admin created.
- Impersonation risk: Anyone holding the keytab can authenticate as the service, so treat the file like a password.
- File handling: Keep keytabs readable only by the service account, and avoid copying them into tickets, chat or build logs.
- Review: Recheck delegations when team members change or the application is retired.
Ask the team to show which principal they retrieve and confirm that a retrieval by another user is refused.
The access model is only as sound as its review. The FreeIPA workshop walks through creating a service, retrieving its keytab with an admin ticket and showing the host and service permissions that allow or disallow creating and retrieving keytabs. Use the same steps as a test harness for your own realm before granting rights to real teams. Treat every permission as a grant that someone must justify and that someone must remove when no longer needed.
- Permission listing: Export the current host and service permissions and compare them with the approved owner list.
- Test retrievals: For each audience, attempt to create and retrieve a keytab for a service outside its scope and confirm the refusal is logged.
- Impersonation check: Confirm that the keytab holder cannot reach other services through their own tickets.
- Change records: Record every grant and removal with a reason and an approver.
- Periodic review: Set a review interval in your access policy and assign an owner for it.
Before sign-off, ask the platform team to demonstrate one denied retrieval and one permitted retrieval for each audience.
How principals, hosts, keytab files and service accounts map
This table traces one service from its Kerberos principal name through its FreeIPA host and service objects to the keytab file and the account that reads it. Read each row as a link in the chain, and check that every name matches what the client and the service expect. The main takeaway is that a mismatch at any link usually surfaces as an authentication failure, not as a clear error.
| Element | What it is in FreeIPA | Example (illustrative) | What to confirm |
|---|---|---|---|
| Kerberos principal | The unique name a service uses in Kerberos, in the form service/fully-qualified-host@REALM | HTTP/app01.example.internal@EXAMPLE.INTERNAL | The service part (HTTP here) and the realm match the client and the web server configuration exactly |
| Host object | The enrolled machine record that owns the service and holds the host keys | app01.example.internal | The host is enrolled and its DNS name resolves forward and reverse to the name in the principal |
| Service object | The FreeIPA record for the principal, created by the service add command and linked to the host | HTTP/app01.example.internal | The service object exists before the keytab is retrieved, and the principal name is spelled identically |
| Keytab file | A file on the host holding the long-term keys for the principal, retrieved with an administrator ticket or by a permitted host | /etc/httpd/conf/http.keytab (illustrative path) | The file path matches the service configuration and the file is readable only by the owning account |
| File owner and mode | The operating system user and group that can read the keytab, set on the host, not in FreeIPA | root or apache with restricted permissions (illustrative) | Only the service account can read the file, and copies are not left in shared or backup locations |
| Service account | The local process account that runs the service and reads the keytab at startup | apache (illustrative) | The process runs as this account and can open the keytab after any service restart or package update |
How to rotate service keys without breaking running services
Rotating a service key in FreeIPA means three things happen in order: new keys are issued for the service principal, a new keytab containing those keys is distributed to the host that runs the service, and the old keys are retired once every consumer has switched. The order matters because Kerberos clients and services hold keys by key version number (kvno). A service that still presents tickets encrypted with an old key will fail as soon as that key is removed from the principal, and the failure often shows up hours later, when cached tickets expire rather than at the moment of the change. Plan the rotation as a sequence with a rollback point, not as a single command.
The main risk is invalidating tickets that running services and their clients depend on. Before the change, list every host that holds a copy of the keytab, every process that reads it, and every client that requests tickets for that service principal. Check which encryption types the keytab contains and confirm that the Kerberos libraries on each host still accept them. Then rehearse the full sequence on a staging host enrolled in a copy of your realm, or on a dedicated test principal, and confirm that a client can still authenticate after the old keys are removed. Keep the old keytab on the production host until the new one has been verified, so you have something to restore.
Do not assume the exact rotation command, the behavior of key versions, or how many old keys FreeIPA keeps after a rotation. These details depend on your FreeIPA release and on the MIT Kerberos version on each host, so read the official documentation for the release you run and test the behavior there before you schedule a change. Ask your DeployOpen or internal team to record the observed kvno values before and after the staging run. Use the FreeIPA workshop on web application authentication and authorisation as a starting point for the service principal and keytab steps, then confirm each command against the documentation for your own version.
Security controls for keytab handling
A keytab is a bearer credential: anyone who holds it can act as the service principal. The controls below cover who can retrieve keytabs, where they live on disk and in version control, how retrieval is recorded, and what happens when a host leaves service. Apply the controls together, and apply the 4.13.4 security release before you expose service principal management to other administrators.
Apply the 4.13.4 security release first
FreeIPA 4.13.4 is a stabilization release dated July 9, 2026 that fixed two CVEs, including LDAP access control flaws that could let unauthenticated clients obtain credentials, and it hardened authentication checks across the API. Because those flaws concern credential exposure, apply this release before you delegate service principal or keytab management to other teams. Confirm the installed version on every server in the topology, not only the first one, and check the release notes for any upgrade steps that apply to your release line.
Restrict retrieval to named owners
Host and service permissions decide who may create a service and retrieve its keytab. Grant retrieval rights to the named owners of each service, such as the team that runs the web application, and avoid broad groups of administrators or a general-purpose host group. Review these permissions when a team changes, and confirm that the people who can retrieve a keytab are the same people responsible for the service it authenticates.
Set strict file permissions on keytabs
A keytab file should belong to the service account that reads it, typically with mode 0600 or a group-readable mode only where a second process needs access. Store keytabs under the service's own configuration directory, not in shared temporary paths. Check ownership after every package update or restart, because a misplaced file owner can either block the service or expose the key to other local users.
Keep keytabs out of version control
Keytabs contain long-term secrets, so they must never be committed to a Git repository, placed in a container image, or copied to a shared storage location. Deliver keytabs to hosts through a secret store or an automation step that retrieves them at deploy time, and exclude keytab file names from repository templates. Search existing repositories and backups for keytab files, since a credential committed once stays exposed in history.
Audit who retrieved which keytab
Before you rely on audit records, confirm what your FreeIPA version logs for keytab creation and retrieval, and where those records go. Retain administrative and LDAP access logs on the servers, forward them to a central system you control, and test that a sample retrieval produces an entry you can find. Pair this with a periodic comparison of retrieval rights against the list of service owners.
Remove keytabs when hosts retire
When a host is decommissioned, its service principals and keytab files must be retired too. Delete the local keytab files, remove the host and its services from FreeIPA, and check that no other host still holds a copy. Plan the rotation of any shared service keys that the retired host knew, because the copies it held remain valid until the key changes.
Common keytab failures and how to fix them
This table pairs each common keytab failure with its likely cause and the first check to run. Read it top to bottom when a service cannot authenticate, then follow the first check before changing any principal, keytab or host record. Most of these failures trace back to name resolution, time, or file ownership rather than to FreeIPA itself.
| Failure | Likely cause | First check |
|---|---|---|
| Server not found in Kerberos database | The service principal name requested by the client does not match a principal registered in FreeIPA, often because the host name in the URL is a CNAME or alias. | Run kvno against the exact service principal the client requests, then compare it with the principal listed in the keytab using klist -k. |
| Clock skew too great | The service host or client clock differs from the KDC by more than the Kerberos tolerance, so tickets are rejected as not yet valid or expired. | Compare the output of date on the service host with the time on the IPA server, and confirm the host syncs to the same NTP source. |
| Keytab not readable by the service account | The keytab file was written with root ownership or restrictive permissions, so the daemon running as its own user cannot open it. | Check owner, group and mode of the keytab file, then confirm the service user can read it with a test kinit -k against that path. |
| Principal name mismatch from DNS or short host names | Reverse DNS or a short host name resolves to a different fully qualified name than the one used when the principal was created, so the service requests a principal that does not exist. | Run hostname -f on the service host and confirm it matches the host record and service principal in FreeIPA, including case. |
| Key version mismatch after rotation | The keytab on the service host holds an older key version than the one now active in the KDC after the key was rotated, so decryption of tickets fails. | Compare the kvno in the keytab with the kvno reported by the KDC, then retrieve a fresh keytab and restart the service that holds the old copy. |
| Permission denied when retrieving a keytab | The administrator or host requesting the keytab lacks a host or service permission that allows retrieval, or the host is not enrolled as a managed host for that service. | Check the host and service permissions in FreeIPA for the requesting identity, and confirm the requester holds a valid admin ticket with ipa service-show. |
Questions buyers ask about service principals and keytabs
How much does it cost to set up service principals and keytabs in FreeIPA?
Cost depends mainly on how many services need principals, how many hosts they run on, and how much of your existing permission model must be designed or reviewed. Most of the spend is effort: mapping each service to a host and an owner, creating principals, setting who may create or retrieve keytabs, and testing that each service authenticates. Costs recur only when new services arrive or permissions change. Ask any partner for a written scope that lists each service, each host, the permission rules to build, and the test cases, because a quote follows from that list. Your own staff time to review ownership and approvals is a cost too, even when a partner does the build.
How long does it take to register services and hand out keytabs?
Duration depends on the same drivers as cost: the number of services, the number of hosts, the state of your existing host and service permission model, and the amount of testing required. A small set of services on a few hosts with clear ownership moves quickly. Many services across many hosts, with unclear owners or unreviewed permissions, takes longer because decisions must be made before anything is built. No duration can be stated here without a written scope. Ask for a timeline tied to named milestones, such as the permission model sign-off and the test run for each service.
What do we need to provide before work on keytabs can start?
You need a current inventory of the services that will use Kerberos, the hosts each one runs on, and a named owner for each service who can approve access. You also need your existing FreeIPA administration model, including which administrators, groups and host roles exist, and the test environment where services can be checked safely. Access to the FreeIPA deployment with suitable administrator rights is required so that principals, host and service permissions and keytab retrieval can be configured and verified. Confirm these inputs with your own team before scoping, since gaps in ownership are the most common reason work stalls.
Can our internal team set up service principals and keytabs without a partner?
Yes, if your team already runs FreeIPA and understands Kerberos, host enrollment and the permission model. The FreeIPA workshop on web application authentication and authorisation shows the core steps: creating a service, retrieving its keytab with an admin ticket, and setting host and service permissions to allow or disallow creating and retrieving keytabs. Teams without that experience usually need time to learn the failure modes, such as clock skew, DNS mismatches and keytab files left on the wrong host. A partner is most useful for designing the permission model across many services, writing repeatable procedures and running the verification tests.
What is the difference between a service principal and a keytab?
A service principal is the Kerberos identity for a service on a specific host, written in the form service/host.example.com in your realm. A keytab is a file that holds the secret keys for that principal, so the service can authenticate without a password prompt. Creating a principal does not hand over credentials; a keytab must be retrieved and installed on the host that runs the service. Treat keytab files as secrets, restrict their file permissions, and record which host holds each one so rotation and revocation are possible.
How do we control who can create or retrieve a keytab?
FreeIPA lets administrators allow or disallow the creation and retrieval of keytabs through host and service permissions. Decide first which groups may create principals, which hosts' administrators may retrieve keytabs for their own services, and who approves exceptions. Then configure those rules and test them with accounts that should be refused as well as accounts that should succeed. Keep the rules in a written permission model so auditors and your team can trace each grant to an owner. Confirm the exact permission options in your FreeIPA version before you build.
How do we rotate keys for service principals, and where do certificates fit?
Rotation means issuing new keys for a principal, distributing a new keytab to the host, restarting the service, and removing the old key once nothing depends on it. Plan this as a repeatable runbook with a test run before production. Service certificates are a separate concern handled by the certificate authority inside FreeIPA, which issues and renews certificates for services and publishes revocation data. Keytabs authenticate Kerberos sessions, while certificates support TLS and other trust relationships, so rotation plans should cover both. Confirm renewal and revocation behavior with your FreeIPA certificate design before setting schedules.
What testing is needed before services go live with keytabs?
Test each service with an account that should be allowed and an account that should be refused, confirm the keytab works on the intended host only, and check that rotation and removal behave as the runbook says. Include clock synchronization and DNS checks, since Kerberos fails when either drifts. The amount of testing grows with the number of services and the number of distinct permission rules, so ask for the test list as part of the written scope. Illustrative example: a service with three host types and two approval groups needs tests for each combination, not just one happy path.
How DeployOpen scopes and delivers keytab and service principal work
DeployOpen plans, implements, hardens, documents and supports FreeIPA inside your own infrastructure, including the service principals, keytabs and service certificates your applications depend on. Engagements are fixed-scope, with the scope, deliverables and timeline agreed in writing before work starts.
How we scope
- We list each service that needs a principal, its host, its owner and the applications that will read its keytab.
- We record which admin groups and host groups may create principals and retrieve keytabs, and why.
- We agree in writing which keytab storage, file permissions and rotation method apply before any build begins.
How we build
- We create service principals and host bindings in a test realm first, then verify retrieval with an admin ticket.
- We configure host and service permissions so only approved hosts and administrators can create or retrieve each keytab.
- We test keytab use from each consuming service and confirm Kerberos authentication succeeds before rollout.
How we hand over
- We deliver a register of principals, keytab locations, owners, permissions and certificate ties for your records.
- We document the retrieval, rotation and revocation steps so your team can repeat them without us.
- We walk your administrators through the permission model and the checks used to confirm each service still authenticates.
How we support
- Ongoing support covers keytab rotation, new service onboarding and permission reviews, available as a retainer.
- We can re-test service authentication after FreeIPA upgrades or host changes that might affect keytabs.
- Retainer scope, response expectations and review cadence are agreed in writing before the retainer starts.
