PKINIT Configuration

Overview

PKINIT (Public Key Cryptography for Initial Authentication in Kerberos) enables certificate-based Kerberos authentication, allowing users and services to obtain Kerberos tickets using X.509 certificates instead of passwords. This provides stronger authentication security, supports passwordless workflows, and integrates Kerberos with PKI-based identity systems.

The ipa pkinit-status command reports which IPA masters have PKINIT enabled or disabled, helping administrators verify PKINIT deployment status across the infrastructure and identify servers requiring PKINIT configuration changes.

PKINIT Authentication Flow

Traditional Kerberos: User provides password → KDC verifies password → KDC issues TGT (Ticket Granting Ticket).

PKINIT: User provides certificate (from smart card, hardware token, or file) → KDC verifies certificate via PKI → KDC issues TGT.

This certificate-based approach eliminates password transmission, resists password-based attacks (phishing, brute force, credential stuffing), and enables passwordless authentication for users with smart cards or FIDO2 tokens.

PKINIT Capabilities

User Authentication: Users authenticate with certificates instead of passwords, using kinit -X X509_user_identity=... with certificate paths or smart card references.

Anonymous PKINIT: Obtain anonymous Kerberos tickets without authentication, useful for specific protocols and directory browsing scenarios where anonymous access is permitted.

Service Authentication: Services authenticate using their host or service certificates for automated operations without password/keytab management.

Smart Card Integration: PKINIT is the underlying mechanism for smart card authentication in FreeIPA, validating card certificates and issuing Kerberos tickets.

PKINIT Status Importance

Administrators need to verify PKINIT status across IPA masters for several reasons:

Feature Availability: Users can only authenticate via PKINIT against masters with PKINIT enabled. Disabled PKINIT on specific masters limits where users can authenticate.

Load Balancing: In load-balanced deployments, all backend IPA masters should have consistent PKINIT status to ensure uniform user experience regardless of which master handles the request.

Compliance: Security policies may mandate PKINIT support for certificate-based authentication. Status verification ensures compliance across all infrastructure.

Troubleshooting: When users report smart card authentication failures, checking PKINIT status on contacted servers helps diagnose whether the issue is PKINIT configuration or client-side problems.

Upgrade Planning: During upgrades or configuration changes, verifying PKINIT status ensures the feature remains available and isn’t inadvertently disabled.

EXAMPLES:

List PKINIT status on all masters:

ipa pkinit-status

Check PKINIT status on `ipa.example.com`:

ipa pkinit-status --server ipa.example.com

List all IPA masters with disabled PKINIT:

ipa pkinit-status --status='disabled'

For more info about PKINIT support see:

https://www.freeipa.org/page/V4/Kerberos_PKINIT

Use Cases

Verifying PKINIT Deployment Status

After enabling PKINIT for smart card authentication, administrators need to verify that all IPA masters have PKINIT enabled and operational.

# Check PKINIT status on all IPA masters
ipa pkinit-status
  Server name: ipa01.example.com
  PKINIT status: enabled

  Server name: ipa02.example.com
  PKINIT status: enabled

  Server name: ipa03.example.com
  PKINIT status: disabled

# Master ipa03 has PKINIT disabled - users contacting that server
# cannot use smart card authentication

# Enable PKINIT on ipa03
ssh ipa03.example.com
ipa-pkinit-manage enable

# Verify enabled
ipa pkinit-status --server ipa03.example.com
  Server name: ipa03.example.com
  PKINIT status: enabled

Troubleshooting Smart Card Authentication Failures

When users report smart card authentication failures, checking PKINIT status helps determine if the contacted server supports certificate-based authentication.

# User reports: "kinit with smart card fails"

# Check which server user is contacting
# On user's system:
grep xmlrpc_uri /etc/ipa/default.conf
  xmlrpc_uri = https://ipa02.example.com/ipa/xml

# Corresponding KDC is ipa02.example.com
# Check PKINIT status on that server
ipa pkinit-status --server ipa02.example.com
  Server name: ipa02.example.com
  PKINIT status: disabled

# PKINIT disabled on ipa02 - smart card authentication won't work
# Either enable PKINIT on ipa02 or point user to different server
ipa pkinit-status --status=enabled
  Server name: ipa01.example.com
  PKINIT status: enabled

# Direct user to use ipa01 instead
# On user's system, update /etc/ipa/default.conf or use:
kinit -X X509_user_identity=FILE:/path/to/cert.pem,/path/to/key.pem \
  -S krbtgt/EXAMPLE.COM@EXAMPLE.COM \
  -k ipa01.example.com

Audit PKINIT Configuration for Compliance

