Certificate Management

Overview

FreeIPA provides integrated X.509 certificate management through its embedded Dogtag Certificate System certificate authority. This integration enables automated certificate issuance, renewal, and revocation for services, hosts, and users without requiring external PKI infrastructure or manual certificate handling. Certificates issued by IPA’s CA are automatically trusted by all IPA clients, simplifying TLS/SSL deployment and enabling strong authentication mechanisms.

Certificate management in IPA centers on service principals - certificates are associated with Kerberos principals representing services (HTTP/, LDAP/, etc.) or hosts (host/). This binding ensures certificates are issued only to authorized entities and enables automatic renewal through certmonger on IPA clients. The CA tracks certificate lifecycle including issuance dates, expiration dates, revocation status, and ownership relationships.

IPA’s certificate infrastructure supports both internal services (IPA web UI, LDAP servers, Kerberos KDC) and user-managed services requiring TLS certificates. Certificate profiles control what types of certificates can be issued, certificate access control lists (CA ACLs) determine who can request certificates, and sub-CAs enable isolation of certificate issuance for different purposes or security domains.

Certificate Request Prerequisites

Certificate requests require specific IPA objects to exist before submission. This prerequisite structure ensures certificates are associated with properly registered services and prevents unauthorized certificate issuance.

Host Entry: The host where the service runs must exist in IPA. For a certificate requested for HTTP/web.example.com, the host web.example.com must be enrolled or pre-created. Host entries establish ownership and enable delegation of certificate management.

Service Principal: The service principal must exist in IPA unless the --add option automatically creates it during the request. Service principals define which services are authorized to run on specific hosts and track certificate associations.

CA ACL Authorization: The requesting principal (user, host, or service) must be authorized by a CA ACL to request certificates from the specified CA using the specified profile. Default CA ACLs permit hosts to request certificates for their own service principals.

These prerequisites create an authorization chain: the requester must be authorized (CA ACL), the service must be registered (service principal), and the host must be legitimate (host entry). This multi-layer validation prevents unauthorized certificate issuance.

Certificate Signing Requests (CSRs)

Certificate requests are submitted as PEM-formatted Certificate Signing Requests generated by the requester’s key management system. The CSR contains the public key to be certified and subject information identifying the certificate holder. IPA’s CA validates the CSR and, if authorized, issues a signed certificate.

The Dogtag CA enforces IPA-configured subject formatting. While the CSR includes subject fields like CN (common name), O (organization), and OU (organizational unit), the CA overwrites most fields with values configured in the certificate profile. This ensures consistent subject formatting and prevents requesters from arbitrarily setting subject fields that might conflict with IPA policy.

The CN (common name) value from the CSR is preserved and typically matches the service principal. For example, a certificate for HTTP/web.example.com would have CN=web.example.com. Other subject fields are derived from the IPA domain configuration and certificate profile settings.

CSR generation typically occurs on the system requiring the certificate using tools like openssl req, ipa-getcert request (via certmonger), or application-specific certificate request mechanisms. The private key corresponding to the CSR’s public key never leaves the requesting system, maintaining key confidentiality.

Certificate Profiles

Certificate profiles define templates for certificate issuance, specifying certificate characteristics including key usage extensions, validity period, subject DN formatting, and certificate type. Different profiles support different use cases: services requiring server authentication, users needing client authentication, or specialized applications with specific certificate requirements.

IPA ships with default profiles for common scenarios:

caIPAserviceCert: Standard service certificates for TLS/SSL servers
IECUserRoles: User certificates with role information
caIPAserviceCert: Certificates for IPA infrastructure services

Custom profiles can be created for organizational-specific requirements, enabling certificate customization while maintaining CA policy control. Profile selection during certificate request (--profile-id) determines which template governs certificate issuance.

Certificate profiles integrate with CA ACLs to create authorization policies. A CA ACL specifies which principals can use which profiles from which CAs, enabling fine-grained control over certificate issuance capabilities.

Certificate Revocation

Certificate revocation invalidates certificates before their natural expiration, necessary when private keys are compromised, service principals are decommissioned, or certificates were issued in error. IPA supports standard RFC 5280 revocation reasons providing context for why certificates were revoked.

Revocation is immediate and permanent (except for reason code 6, certificateHold). Once revoked, the certificate’s serial number is added to the CA’s Certificate Revocation List (CRL) and marked revoked in OCSP (Online Certificate Status Protocol) responses. Clients checking revocation status will reject revoked certificates.

Common Revocation Reasons:

keyCompromise (1): Private key was exposed or stolen
superseded (4): Certificate replaced by a newer certificate
cessationOfOperation (5): Service no longer operational
certificateHold (6): Temporary revocation, reversible with cert-remove-hold
privilegeWithdrawn (9): Authorization to hold certificate removed