Security compliance requires certificate-based authentication support on all IPA infrastructure. Audit PKINIT status to verify compliance.

# List all masters with PKINIT disabled (compliance failures)
ipa pkinit-status --status=disabled
  Server name: ipa-test.example.com
  PKINIT status: disabled

  Server name: ipa-dev.example.com
  PKINIT status: disabled

# Test and dev environments don't have PKINIT enabled
# For production compliance, verify all prod servers have PKINIT
ipa pkinit-status | grep -E "(ipa-prod|PKINIT)"
  Server name: ipa-prod01.example.com
  PKINIT status: enabled

  Server name: ipa-prod02.example.com
  PKINIT status: enabled

# All production servers compliant

Planning Smart Card Rollout

Before deploying smart cards to users, verify infrastructure readiness by confirming PKINIT is enabled on all user-facing IPA masters.

# Check PKINIT status on all masters
ipa pkinit-status --all
  Server name: ipa01.example.com
  PKINIT status: enabled

  Server name: ipa02.example.com
  PKINIT status: enabled

  Server name: ipa03.example.com
  PKINIT status: disabled

# ipa03 not ready for smart card rollout
# Enable PKINIT on ipa03 before distributing smart cards to users
ssh ipa03.example.com
ipa-pkinit-manage enable

# Verify readiness
ipa pkinit-status --status=enabled | wc -l
  3 servers with PKINIT enabled
# All servers ready for smart card deployment

Monitoring PKINIT Availability

Monitoring systems need to verify PKINIT remains enabled on critical IPA masters to alert when configuration drift occurs.

#!/bin/bash
# Monitor PKINIT status on production masters

PROD_SERVERS="ipa-prod01.example.com ipa-prod02.example.com ipa-prod03.example.com"

for server in $PROD_SERVERS; do
  STATUS=$(ipa pkinit-status --server "$server" 2>/dev/null | \
    grep "PKINIT status:" | awk '{print $3}')

  if [ "$STATUS" != "enabled" ]; then
    echo "CRITICAL: PKINIT disabled on $server"
    # Send alert to monitoring system
    exit 2
  fi
done

echo "OK: PKINIT enabled on all production masters"
exit 0

Validating Load Balancer Backend Configuration

When using load balancers for IPA, all backend masters should have consistent PKINIT configuration to ensure uniform smart card authentication regardless of which backend handles the request.

# Identify backend servers for load balancer
LB_BACKENDS="ipa-lb01.example.com ipa-lb02.example.com ipa-lb03.example.com"

# Check PKINIT status on all backends
for server in $LB_BACKENDS; do
  ipa pkinit-status --server "$server"
done

  Server name: ipa-lb01.example.com
  PKINIT status: enabled

  Server name: ipa-lb02.example.com
  PKINIT status: enabled

  Server name: ipa-lb03.example.com
  PKINIT status: disabled

# Inconsistent configuration - ipa-lb03 doesn't support smart cards
# Users randomly failing smart card auth when load balanced to ipa-lb03
# Enable PKINIT on ipa-lb03 for consistent behavior

Investigating Certificate Authentication Errors

When certificate-based authentication fails with cryptic errors, verifying PKINIT status is a critical early troubleshooting step.

# User error: "Preauthentication failed while getting initial credentials"

# First troubleshooting step: verify PKINIT enabled
ipa pkinit-status
  # Check if any servers have PKINIT disabled

# If all enabled, issue is likely:
# - Certificate validation (expired, untrusted CA)
# - Certificate principal mapping
# - Smart card reader/middleware issues

# If PKINIT disabled on contacted server:
# - Enable PKINIT or direct user to different server

Documenting IPA Infrastructure Capabilities

Infrastructure documentation should include PKINIT status for each IPA master to guide users and support teams.

# Generate PKINIT status report for documentation
echo "# IPA Infrastructure PKINIT Status Report"
echo "Generated: $(date)"
echo ""

ipa pkinit-status | while read -r line; do
  if [[ $line =~ "Server name:" ]]; then
    SERVER=$(echo "$line" | awk '{print $3}')
    echo -n "- $SERVER: "
  elif [[ $line =~ "PKINIT status:" ]]; then
    STATUS=$(echo "$line" | awk '{print $3}')
    echo "$STATUS"
  fi
done > pkinit-status-report.md

# Report includes:
# - ipa01.example.com: enabled
# - ipa02.example.com: enabled
# - ipa03.example.com: disabled

Preparing for Anonymous PKINIT Deployment

Before enabling anonymous PKINIT for specific use cases, verify baseline PKINIT functionality is operational on all masters.

# Verify PKINIT operational on all masters
ipa pkinit-status | grep -c "PKINIT status: enabled"
  3

ipa pkinit-status | wc -l | awk '{print $1/2}'
  3

# All 3 masters have PKINIT enabled
# Proceed with anonymous PKINIT configuration on each master
for server in $(ipa pkinit-status | grep "Server name" | awk '{print $3}'); do
  ssh "$server" "ipa-pkinit-manage enable-anonymous"
done

# Anonymous PKINIT now available on all masters

Identifying Servers for PKINIT Disablement

In environments where PKINIT is being deprecated or removed, identify which servers currently have PKINIT enabled.

# List all servers with PKINIT enabled
ipa pkinit-status --status=enabled
  Server name: ipa01.example.com
  PKINIT status: enabled

  Server name: ipa02.example.com
  PKINIT status: enabled

# Disable PKINIT on each identified server
ssh ipa01.example.com "ipa-pkinit-manage disable"
ssh ipa02.example.com "ipa-pkinit-manage disable"

# Verify disablement
ipa pkinit-status --status=enabled
  # No results - PKINIT disabled on all servers

Security Considerations

PKINIT enables passwordless authentication: When PKINIT is enabled, users with valid certificates can obtain Kerberos tickets without passwords. If certificate private keys are compromised or stolen, attackers gain password-equivalent access. Smart card PIN protection and hardware key storage are critical.

Anonymous PKINIT information disclosure: Anonymous PKINIT allows unauthenticated principals to obtain Kerberos tickets with limited privileges. This can be abused to enumerate realm information, discover services, or probe for vulnerabilities without authentication. Disable anonymous PKINIT unless specifically required.

Certificate validation criticality: PKINIT trusts certificates issued by the IPA CA by default. If the IPA CA is compromised or issues certificates to unauthorized entities, those entities can authenticate via PKINIT. CA security and certificate issuance controls are critical when PKINIT is enabled.

Inconsistent PKINIT status creates security gaps: If some IPA masters have PKINIT enabled and others don’t, users may change behavior based on which server they contact. This inconsistency can lead to security policy violations (users forced to use passwords when smart card expected) or authentication bypasses.

PKINIT exposes KDC to certificate-based attacks: Enabling PKINIT increases the KDC attack surface by accepting certificate-based authentication in addition to password-based. Certificate parsing vulnerabilities, cryptographic implementation flaws, or certificate validation bypass bugs become potential KDC compromise vectors.

Smart card loss becomes high-impact incident: With PKINIT, lost or stolen smart cards grant access equivalent to passwords. Unlike passwords (which can be changed immediately), certificates must be revoked, and revocation must propagate to all KDCs. Delayed revocation creates authentication bypass windows.

Certificate expiration causes authentication outages: When user certificates expire, PKINIT authentication fails. Unlike password expiration (which prompts for password change), certificate expiration requires certificate renewal and reissuance. Users with expired certificates cannot authenticate until certificates are renewed.

PKINIT status information enables reconnaissance: The pkinit-status command reveals which servers support certificate-based authentication, helping attackers identify potential targets for certificate-based attacks or understand infrastructure capabilities for attack planning.

No multi-factor authentication with PKINIT: While smart cards with PIN provide two factors (something you have + something you know), PKINIT using file-based certificates provides only single-factor authentication (something you have). File-based PKINIT certificates without additional protections are equivalent to password files.

Certificate principal mapping vulnerabilities: PKINIT maps certificates to Kerberos principals based on certificate subject or SAN (Subject Alternative Name). Incorrect mapping configurations can enable certificate-based authentication as unintended principals, granting unauthorized access.

Revocation list propagation delays: Certificate revocation lists (CRLs) or OCSP responses control whether revoked certificates are still trusted. CRL/OCSP propagation delays or failures allow revoked certificates to remain valid for PKINIT authentication, enabling continued access for users who should be blocked.

Troubleshooting

pkinit-status Shows No Results

Symptom: ipa pkinit-status returns no output or shows “0 PKINIT enabled servers found”.

Diagnosis: No IPA masters have PKINIT enabled, or there’s a query/connectivity issue.

Resolution: Verify IPA masters exist and enable PKINIT if needed:

# List all IPA servers
ipa server-find

# If servers exist but no PKINIT status shown, enable PKINIT
ssh ipa01.example.com
ipa-pkinit-manage enable

# Verify PKINIT enabled
ipa pkinit-status
  Server name: ipa01.example.com
  PKINIT status: enabled

Cannot Check PKINIT Status on Specific Server

Symptom: ipa pkinit-status --server ipa02.example.com fails or returns no results.