Reason code 6 (certificateHold) uniquely allows reversal. Certificates placed on hold can be removed from hold status if the security concern is resolved. All other revocation reasons are permanent.

Certificate Hold and Release

The certificate hold mechanism enables temporary suspension of certificate validity without permanent revocation. This is useful when investigating potential key compromise, temporarily suspending services, or responding to security incidents where permanent revocation may be premature.

Certificates on hold appear as revoked in CRL and OCSP responses. Clients validating these certificates will reject them as revoked. However, unlike permanent revocation, hold status can be reversed using cert-remove-hold, returning the certificate to valid status.

Use certificate hold judiciously - repeatedly placing certificates on and off hold can cause operational confusion and may not be supported consistently across all client implementations. For long-term service suspension, consider permanent revocation and reissuing a new certificate when service resumes.

Certificate Storage and Association

Certificates are stored in the Dogtag Certificate System database and associated with IPA principals (services, hosts, users) through LDAP entries. The IPA LDAP directory stores certificate metadata including serial number, subject, issuer, validity period, and principal association.

Service and host entries can store multiple certificates simultaneously, supporting certificate renewal transitions and certificate type diversity. For example, a web service might have both RSA and ECDSA certificates to support different client capabilities.

User entries can store certificates for smart card authentication, enabling passwordless login using certificates on smart cards or hardware tokens. These certificates are discovered by IPA clients during authentication, matching presented certificates against stored certificates.

Automatic Renewal with Certmonger

IPA clients use certmonger to automatically renew certificates before expiration. Certmonger tracks certificates, monitors expiration dates, and automatically requests renewals from the IPA CA when certificates approach expiration (typically 28 days before expiry).

Automatic renewal prevents certificate expiration outages and eliminates manual renewal processes. Services using certificates managed by certmonger receive renewed certificates transparently, with certmonger handling CSR generation, submission, retrieval, and local certificate file updates.

Certmonger integrates with service management to automatically reload services after certificate renewal. For example, after renewing an HTTP certificate, certmonger can trigger httpd reload to activate the new certificate without service interruption.

External Certificates

While IPA primarily manages certificates issued by its own CA, it can also track externally-issued certificates. External certificates (from public CAs, organizational PKI, or other sources) can be imported into service, host, or user entries for tracking and management purposes.

External certificate tracking enables IPA to serve as a centralized certificate inventory even when issuance occurs elsewhere. Administrators can search for certificates, view expiration dates, and track certificate-to-principal associations regardless of the issuing CA.

External certificates don’t receive automatic renewal through IPA’s certmonger integration (unless separately configured) and IPA cannot revoke them (revocation must occur at the issuing CA). However, tracking external certificates provides visibility and management consistency.

Certificate Search Capabilities

Certificates can be searched using multiple criteria enabling administrators to locate specific certificates, audit certificate issuance, track expirations, and investigate security incidents. Search parameters include certificate attributes, ownership, dates, and revocation status.

Subject Searching: Locate certificates by common name or subject DN components. The --subject parameter searches the CN field, while --exactly requires exact CN matching rather than substring matching.

Serial Number Ranges: Search for certificates by serial number ranges using --min-serial-number and --max-serial-number. Serial numbers can be specified in decimal or hexadecimal (prefix with 0x).

Date-Based Searches: Filter certificates by validity dates (notBefore, notAfter), issuance dates, or revocation dates. Date ranges use --*-from (>=) and --*-to (<=) parameters in YYYY-mm-dd format. All dates are interpreted as GMT matching certificate encoding.

Ownership Searches: Find certificates associated with specific users (--users), hosts (--hosts), or services (--services). This enables auditing what certificates are held by specific principals.

Revocation Status: Search for revoked certificates by revocation reason or revocation date range. This supports incident investigation and compliance auditing.

Certificate File Examination: The --file parameter accepts a certificate file (PEM format) and searches for it in the IPA database, returning metadata and ownership information.

Examples

Certificate Requests

Request a certificate for an existing service principal:

ipa cert-request --principal=HTTP/web.example.com web.csr

Request a certificate and automatically create the service principal:

ipa cert-request --add --principal=HTTP/web.example.com web.csr

Request a certificate using a specific profile:

ipa cert-request --principal=HTTP/web.example.com --profile-id=caIPAserviceCert web.csr

Request a certificate and retrieve the full chain:

ipa cert-request --principal=HTTP/web.example.com --chain web.csr

Request from a specific sub-CA:

ipa cert-request --principal=HTTP/web.example.com --ca=subca web.csr

Certificate Retrieval

Retrieve a certificate by serial number:

ipa cert-show 1032

Retrieve certificate and save to file:

ipa cert-show 1032 --out=cert.pem

Retrieve certificate with full chain:

ipa cert-show 1032 --chain

Retrieve certificate from specific CA:

ipa cert-show 1032 --ca=subca

Display all certificate attributes:

ipa cert-show 1032 --all

Certificate Revocation

Revoke a certificate (unspecified reason):

ipa cert-revoke 1032 --revocation-reason=0

Revoke due to key compromise:

ipa cert-revoke 1032 --revocation-reason=1

Revoke due to service cessation:

ipa cert-revoke 1032 --revocation-reason=5

Place certificate on hold (temporary revocation):

ipa cert-revoke 1032 --revocation-reason=6

Remove certificate from hold status (reactivate):

ipa cert-remove-hold 1032

Certificate Search

Search by subject common name:

ipa cert-find --subject=web.example.com

Search with exact CN matching:

ipa cert-find --subject=web.example.com --exactly

Search for certificates owned by a specific user:

ipa cert-find --user=jsmith

Search for certificates for a specific host:

ipa cert-find --host=web.example.com

Search for certificates for a specific service:

ipa cert-find --service=HTTP/web.example.com

Search for certificates issued in a specific date range:

ipa cert-find --issuedon-from=2024-01-01 --issuedon-to=2024-12-31

Search for certificates expiring soon:

ipa cert-find --validnotafter-from=2024-01-01 --validnotafter-to=2024-03-31

Search for revoked certificates:

ipa cert-find --status=revoked

Search by revocation reason:

ipa cert-find --revocation-reason=1

Search for certificates revoked in a date range:

ipa cert-find --revokedon-from=2024-01-01 --revokedon-to=2024-01-31

Search by serial number range:

ipa cert-find --min-serial-number=1000 --max-serial-number=2000

Examine a certificate file to see if it’s in IPA:

ipa cert-find --file=cert.pem --all

Verify certificate ownership:

ipa cert-find --file=cert.pem --user=jsmith

Search certificates from specific CA:

ipa cert-find --ca=subca

Request Status Checking

Check status of a certificate request (rarely used - IPA issues immediately):

ipa cert-status 10

Revocation Reason Codes

The following RFC 5280 revocation reasons are supported:

0 - unspecified: No specific reason provided
1 - keyCompromise: Private key was compromised or stolen
2 - cACompromise: CA’s private key was compromised
3 - affiliationChanged: Certificate holder changed affiliation
4 - superseded: Certificate replaced by a newer certificate
5 - cessationOfOperation: Service or entity ceased operations
6 - certificateHold: Temporary hold (reversible with cert-remove-hold)
8 - removeFromCRL: Remove from CRL (administrative use)
9 - privilegeWithdrawn: Privileges granted by certificate withdrawn
10 - aACompromise: Attribute authority compromised

Note: Reason code 7 is unused in RFC 5280. Reason code 6 (certificateHold) is the only reversible revocation reason.

Use Cases

Web Application TLS Certificate with Automatic Renewal

Scenario: Apache web server needs TLS certificate with automated renewal.

Solution:

# Create service principal (if not exists)
ipa service-add HTTP/web.example.com

# Request certificate with certmonger tracking
ipa-getcert request -f /etc/httpd/certs/server.crt \
    -k /etc/httpd/certs/server.key \
    -N CN=web.example.com \
    -D web.example.com \
    -K HTTP/web.example.com@EXAMPLE.COM \
    -C "systemctl reload httpd"

# Certmonger automatically:
# - Generates private key
# - Creates CSR
# - Submits to IPA CA
# - Retrieves certificate
# - Monitors expiration
# - Renews automatically ~28 days before expiry
# - Reloads httpd after renewal

Multi-SAN Certificate for Load Balanced Services

Scenario: Load balancer with multiple backend servers needs certificate with SANs.

Solution:

# Request certificate with multiple Subject Alternative Names
ipa-getcert request -f /etc/haproxy/certs/lb.crt \
    -k /etc/haproxy/certs/lb.key \
    -N CN=lb.example.com \
    -D lb.example.com \
    -D www.example.com \
    -D api.example.com \
    -K HTTP/lb.example.com@EXAMPLE.COM

# Certificate valid for all three hostnames
# Clients can connect to any name without certificate warnings

Certificate Revocation After Key Compromise

Scenario: Private key compromised, immediate certificate revocation required.

Solution:

# Find certificate serial number
ipa cert-find --subject=web.example.com

# Revoke with keyCompromise reason
ipa cert-revoke 0x1234567890ABCDEF --revocation-reason=1

# Certificate immediately added to CRL
# OCSP responders mark as revoked
# Clients reject certificate