Diagnosis: Server name incorrect, server not in IPA topology, or server unreachable.

Resolution: Verify server exists and is reachable:

# List all IPA servers to get exact hostnames
ipa server-find --pkey-only
  Server name: ipa01.example.com
  Server name: ipa02.example.com

# Use exact server name from list
ipa pkinit-status --server ipa02.example.com

# If still fails, check connectivity
ping ipa02.example.com
ssh ipa02.example.com
  # Verify server is accessible

PKINIT Status Shows “disabled” After ipa-pkinit-manage enable

Symptom: Ran ipa-pkinit-manage enable but pkinit-status still shows disabled.

Diagnosis: PKINIT enable operation failed, or status not yet replicated.

Resolution: Verify PKINIT configuration and check for errors:

# Check PKINIT configuration files exist
ssh ipa01.example.com
ls -l /var/kerberos/krb5kdc/kdc.conf | grep pkinit
  # Should show PKINIT configuration sections

# Check KDC configuration
grep -i pkinit /var/kerberos/krb5kdc/kdc.conf
  pkinit_identity = FILE:/var/kerberos/krb5kdc/kdc.pem
  pkinit_anchors = FILE:/etc/ipa/ca.crt
  # PKINIT configuration present

# Restart KDC to apply configuration
systemctl restart krb5kdc

# Wait for replication and retry status check
sleep 30
ipa pkinit-status --server ipa01.example.com

PKINIT Status Inconsistent Across Replicas

Symptom: Different IPA masters show different PKINIT status when they should be consistent.

Diagnosis: Configuration drift, manual changes, or replication issues.

Resolution: Identify inconsistency and standardize configuration:

# Check status on all servers
ipa pkinit-status
  Server name: ipa01.example.com
  PKINIT status: enabled

  Server name: ipa02.example.com
  PKINIT status: disabled

# Decide on target state (all enabled or all disabled)
# Enable PKINIT on ipa02 to match ipa01
ssh ipa02.example.com
ipa-pkinit-manage enable

# Verify consistency
ipa pkinit-status
  # All servers should show same status

Cannot Disable PKINIT on Server

Symptom: ipa-pkinit-manage disable fails or PKINIT remains enabled after disable command.

Diagnosis: Permission issue, KDC configuration locked, or disablement prevented by policy.

Resolution: Check permissions and force disable if necessary:

# Verify running as root or with sudo
sudo ipa-pkinit-manage disable

# Check KDC configuration file permissions
ls -l /var/kerberos/krb5kdc/kdc.conf
  -rw-r--r-- 1 root root

# Manually remove PKINIT configuration if needed
vi /var/kerberos/krb5kdc/kdc.conf
  # Comment out or remove pkinit_* lines

# Restart KDC
systemctl restart krb5kdc

# Verify disabled
ipa pkinit-status --server $(hostname)

pkinit-status Returns “Not Found” Error

Symptom: ipa pkinit-status fails with “command not found” or “not found” error.

Diagnosis: IPA version too old (predates pkinit-status command) or command unavailable.

Resolution: Update IPA or check PKINIT status manually:

# Check IPA version
ipa --version
  VERSION: 4.6.8
  # Old version may not have pkinit-status

# Check PKINIT status manually
ssh ipa01.example.com
grep -i pkinit /var/kerberos/krb5kdc/kdc.conf
  # If pkinit_* lines present: enabled
  # If no pkinit_* lines: disabled

# Update IPA for pkinit-status command
dnf update ipa-server ipa-client

PKINIT Status Different Between —status Filter and Full Output

Symptom: ipa pkinit-status --status=enabled shows different results than parsing full ipa pkinit-status output.

Diagnosis: Caching issue or filter logic bug.

Resolution: Use fresh queries and verify filter:

# Clear any cached results
rm -rf ~/.cache/ipa/

# Get fresh full status
ipa pkinit-status | tee /tmp/full-status.txt

# Get fresh filtered status
ipa pkinit-status --status=enabled | tee /tmp/enabled-status.txt

# Compare
diff /tmp/full-status.txt /tmp/enabled-status.txt
  # Should show only filtering difference

PKINIT Enable Fails with Certificate Error

Symptom: ipa-pkinit-manage enable fails with error about missing or invalid certificates.

Diagnosis: KDC certificate missing, expired, or not trusted by IPA CA.

Resolution: Verify and regenerate KDC certificate:

# Check KDC certificate
openssl x509 -in /var/kerberos/krb5kdc/kdc.pem -text -noout
  # Check issuer (should be IPA CA)
  # Check expiration date