# Request new certificate with new key
ipa-getcert resubmit -i <tracking-id> -G
# -G generates new key pair

User Smart Card Certificate Issuance

Scenario: Issue smart card certificates for passwordless user authentication.

Solution:

# User generates key pair on smart card
# Export CSR from smart card

# Submit CSR for user certificate
ipa cert-request user-smartcard.csr \
    --principal=alice@EXAMPLE.COM \
    --profile-id=IECUserRoles

# Import certificate to smart card
# Certificate stored in user entry automatically

# User can now authenticate with smart card
kinit alice
# (prompted for smart card PIN instead of password)

Temporary Service Suspension with Certificate Hold

Scenario: Service under investigation, temporarily suspend certificate validity.

Solution:

# Place certificate on hold
ipa cert-revoke 0x1234567890ABCDEF --revocation-reason=6

# Certificate shows as revoked in CRL/OCSP
# Service authentication fails

# After investigation cleared, release hold
ipa cert-remove-hold 0x1234567890ABCDEF

# Certificate valid again
# No new certificate needed

Sub-CA Isolated Certificate Issuance

Scenario: Development environment needs isolated CA preventing cross-use with production.

Solution:

# Create sub-CA for development
ipa ca-add dev-ca --subject="CN=Dev CA,O=Example Corp" \
    --desc="Development environment CA"

# Create certificate profile for dev
ipa certprofile-import dev-service \
    --file=dev-service-profile.cfg \
    --desc="Development service certificates"

# Create CA ACL for dev certificates
ipa caacl-add dev-access --desc="Dev environment certificate access"
ipa caacl-add-ca dev-access --cas=dev-ca
ipa caacl-add-profile dev-access --certprofiles=dev-service
ipa caacl-add-host dev-access --hostgroups=dev-servers

# Dev servers can only request from dev-ca
# Production servers cannot request from dev-ca
# Certificate isolation enforced

Certificate Renewal Grace Period Management

Scenario: Critical service requires extended certificate overlap during renewal.

Solution:

# Request initial certificate
ipa-getcert request -f /etc/service/cert.pem \
    -k /etc/service/key.pem \
    -N CN=critical.example.com \
    -K HTTP/critical.example.com@EXAMPLE.COM

# Configure extended renewal time (60 days before expiry)
getcert start-tracking -f /etc/service/cert.pem \
    -k /etc/service/key.pem \
    -R 60

# Certmonger renews 60 days early
# Long overlap period for gradual rollout

Wildcard Certificate Limitation Alternative

Scenario: Need certificates for multiple subdomains without wildcard certificate.

Solution:

# IPA CA doesn't issue wildcard certificates by default
# Use multiple SANs instead

# Request certificate with all subdomains
ipa-getcert request -f /etc/certs/services.pem \
    -k /etc/certs/services.key \
    -N CN=services.example.com \
    -D api.example.com \
    -D www.example.com \
    -D cdn.example.com \
    -D mail.example.com \
    -K HTTP/services.example.com@EXAMPLE.COM

# Certificate valid for all listed subdomains
# More secure than wildcard (no unlimited subdomain coverage)

External Certificate Import for Public-Facing Service

Scenario: Public website requires certificate from public CA (Let’s Encrypt, etc.).

Solution:

# Obtain certificate from external CA (e.g., Let's Encrypt via certbot)
certbot certonly --standalone -d www.example.com

# Import external certificate to IPA for tracking
ipa service-add-cert HTTP/www.example.com \
    --certificate="$(cat /etc/letsencrypt/live/www.example.com/cert.pem)"

# Certificate tracked in IPA but not issued by IPA CA
# Renewal handled by external tooling (certbot)
# IPA tracks for inventory/compliance

Batch Certificate Issuance for Infrastructure

Scenario: Provision 100 new servers, each needs service certificate.

Solution:

# Create service principals in batch
for host in server{01..100}.example.com; do
    ipa service-add "HTTP/$host"
done

# On each server during provisioning (Ansible, etc.):
# ipa-getcert request -f /etc/httpd/certs/server.crt \
#     -k /etc/httpd/certs/server.key \
#     -N "CN=$(hostname)" \
#     -K "HTTP/$(hostname)@EXAMPLE.COM"

# Automated certificate request during server deployment
# All certificates tracked by certmonger for renewal

Security Considerations

Private key protection critical: Certificate security depends entirely on private key confidentiality. Private keys should never leave the system they’re generated on, have restrictive file permissions (0600), and be stored in hardware security modules for high-security environments.

Certificate revocation checking not universal: Not all clients check CRL/OCSP before accepting certificates. Revoked certificates may still be accepted by clients with disabled revocation checking. Don’t rely solely on revocation for security-critical scenarios.

Subject DN overwriting by profiles: Certificate profiles override CSR subject fields. Attackers cannot manipulate subject DNs via crafted CSRs, but administrators should understand actual subject values differ from CSR submissions.

CA ACL bypass via direct Dogtag access: CA ACLs enforced by IPA framework, not Dogtag itself. Direct access to Dogtag CA (port 8443) bypasses IPA ACLs. Restrict Dogtag port access to IPA servers only via firewall rules.

Certificate hold abuse potential: Certificate hold/release can be abused for service disruption. Repeated hold/release operations may indicate malicious activity. Monitor cert-revoke/cert-remove-hold operations for unusual patterns.

Serial number exposure: Certificate serial numbers are public information visible to all authenticated users. Avoid encoding sensitive data in serial numbers or certificate subjects.

Certmonger renewal windows: Default 28-day renewal window provides safety margin for renewal failures. Shorter renewal windows increase outage risk if CA unavailable. Longer windows extend exposure period for compromised certificates.

External certificate trust assumptions: Importing external certificates to IPA for tracking doesn’t validate them. Administrator must verify external certificate authenticity and chain of trust independently.

Sub-CA compromise scope: Compromised sub-CA can issue arbitrary certificates for its scope but cannot issue certificates claiming to be from IPA root CA. Sub-CAs limit blast radius of CA key compromise.

Certificate profiles enable policy bypass: Overly permissive certificate profiles can grant certificate types inconsistent with security policy. Review custom profiles carefully for unintended capabilities.

Expired certificate persistence: Expired certificates remain in directory and can be retrieved. Depending on client behavior, expired certificates might be cached and reused. Revoke certificates well before expiration for planned decommissioning.

OCSP responder availability: Certificate validation failures if OCSP responder unreachable and client requires OCSP. Ensure OCSP responder high availability for critical certificate-dependent services.

Certificate storage visibility: Certificates in service/host/user entries visible to authenticated users. Public keys and subject information disclosed. Don’t store private/sensitive data in certificate subjects.

Automatic renewal failures: Certmonger renewal failures may go unnoticed until certificate expires causing outage. Monitor certmonger status and renewal success rates actively.

Troubleshooting

Certificate request fails with “Insufficient access”:

# Check CA ACL authorization
ipa caacl-find --principal=HTTP/web.example.com

# If no matching CA ACL, create one
ipa caacl-add web-certs --desc="Web service certificates"
ipa caacl-add-principal web-certs --services=HTTP/web.example.com
ipa caacl-add-profile web-certs --certprofiles=caIPAserviceCert

# Or grant to host (common pattern)
ipa caacl-add web-certs
ipa caacl-add-host web-certs --hosts=web.example.com
ipa caacl-add-profile web-certs --certprofiles=caIPAserviceCert

Certificate request fails with “Service not found”:

# Service principal must exist first
ipa service-show HTTP/web.example.com

# If missing, create service principal
ipa service-add HTTP/web.example.com

# Retry certificate request
ipa cert-request web.csr --principal=HTTP/web.example.com

Certmonger renewal failing continuously:

# Check certmonger status
getcert list

# Look for error messages
getcert list -i <request-id>

# Common issues:
# 1. CA unreachable - check network connectivity
ping ipa.example.com

# 2. Kerberos authentication failure - check keytab
klist -kt /etc/krb5.keytab

# 3. CA ACL no longer permits renewal - check CA ACLs
ipa caacl-find --services=HTTP/hostname.example.com

# Force immediate renewal attempt
getcert resubmit -i <request-id>

# Check logs for details
journalctl -u certmonger -n 50

Certificate shows as expired but was renewed:

# Service may not have reloaded to use new certificate
systemctl status httpd

# Check certificate file modification time
ls -l /etc/httpd/certs/server.crt

# Reload/restart service to use new certificate
systemctl reload httpd

# Verify new certificate in use
openssl s_client -connect web.example.com:443 | openssl x509 -noout -dates

Cannot revoke certificate - serial number not found:

# Find certificate by subject or service
ipa cert-find --subject=web.example.com
ipa cert-find --service=HTTP/web.example.com

# Get serial number from output
# Revoke with correct serial (hex format with 0x prefix)
ipa cert-revoke 0x1234567890ABCDEF --revocation-reason=5

Certificate hold cannot be removed:

# Verify certificate is actually on hold (reason 6)
ipa cert-show 0x1234567890ABCDEF | grep "Revocation reason"

# If revocation reason is not 6, cannot remove hold
# Only certificateHold (reason 6) is reversible

# If trying to restore permanently revoked cert:
# Must request new certificate
ipa cert-request new.csr --principal=HTTP/web.example.com

CSR rejected with subject DN errors:

# Certificate profiles override subject DN
# CSR subject values mostly ignored

# Check which profile being used
ipa certprofile-show caIPAserviceCert

# Ensure CSR has correct CN matching service hostname
# Other fields (O, OU, C) will be overwritten by profile

# Regenerate CSR with correct CN
openssl req -new -key server.key -out server.csr \
    -subj "/CN=web.example.com"

Certificate not appearing in service entry after issuance:

# Verify certificate was issued
ipa cert-find --subject=web.example.com

# Certificate should be automatically associated
ipa service-show HTTP/web.example.com --all | grep -i certificate

# If missing, manually add
ipa service-add-cert HTTP/web.example.com \
    --certificate="$(cat server.crt)"

OCSP responder returning “unknown” status:

# Verify OCSP responder configuration
ipa-cacert-manage status

# Check if OCSP enabled for CA
# On IPA server:
pki-server ca-config-show ca.ocsp.enable

# Verify certificate serial in CA database
# If certificate very new, may need cache refresh time
# Wait a few minutes and retry

# Test OCSP manually
openssl ocsp -issuer /etc/ipa/ca.crt -cert server.crt \
    -url http://ipa.example.com/ca/ocsp \
    -CAfile /etc/ipa/ca.crt

Certificate request succeeds but certmonger shows “CA_REJECTED”:

# Check Dogtag CA logs
journalctl -u pki-tomcatd@pki-tomcat -n 100

# Common causes:
# 1. Invalid CSR format/parameters
# 2. Profile constraints violated
# 3. CA database issues

# Verify CSR is valid
openssl req -text -noout -verify -in server.csr

# Try different certificate profile
getcert resubmit -i <request-id> -T caIPAserviceCert

Multiple certificates exist, which one is active?:

# List all certificates for service
ipa cert-find --service=HTTP/web.example.com

# Check validity dates
ipa cert-show 0x<serial> | grep "Valid"

# Check revocation status
ipa cert-show 0x<serial> | grep "Revoked"

# Active certificate:
# - Not revoked
# - Current date within validity period
# - Typically newest non-revoked certificate

Certificate renewal created new key pair unexpectedly:

# Check certmonger tracking options
getcert list -i <request-id>

# If "Reuse existing key pair: no", new key generated
# Change to reuse existing key
getcert stop-tracking -i <request-id>
getcert start-tracking -f /etc/certs/cert.pem \
    -k /etc/certs/key.pem \
    -r  # Reuse key pair

# Future renewals will keep same key

Sub-CA certificate request failing:

# Verify sub-CA exists and is enabled
ipa ca-show sub-ca-name

# Verify CA ACL permits request to sub-CA
ipa caacl-find --cas=sub-ca-name

# Specify sub-CA in certificate request
ipa cert-request server.csr \
    --principal=HTTP/web.example.com \
    --ca=sub-ca-name \
    --profile-id=caIPAserviceCert

Certificate request timeout:

# CA may be overloaded or database locked
# Check CA status
systemctl status pki-tomcatd@pki-tomcat

# Check CA database
pki-server ca-db-status

# Increase timeout and retry
ipa cert-request server.csr --principal=HTTP/web.example.com \
    --timeout=120

External certificate import fails:

# Verify certificate format (PEM or DER)
openssl x509 -in external.crt -noout -text

# If DER format, convert to PEM
openssl x509 -inform der -in external.crt -out external.pem

# Ensure certificate is base64 encoded (no line breaks for --certificate)
ipa service-add-cert HTTP/web.example.com \
    --certificate="$(cat external.pem | grep -v BEGIN | grep -v END | tr -d '\n')"

Best Practices

Certificate Request Management

Pre-create service principals: Create service principals before requesting certificates rather than relying on --add. This enables proper access control configuration and principal attribute setting before certificate issuance.

Use appropriate certificate profiles: Select certificate profiles that match certificate purpose. Service certificates should use service-specific profiles, user certificates should use user profiles. Incorrect profile selection can result in certificates lacking necessary extensions.

Validate CSR content: Before submitting CSRs, verify they contain correct public keys and subject information. Incorrect CSRs result in certificates that don’t match private keys or have unexpected subject fields.

Document certificate purposes: Maintain records of why certificates were issued, which services use them, and expected lifecycle. This documentation aids troubleshooting and prevents accidental revocation of active certificates.

Renewal and Lifecycle

Leverage certmonger for automatic renewal: Configure all IPA-issued service certificates in certmonger for automatic renewal. This prevents expiration outages and eliminates manual renewal processes.

Monitor certificate expiration: Even with automatic renewal, monitor certificate expiration dates to detect renewal failures. Alert on certificates expiring within 14 days.