# If certificate missing or invalid, regenerate
ipa-getcert list -d /var/kerberos/krb5kdc -n KDC-Cert
  # Check certificate tracking status

# Request new certificate if needed
ipa-getcert request -d /var/kerberos/krb5kdc -n KDC-Cert \
  -K host/$(hostname)@REALM

# Retry PKINIT enable
ipa-pkinit-manage enable

User Smart Card Authentication Fails Despite PKINIT Enabled

Symptom: ipa pkinit-status shows enabled, but users cannot authenticate with smart cards.

Diagnosis: PKINIT enabled but other components (certificate validation, smart card middleware) have issues.

Resolution: Verify end-to-end smart card authentication chain:

# Verify PKINIT enabled
ipa pkinit-status --server ipa01.example.com
  PKINIT status: enabled

# Test user certificate validity
openssl x509 -in /path/to/user-cert.pem -text -noout
  # Check issuer (should be IPA CA)
  # Check expiration

# Test smart card reader
pcsc_scan
  # Should detect smart card reader and card

# Test kinit with certificate
kinit -X X509_user_identity=FILE:/path/to/cert.pem,/path/to/key.pem alice
  # Should succeed if PKINIT and certificate valid

# If fails, check KDC logs
ssh ipa01.example.com
tail -f /var/log/krb5kdc.log
  # Look for PKINIT-related errors

PKINIT Status Shows Unexpected Server

Symptom: ipa pkinit-status shows server that shouldn’t exist or has been decommissioned.

Diagnosis: Stale server record in IPA topology, server not properly removed.

Resolution: Remove stale server from topology:

# Verify server is actually decommissioned
ping old-ipa-server.example.com
  # Should not respond

# Remove from topology
ipa server-del old-ipa-server.example.com

# Verify removal
ipa pkinit-status
  # Should not show old server anymore

Cannot Filter by —status=‘enabled’

Symptom: ipa pkinit-status --status='enabled' fails with syntax error or returns wrong results.

Diagnosis: Quote syntax or filter value incorrect.

Resolution: Use correct syntax:

# Wrong syntax
ipa pkinit-status --status='enabled'
  # May fail depending on shell

# Correct syntax (no quotes needed)
ipa pkinit-status --status=enabled

# Or with quotes (both quote styles work)
ipa pkinit-status --status="enabled"
ipa pkinit-status --status='enabled'

# Verify correct values: enabled or disabled
ipa pkinit-status --status=disabled

PKINIT Status Query Times Out

Symptom: ipa pkinit-status command hangs and eventually times out.

Diagnosis: Network connectivity issue, server unreachable, or IPA service degraded.

Resolution: Test connectivity and service health:

# Test IPA connectivity
ipa ping
  # Should respond quickly

# If ping works but pkinit-status hangs, check specific servers
for server in $(ipa server-find --pkey-only | grep "Server name" | awk '{print $3}'); do
  echo "Testing $server..."
  timeout 5 ipa pkinit-status --server "$server"
done
  # Identify which server is causing timeout

# SSH to problematic server and check services
ssh problem-server.example.com
ipactl status
  # Check all services running

systemctl status krb5kdc
  # KDC should be active

Anonymous PKINIT Status Not Shown

Symptom: PKINIT status command doesn’t indicate whether anonymous PKINIT is enabled.

Diagnosis: pkinit-status only shows whether PKINIT is enabled, not anonymous PKINIT specifically.

Resolution: Check anonymous PKINIT configuration manually:

# Check KDC configuration for anonymous PKINIT
ssh ipa01.example.com
grep -i anon /var/kerberos/krb5kdc/kdc.conf
  pkinit_allow_upn = true
  # Look for anonymous-specific configuration

# Test anonymous PKINIT
kinit -n
  # Should succeed if anonymous PKINIT enabled

# Check for WELLKNOWN/ANONYMOUS principal
klist
  Principal: WELLKNOWN/ANONYMOUS@WELLKNOWN:ANONYMOUS
  # Anonymous ticket obtained

Commands

pkinit-status

Usage: ipa [global-options] pkinit-status [CRITERIA] [options]

Report PKINIT status on the IPA masters

Arguments

Argument Required Description

---

CRITERIA no A string searched in all relevant object attributes

Options

Option	Description
--server SERVER	IPA server hostname
--status STATUS	Whether PKINIT is enabled or disabled
--timelimit TIMELIMIT	Time limit of search in seconds (0 is unlimited)
--sizelimit SIZELIMIT	Maximum number of entries returned (0 is unlimited)
--all	Retrieve and print all attributes from the server. Affects command output.
--raw	Print entries as stored on the server. Only affects output format.