Test certificate renewal in non-production: Verify automatic renewal works correctly before deploying to production. Renewal failures often surface during the first renewal attempt.

Plan for certificate rollover: When renewing certificates, ensure both old and new certificates work during the transition period. Some services support multiple simultaneous certificates for smooth rollover.

Revocation Practices

Revoke promptly when compromise suspected: If private key compromise is suspected, revoke immediately. Delaying revocation extends the window for potential misuse.

Use appropriate revocation reasons: Select revocation reasons accurately. This information aids security audits and incident investigation. keyCompromise and cessationOfOperation are most commonly appropriate.

Consider certificateHold for investigations: When investigating potential compromise, use certificateHold rather than permanent revocation. If investigation clears the certificate, it can be removed from hold.

Communicate revocations: When revoking service certificates, ensure service owners are notified. Revocation causes immediate service disruption if not coordinated.

Security Considerations

Protect private keys: Never share private keys across systems. Each service should have its own private key and certificate. Shared keys multiply compromise impact.

Implement CRL/OCSP checking: Configure clients to check certificate revocation status via CRL or OCSP. Without revocation checking, revoked certificates remain usable by attackers.

Audit certificate issuance regularly: Review certificate issuance logs to detect unauthorized requests or unusual patterns. Regular audits help identify compromised credentials.

Use strong key algorithms: Generate CSRs with strong key algorithms (RSA 2048+ bits, ECDSA P-256+). Weak keys reduce certificate security regardless of CA strength.

Limit CA ACL scope: CA ACLs should grant minimal necessary certificate issuance privileges. Overly broad CA ACLs enable unauthorized certificate issuance.

Operational Practices

Maintain certificate inventory: Track all issued certificates, their purposes, and owners. IPA provides this inventory through cert-find, but supplement with organizational documentation.

Establish certificate naming conventions: Use consistent service principal naming conventions. This simplifies certificate searches and prevents naming conflicts.

Test certificate deployment before production: Verify new certificates work correctly in test environments before deploying to production services. Certificate errors can be difficult to diagnose in production.

Plan for CA migration: If migrating to new CAs or changing certificate hierarchies, plan transition carefully. Services may need dual certificates during migration periods.

Document emergency revocation procedures: Establish clear procedures for emergency certificate revocation including authorization, communication, and execution. Delayed revocation during incidents multiplies damage.

Integration with Other IPA Components

Service Principals

Every certificate is associated with a service principal. Service principal management (service-* commands) creates the principals that certificates are issued to. Service principals track all certificates issued to that principal.

Host Entries

Certificates for host principals (host/hostname) and services on hosts require the host to exist in IPA. Host management (host-* commands) creates the hosts that certificates are associated with.

Certificate Profiles

Certificate profiles (certprofile-* commands) define templates for certificate issuance. Profile selection during certificate requests determines certificate characteristics including validity period and extensions.

CA ACLs

Certificate Access Control Lists (caacl-* commands) determine who can request certificates using which profiles from which CAs. CA ACL evaluation occurs before certificate issuance.

Sub-CAs

Sub-CAs (ca-* commands) provide separate certificate issuance hierarchies within IPA. Certificates can be requested from specific sub-CAs using --ca parameter, enabling certificate issuance isolation.

Certmonger

Certmonger on IPA clients automates certificate renewal, monitoring expiration and requesting renewals from the IPA CA. Certmonger integration eliminates manual certificate lifecycle management.

Smart Card Authentication

User certificates enable smart card authentication. Certificates stored in user entries (user-add-cert) are matched against certificates presented from smart cards during authentication.

Commands

cert-find

Usage: ipa [global-options] cert-find [CRITERIA] [options]

Search for existing certificates.

For certificates not issued by IPA CA,
only --certificate option is supported.

Arguments

Argument Required Description

CRITERIA no A string searched in all relevant object attributes

Options

Option	Description
`--certificate CERTIFICATE`	Base-64 encoded certificate.
`--issuer ISSUER`	Issuer DN
`--revocation-reason REVOCATION-REASON`	Reason for revoking the certificate (0-10). Type “ipa help cert” for revocation reason details.
`--ca CA`	Name of issuing CA
`--subject SUBJECT`	Match cn attribute in subject
`--min-serial-number MIN-SERIAL-NUMBER`	minimum serial number
`--max-serial-number MAX-SERIAL-NUMBER`	maximum serial number
`--exactly`	match the common name exactly
`--validnotafter-from VALIDNOTAFTER-FROM`	Valid not after from this date (YYYY-mm-dd)
`--validnotafter-to VALIDNOTAFTER-TO`	Valid not after to this date (YYYY-mm-dd)
`--validnotbefore-from VALIDNOTBEFORE-FROM`	Valid not before from this date (YYYY-mm-dd)
`--validnotbefore-to VALIDNOTBEFORE-TO`	Valid not before to this date (YYYY-mm-dd)
`--issuedon-from ISSUEDON-FROM`	Issued on from this date (YYYY-mm-dd)
`--issuedon-to ISSUEDON-TO`	Issued on to this date (YYYY-mm-dd)
`--revokedon-from REVOKEDON-FROM`	Revoked on from this date (YYYY-mm-dd)
`--revokedon-to REVOKEDON-TO`	Revoked on to this date (YYYY-mm-dd)
`--status STATUS`	Status of the certificate
`--pkey-only`	Results should contain primary key attribute only (“certificate”)
`--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.
`--users USERS`	Search for certificates with these owner users.
`--no-users NO-USERS`	Search for certificates without these owner users.
`--hosts HOSTS`	Search for certificates with these owner hosts.
`--no-hosts NO-HOSTS`	Search for certificates without these owner hosts.
`--services SERVICES`	Search for certificates with these owner services.
`--no-services NO-SERVICES`	Search for certificates without these owner services.

cert-remove-hold

Usage: ipa [global-options] cert-remove-hold SERIAL-NUMBER [options]

Take a revoked certificate off hold.

Arguments

Argument	Required	Description
`SERIAL-NUMBER`	yes	Serial number in decimal or if prefixed with 0x

                           in hexadecimal

Options

Option	Description
`--ca CA`	Name of issuing CA

cert-request

Usage: ipa [global-options] cert-request CSR-FILE [options]

Submit a certificate signing request.

Arguments

Argument	Required	Description
`CSR-FILE`	yes	CSR

Options

Option	Description
`--profile-id PROFILE-ID`	Certificate Profile to use
`--ca CA`	Name of issuing CA
`--principal PRINCIPAL`	Principal for this certificate (e.g. HTTP/test.example.com)
`--add`	automatically add the principal if it doesn’t exist (service principals only)
`--chain`	Include certificate chain in output
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.

cert-revoke

Usage: ipa [global-options] cert-revoke SERIAL-NUMBER [options]

Revoke a certificate.

Arguments

Argument	Required	Description
`SERIAL-NUMBER`	yes	Serial number in decimal or if prefixed with 0x

                           in hexadecimal

Options

Option	Description
`--revocation-reason REVOCATION-REASON`	Reason for revoking the certificate (0-10). Type “ipa help cert” for revocation reason details.
`--ca CA`	Name of issuing CA

cert-show

Usage: ipa [global-options] cert-show SERIAL-NUMBER [options]

Retrieve an existing certificate.

Arguments

Argument	Required	Description
`SERIAL-NUMBER`	yes	Serial number in decimal or if prefixed with 0x

                           in hexadecimal

Options

Option	Description
`--ca CA`	Name of issuing CA
`--out OUT`	File to store the certificate in.
`--chain`	Include certificate chain in output
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.
`--no-members`	Suppress processing of membership attributes.

cert-status

Usage: ipa [global-options] cert-status REQUEST-ID [options]

Check the status of a certificate signing request.

Arguments

Argument	Required	Description
`REQUEST-ID`	yes	Request id

Options

Option	Description
`--ca CA`	Name of issuing CA
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.

Overview

Certificate Request Prerequisites

Certificate Signing Requests (CSRs)

Certificate Profiles

Certificate Revocation

Certificate Hold and Release

Certificate Storage and Association

Automatic Renewal with Certmonger

External Certificates

Certificate Search Capabilities

Examples

Certificate Requests

Certificate Retrieval

Certificate Revocation

Certificate Search

Request Status Checking

Revocation Reason Codes

Use Cases

Web Application TLS Certificate with Automatic Renewal

Multi-SAN Certificate for Load Balanced Services

Certificate Revocation After Key Compromise

User Smart Card Certificate Issuance

Temporary Service Suspension with Certificate Hold

Sub-CA Isolated Certificate Issuance

Certificate Renewal Grace Period Management

Wildcard Certificate Limitation Alternative

External Certificate Import for Public-Facing Service

Batch Certificate Issuance for Infrastructure

Security Considerations

Troubleshooting

Best Practices

Certificate Request Management

Renewal and Lifecycle

Revocation Practices

Security Considerations

Operational Practices

Integration with Other IPA Components

Service Principals

Host Entries

Certificate Profiles

CA ACLs

Sub-CAs

Certmonger

Smart Card Authentication

Commands

cert-find

Arguments

Options

cert-remove-hold

Arguments

Options

cert-request

Arguments

Options

cert-revoke

Arguments

Options

cert-show

Arguments

Options

cert-status

Arguments

Options

Related Topics