Certificate Authority - CLI Reference

Overview

FreeIPA’s integrated Public Key Infrastructure (PKI) is powered by Dogtag Certificate System, providing a complete X.509 certificate authority for issuing, managing, and revoking certificates. The root Certificate Authority, called “ipa”, is created automatically during IPA server installation and serves as the trust anchor for the entire IPA domain.

Beyond the root CA, FreeIPA supports subordinate Certificate Authorities (sub-CAs)—lightweight CAs that issue certificates under the authority of the root CA. Sub-CAs enable certificate isolation, policy enforcement, and organizational segmentation without deploying separate PKI infrastructure.

Sub-CAs provide several architectural benefits:

Certificate Isolation: Different sub-CAs for different purposes (user certificates, service certificates, device certificates, code signing) enable policy segmentation and controlled revocation scope.

Organizational Units: Different departments or business units can have dedicated sub-CAs with unit-specific certificate policies and naming conventions.

Trust Partitioning: Compromise or revocation of a sub-CA’s signing certificate doesn’t affect certificates issued by other sub-CAs or the root CA.

Policy Enforcement: Certificate profiles and ACLs can be scoped to specific sub-CAs, enabling different validation rules, certificate lifetimes, and issuance policies per sub-CA.

Compliance Requirements: Some compliance frameworks require separation of certificate authorities for different purposes (e.g., separate CAs for employee vs contractor certificates).

CA Architecture

Root CA (ipa)

The ipa CA is the trust anchor for the entire IPA domain:

Created automatically during ipa-server-install
Self-signed root certificate (or externally signed if using external CA)
Cannot be disabled or deleted
Issues certificates directly and signs subordinate CA certificates
All IPA-enrolled systems trust the ipa CA certificate

The ipa CA certificate is distributed to all IPA clients via SSSD and stored in system trust stores (/etc/pki/ca-trust/ on RHEL/Fedora, /usr/local/share/ca-certificates/ on Debian/Ubuntu).

Subordinate CAs (Sub-CAs)

Sub-CAs are lightweight certificate authorities created within FreeIPA:

Signed by the ipa CA (forming a certificate chain: Root CA → Sub-CA → End Entity Certificate)
Independent signing key pair (private key stored in Dogtag HSM)
Independent certificate serial number range
Can be enabled, disabled, and deleted (unlike root CA)
Subject to CA ACL policies for controlled certificate issuance
Support same certificate profiles as root CA (or subset via ACLs)

Each sub-CA has:

Name: Human-readable identifier (e.g., “puppet”, “vpn”, “code-signing”)
Subject DN: Distinguished Name identifying the CA (e.g., “CN=Puppet CA,O=EXAMPLE.COM”)
Signing Certificate: X.509 certificate signed by the ipa CA
Private Key: Stored securely in Dogtag’s NSSDB or HSM
Dogtag Authority ID: Internal identifier used by Dogtag Certificate System

Certificate Chain

Certificates issued by sub-CAs form a three-level chain:

Root CA (ipa)
  ↓ signs
Subordinate CA (puppet)
  ↓ signs
End Entity Certificate (puppet-master.example.com)

Clients validating end entity certificates must trust the entire chain. Since IPA clients trust the root CA, they automatically trust sub-CA-issued certificates as long as the chain is valid.

CA Lifecycle

Creation

Creating a sub-CA requires:

Unique name within IPA
Subject Distinguished Name (DN) with organization and common name
Appropriate RBAC permissions (“System: Add CA”)

Upon creation:

IPA generates a new key pair for the sub-CA
Dogtag creates a Certificate Signing Request (CSR)
CSR is submitted to the root CA for signing
Signed certificate is stored and the sub-CA becomes operational
Sub-CA is enabled by default and ready to issue certificates

Enabled State

Enabled sub-CAs can issue certificates:

Certificate requests can specify the sub-CA via --ca=<name> option
Subject to CA ACL policies (which users/groups/hosts/services can use which CAs)
Certificates are signed with the sub-CA’s private key
Certificate chain includes the sub-CA and root CA certificates

Disabled State

Disabling a sub-CA prevents it from issuing new certificates:

Certificate requests specifying the disabled sub-CA fail
Existing certificates issued by the sub-CA remain valid (disabling doesn’t revoke them)
Sub-CA’s signing certificate remains valid
Can be re-enabled to resume certificate issuance
Useful for temporary suspension (incident response, policy changes)

All sub-CAs except the root “ipa” CA can be disabled.

Deletion

Deleting a sub-CA is permanent and irreversible:

Sub-CA must be disabled first (safety measure)
Sub-CA’s signing certificate is revoked and added to the CRL
Sub-CA’s private key is deleted from Dogtag
No new certificates can be issued by this sub-CA
Existing certificates issued by the sub-CA become invalid (chain validation fails when clients check CRL)
Requires “System: Delete CA” permission

Warning: Deletion revokes the sub-CA’s signing certificate, invalidating all certificates it issued. Only delete sub-CAs when all issued certificates are no longer needed.

Subject Distinguished Name

Each sub-CA requires a Subject DN identifying the CA in the X.509 certificate:

Format: CN=<Common Name>,O=<Organization>[,OU=<Organizational Unit>][,C=<Country>]

Common Name (CN): Human-readable CA name (e.g., “Puppet CA”, “VPN CA”, “Code Signing Authority”)

Organization (O): Organization name, typically matching the IPA domain (e.g., “EXAMPLE.COM”, “Example Corporation”)

Organizational Unit (OU): Optional business unit identifier (e.g., “Engineering”, “Security”)

Country (C): Optional two-letter country code (e.g., “US”, “GB”)

Requirements:

CN is required and should clearly identify the CA’s purpose
O is required and should align with organizational identity
Subject DN must be unique across all CAs in the IPA domain
Subject DN should follow X.500 naming conventions

Examples:

CN=Puppet CA,O=EXAMPLE.COM
CN=VPN Certificate Authority,O=Example Corporation,OU=IT Security,C=US
CN=Code Signing CA,O=EXAMPLE.COM
CN=Device Certificates,O=Example Corporation,OU=IoT

CA ACL Integration

Sub-CAs are subject to Certificate Authority Access Control Lists (CA ACLs):

CA ACL Purpose: Define which users, groups, hosts, host groups, and services can request certificates from which CAs using which certificate profiles.

Default Behavior: Upon creation, sub-CAs have no CA ACLs, meaning no one (except those with “bypass CA ACL” privilege) can request certificates from the sub-CA.

Access Grant: Administrators must create CA ACL rules to grant specific entities access to specific sub-CAs:

# Allow engineers group to request certificates from the puppet CA
$ ipa caacl-add "Engineers use Puppet CA"
$ ipa caacl-add-ca "Engineers use Puppet CA" --cas=puppet
$ ipa caacl-add-user "Engineers use Puppet CA" --groups=engineers
$ ipa caacl-add-profile "Engineers use Puppet CA" --certprofiles=caIPAserviceCert

This integration enables fine-grained control over which entities can use which CAs, supporting separation of duties and compliance requirements.

See caacl topic for comprehensive CA ACL documentation.

Use Cases

Application-Specific CAs

Different applications or services may require dedicated CAs:

Puppet: Dedicated CA for Puppet server/agent certificates VPN: Dedicated CA for VPN user and gateway certificates Web Services: Dedicated CA for internal web application certificates Code Signing: Dedicated CA for signing software packages and scripts

This separation enables different certificate policies (lifetimes, key sizes, extensions) and controlled trust scopes.

Departmental CAs

Large organizations may create sub-CAs per department:

Engineering CA: Certificates for engineering team members and systems HR CA: Certificates for HR systems and staff Finance CA: Certificates for financial systems with stricter audit requirements

Each department can have dedicated administrators managing their sub-CA via CA ACLs and delegated permissions.

Compliance and Audit

Compliance frameworks may require certificate separation:

Employee CA: Certificates for full-time employees Contractor CA: Certificates for contractors and temporary staff (shorter validity periods) External Partner CA: Certificates for external business partners (restricted profiles)

Different CAs enable different audit trails, revocation policies, and validity periods to meet compliance requirements.

Environment Segregation

Separate sub-CAs for different operational environments:

Production CA: Certificates for production systems (strict ACLs, longer validity) Staging CA: Certificates for staging/QA systems (relaxed ACLs, moderate validity) Development CA: Certificates for development systems (very relaxed ACLs, short validity)

This prevents accidental use of production certificates in non-production environments.

Certificate Lifecycle Management

Sub-CAs enable controlled certificate lifecycle experiments:

Long-Lived CA: Certificates with multi-year validity (infrastructure certificates) Short-Lived CA: Certificates with days/weeks validity (ephemeral workloads, containers) Test CA: Experimental CA for testing new certificate profiles or policies

Examples

Create Basic Sub-CA

# Create subordinate CA for Puppet infrastructure
$ ipa ca-add puppet \
  --desc="Puppet Certificate Authority" \
  --subject="CN=Puppet CA,O=EXAMPLE.COM"

  CA name: puppet
  Description: Puppet Certificate Authority
  Authority ID: <dogtag-authority-id>
  Subject DN: CN=Puppet CA,O=EXAMPLE.COM
  Issuer DN: CN=Certificate Authority,O=EXAMPLE.COM

Create Sub-CA with Organizational Unit

# Create sub-CA for VPN with organizational unit
$ ipa ca-add vpn \
  --desc="VPN Certificate Authority" \
  --subject="CN=VPN CA,O=Example Corporation,OU=IT Security,C=US"

Create Sub-CA for Code Signing

# Create dedicated CA for code signing certificates
$ ipa ca-add code-signing \
  --desc="Code Signing Authority" \
  --subject="CN=Code Signing CA,O=EXAMPLE.COM"

List All CAs

# View all CAs including root and sub-CAs
$ ipa ca-find
  2 CAs matched
  CA name: ipa
  Description: IPA CA
  CA name: puppet
  Description: Puppet Certificate Authority

Show CA Details

# View specific CA information
$ ipa ca-show puppet
  CA name: puppet
  Description: Puppet Certificate Authority
  Authority ID: a1b2c3d4-5678-90ab-cdef-1234567890ab
  Subject DN: CN=Puppet CA,O=EXAMPLE.COM
  Issuer DN: CN=Certificate Authority,O=EXAMPLE.COM
  Enabled: TRUE

Show CA with Certificate Chain

# View CA details including certificate chain
$ ipa ca-show puppet --chain
  CA name: puppet
  [... CA details ...]
  Certificate: MIIDzTCCArWgAwIBAgIBATANBgkqhkiG9w0BAQsFADA...
  Certificate chain: MIIDzTCCArWgAwIBAgIBATANBgkqhkiG9w0BAQsFADA...,
                     MIIECTCCAvGgAwIBAgIBATANBgkqhkiG9w0BAQsFADA...

Disable Sub-CA

# Temporarily disable CA (incident response or policy change)
$ ipa ca-disable puppet
  Disabled CA "puppet"

# Verify CA is disabled
$ ipa ca-show puppet | grep Enabled
  Enabled: FALSE

Re-enable Sub-CA

# Re-enable previously disabled CA
$ ipa ca-enable puppet
  Enabled CA "puppet"

Modify CA Description

# Update CA description
$ ipa ca-mod puppet \
  --desc="Puppet Infrastructure Certificate Authority"

  CA name: puppet
  Description: Puppet Infrastructure Certificate Authority

Search CAs by Subject

# Find CAs by subject DN pattern
$ ipa ca-find --subject="*Puppet*"
  1 CA matched
  CA name: puppet
  Subject DN: CN=Puppet CA,O=EXAMPLE.COM

Delete Sub-CA

# Must disable before deletion (safety check)
$ ipa ca-disable puppet
  Disabled CA "puppet"

# Permanently delete CA (revokes signing cert, deletes private key)
$ ipa ca-del puppet
  Deleted CA "puppet"

# WARNING: All certificates issued by this CA are now invalid

Create Multiple Sub-CAs

# Create sub-CAs for different application tiers
$ ipa ca-add production \
  --desc="Production Environment CA" \
  --subject="CN=Production CA,O=EXAMPLE.COM"

$ ipa ca-add staging \
  --desc="Staging Environment CA" \
  --subject="CN=Staging CA,O=EXAMPLE.COM"

$ ipa ca-add development \
  --desc="Development Environment CA" \
  --subject="CN=Development CA,O=EXAMPLE.COM"

Request Certificate from Sub-CA

# Request service certificate from specific sub-CA
$ ipa cert-request puppet-server.csr \
  --principal=puppet/puppet-server.example.com \
  --ca=puppet

  Certificate: MIIECTCCAvGgAwIBAgIBATANBgkqhkiG9w0BAQsFADA...
  Subject: CN=puppet-server.example.com,O=EXAMPLE.COM
  Issuer: CN=Puppet CA,O=EXAMPLE.COM
  [Certificate signed by puppet sub-CA]

Best Practices

Sub-CA Design

Purpose-specific CAs: Create sub-CAs based on certificate purpose or application, not organizational structure. “VPN CA” is better than “Engineering CA” because VPN purpose is stable while organizational structure changes.

Clear naming: Use descriptive CA names that indicate purpose: “puppet”, “code-signing”, “vpn”, “web-services”. Avoid generic names like “subca1”, “test”, “misc”.

Subject DN consistency: Use consistent DN format across all sub-CAs for easier management. All should include O (organization), and CN (common name) should clearly identify purpose.

Limit sub-CAs: Don’t create excessive sub-CAs. Each sub-CA adds complexity (ACLs, policies, administration). Only create when genuine need for certificate isolation or policy separation exists.

Security Considerations

Protect private keys: Sub-CA private keys are stored in Dogtag’s NSSDB or HSM. Ensure Dogtag server has appropriate physical and logical security controls.

CA ACLs required: Always create CA ACLs for sub-CAs immediately after creation. Unrestricted sub-CA access defeats the purpose of isolation.

Disable unused CAs: If a sub-CA is no longer needed but certificates must remain valid, disable it to prevent new issuance while keeping existing certificates valid.

Delete carefully: Deleting a sub-CA revokes its signing certificate, invalidating ALL certificates it issued. Only delete when absolutely certain all issued certificates are no longer needed.

Monitor certificate issuance: Track which sub-CAs are issuing certificates and to whom. Unusual issuance patterns may indicate compromised credentials or policy violations.

Operational Practices

Document sub-CA purposes: Maintain documentation explaining why each sub-CA exists, which applications/teams use it, and what certificate profiles are permitted.

Regular audits: Periodically review sub-CAs to ensure they’re still needed and being used appropriately. Delete or disable obsolete sub-CAs.

Change management: Treat sub-CA creation, modification, and deletion as significant infrastructure changes requiring approval and communication.

Test before production: Test certificate issuance from new sub-CAs in non-production environments before granting production access.

Backup considerations: While IPA backup includes CA configuration, ensure disaster recovery procedures account for sub-CA reconstruction if needed.

CA ACL Integration

Create ACLs immediately: After creating a sub-CA, immediately create CA ACL rules defining who can use it. Unrestricted sub-CAs defeat security goals.

Least privilege: Grant CA access only to users/groups/hosts/services that require certificates from that specific CA. Don’t grant organization-wide access.

Profile restrictions: Restrict which certificate profiles can be used with each sub-CA via CA ACLs. Not all profiles make sense for all sub-CAs.

Review and update: Regularly review CA ACLs to ensure they still reflect current access requirements and organizational structure.

Integration Points

Certificates

Sub-CAs issue X.509 certificates just like the root CA:

Certificate requests: Use --ca=<name> option to request certificates from specific sub-CAs Certificate profiles: Sub-CAs support the same certificate profiles as root CA (subject to CA ACL restrictions) Certificate chain: Certificates issued by sub-CAs include the sub-CA certificate and root CA certificate in the chain

Commands: cert-request, cert-show, cert-revoke

CA ACLs

CA ACLs control which entities can request certificates from which CAs:

Access control: CA ACLs define user/group/host/service access to sub-CAs Profile restrictions: CA ACLs also restrict which certificate profiles can be used Default deny: Without CA ACL rules, sub-CAs are inaccessible (except to privileged users)

Commands: caacl-add, caacl-add-ca, caacl-add-user, caacl-add-profile

Certificate Profiles

Certificate profiles define certificate templates and validation rules:

Profile application: Profiles can be used with any CA (root or sub-CA) unless restricted by CA ACLs Profile-CA combinations: Different CA-profile combinations enable flexible certificate policies CA ACL restrictions: Specific profiles can be restricted to specific CAs for policy enforcement

Commands: certprofile-find, certprofile-show, certprofile-import

Dogtag Certificate System

Sub-CAs are lightweight authorities within Dogtag PKI:

Dogtag integration: IPA manages sub-CAs via Dogtag’s REST API Authority IDs: Each sub-CA has a unique Dogtag Authority ID Shared infrastructure: All sub-CAs share the same Dogtag instance (no separate processes) HSM support: Sub-CA private keys can be stored in Hardware Security Modules if Dogtag is configured for HSM

Replication

Sub-CA configuration replicates across IPA servers:

CA data replication: Sub-CA metadata (name, subject, description) replicates via LDAP Dogtag replication: Sub-CA certificates and configuration replicate to all CA-enabled IPA replicas Certificate issuance: Any CA-enabled IPA replica can issue certificates from any sub-CA

RBAC

Sub-CA management requires appropriate permissions:

“System: Add CA”: Required to create new sub-CAs “System: Modify CA”: Required to enable/disable or modify sub-CAs “System: Delete CA”: Required to delete sub-CAs “System: Read CAs”: Required to view CA information

These permissions are typically granted via the “CA Administrator” role.

Security Considerations

1. Sub-CA Deletion Revokes All Issued Certificates

Deleting a sub-CA revokes its signing certificate, invalidating all certificates it issued.

Deletion of sub-CA adds its signing certificate to CRL
All end-entity certificates issued by deleted sub-CA fail chain validation
Services using sub-CA-issued certificates immediately lose functionality
No recovery mechanism; certificates cannot be re-validated after deletion
Before deletion, identify and replace all certificates issued by sub-CA
Consider disabling instead of deleting for temporary suspension

2. Sub-CA Private Key Compromise

Compromise of a sub-CA’s private key enables attacker to issue fraudulent certificates.

Attacker with sub-CA private key can issue certificates for any subject
Fraudulent certificates appear valid and trusted by all IPA clients
Compromise limited to sub-CA scope; other sub-CAs and root CA unaffected
Immediate response: disable sub-CA, revoke sub-CA signing certificate
Replace all certificates issued by compromised sub-CA
Sub-CA private keys stored in Dogtag NSSDB or HSM; protect with filesystem and HSM security

3. CA ACL Bypass Privilege

Users with “bypass CA ACL” privilege can request certificates from any CA without ACL restrictions.

Bypass privilege granted through “Certificate Manager Agents” role by default
Overly broad privilege assignment enables unauthorized certificate issuance
Attackers with this privilege can request certificates from any sub-CA
Limit “bypass CA ACL” privilege to minimal administrators
Regular certificate managers should be subject to CA ACL restrictions
Audit role membership regularly for “Certificate Manager Agents”

4. Subject DN Collision with External CAs

Sub-CA subject DNs must be unique but may collide with external certificate authorities.

Subject DN like “CN=VPN CA,O=EXAMPLE.COM” could match external CA
Certificate chain validation may fail if external CA has same subject DN
Name constraints in root CA certificate can prevent collision issues
Use organization-specific naming conventions (e.g., “CN=IPA VPN CA”)
Document all CA subject DNs to prevent internal collisions

5. Inadequate CA ACL Configuration

Default-deny CA ACL model requires explicit access grants; misconfiguration denies legitimate access.

New sub-CA without CA ACLs denies all certificate requests
Users encounter authorization failures without clear error messages
Overly restrictive CA ACLs block legitimate business workflows
Test CA ACL configuration with non-privileged users before production
Create CA ACL rules immediately after creating sub-CA
Document which groups should access which sub-CAs

6. Certificate Revocation Propagation Delay

Sub-CA deletion revokes signing certificate, but CRL propagation takes time.

Clients cache CRLs with configurable TTL (typically hours)
Clients with cached CRLs continue trusting deleted sub-CA’s certificates temporarily
OCSP provides real-time revocation checking but may not be enabled
Plan sub-CA deletion during maintenance windows when impact tolerable
Force client CRL refresh if immediate revocation required
Enable OCSP for real-time revocation validation in high-security environments

7. Insufficient Sub-CA Isolation for Compliance

Single Dogtag instance hosts all sub-CAs; compromise affects entire PKI infrastructure.

All sub-CAs share same Dogtag process and database
Dogtag compromise impacts all sub-CAs simultaneously
Physical separation of CAs may be required for highest security compliance
IPA sub-CAs provide logical, not physical, isolation
For critical separation requirements, consider separate Dogtag instances or external CAs
Document sub-CA architecture for compliance audits

8. Disabled CA Re-Enablement Without Review

Disabled sub-CAs can be re-enabled without reviewing why they were disabled.

Sub-CA disabled for security incident can be re-enabled accidentally
No built-in approval workflow for re-enablement
Re-enablement immediately allows certificate issuance
Document reason for disablement in CA description field
Implement organizational policy requiring review before re-enablement
Monitor CA enable/disable operations in audit logs

9. Root CA Cannot Be Disabled

The root “ipa” CA cannot be disabled, providing no emergency shutoff for entire PKI.

Compromise or misconfiguration of root CA cannot be quickly contained
All IPA clients trust root CA unconditionally
No mechanism to globally disable certificate issuance
Harden root CA security with strict RBAC and audit logging
Monitor root CA certificate issuance for anomalies
Incident response requires revoking individual certificates, not disabling CA

10. CA Certificate Expiration

Sub-CA signing certificates have finite lifetimes; expiration invalidates all issued certificates.

Default sub-CA certificate lifetime varies (typically 10-20 years)
Expired sub-CA cannot issue new certificates
Existing certificates issued by expired sub-CA fail chain validation
Monitor CA certificate expiration dates; renew before expiration
Set calendar reminders 1 year before sub-CA certificate expiration
Renewal requires generating new CSR and re-signing by root CA

11. Subject DN Modification Not Supported

Sub-CA subject DN cannot be changed after creation; requires delete and recreate.

Subject DN embedded in signing certificate; cannot be modified
Changing subject DN requires deleting sub-CA (revokes signing cert)
All certificates issued by deleted sub-CA become invalid
Choose subject DNs carefully during sub-CA creation
If change required, create new sub-CA and migrate certificate issuance
Replace all existing certificates with new sub-CA-issued certificates

12. CA Administrator Privilege Escalation

CA administrators can create sub-CAs and define CA ACLs, enabling self-privilege grants.

CA admin can create sub-CA, add self to CA ACL, issue arbitrary certificates
Certificate issuance enables authentication as any principal
Separation of duties: different teams for CA management vs CA ACL management
Audit CA creation and CA ACL modification operations
Implement two-person rule for sub-CA creation in high-security environments

13. Dogtag Database Backup Requirements

Sub-CA private keys stored in Dogtag database; loss prevents certificate issuance and renewal.

Dogtag database contains all CA private keys
Database corruption or loss renders all sub-CAs non-functional
Cannot re-create sub-CA with same subject DN (signing cert already issued/revoked)
Regular Dogtag database backups essential for disaster recovery
Test backup restoration procedures in non-production environment
Store backups encrypted and offline; contain CA private keys

14. Certificate Serial Number Exhaustion

Each sub-CA has independent serial number range; exhaustion prevents new certificates.

Default serial number range typically very large (unlikely to exhaust)
Misconfiguration or bugs could cause rapid serial consumption
Serial number exhaustion prevents new certificate issuance
Monitor serial number utilization in Dogtag logs
Serial number range expansion requires Dogtag reconfiguration

15. Multi-Master CA Inconsistency

Sub-CA operations require all CA-enabled replicas to be synchronized.

Sub-CA creation replicates to all IPA servers via LDAP
Dogtag-level sub-CA configuration must synchronize across CA replicas
Replication lag or failure creates inconsistent PKI state
Certificate issuance may fail if attempted on unsynchronized replica
Monitor LDAP and Dogtag replication health
Allow 60-120 seconds after sub-CA operations before certificate requests

Troubleshooting

1. Cannot Create Sub-CA - Permission Denied

Symptom: ca-add command fails with “Insufficient access” error.

Diagnosis:

# Check current user permissions
ipa user-show $(whoami) --all | grep "memberof role"

# Verify CA Administrator role membership
ipa role-show "CA Administrator" | grep members

Resolution:

User needs “System: Add CA” permission
Request admin to grant CA Administrator role:

  ipa role-add-member "CA Administrator" --users=username

Or request specific CA management permission through privilege

2. Sub-CA Certificate Requests Fail - CA ACL Denial

Symptom: Certificate request specifying sub-CA fails with “CA ACL check failed” error.

Diagnosis:

# Check if CA ACLs exist for the sub-CA
ipa caacl-find --cas=puppet

# Test CA ACL for specific user/host
ipa caacl-find | grep -B5 -A10 puppet

# Show specific CA ACL details
ipa caacl-show "CA ACL Name"

Resolution:

Create CA ACL granting access to sub-CA:

  ipa caacl-add "Engineers use Puppet CA"
  ipa caacl-add-ca "Engineers use Puppet CA" --cas=puppet
  ipa caacl-add-user "Engineers use Puppet CA" --groups=engineers
  ipa caacl-add-profile "Engineers use Puppet CA" --certprofiles=caIPAserviceCert

Verify user/host is member of group/hostgroup in CA ACL

3. Cannot Delete Sub-CA - Still Enabled

Symptom: ca-del command fails with “CA must be disabled” error.

Diagnosis:

# Check CA status
ipa ca-show puppet | grep Enabled

# Should show: Enabled: TRUE

Resolution:

Disable CA before deletion:

  ipa ca-disable puppet
  ipa ca-del puppet

Warning: Deletion revokes sub-CA certificate, invalidating all certificates it issued
Ensure all services migrated off sub-CA-issued certificates before deletion

4. Sub-CA Creation Hangs or Times Out

Symptom: ca-add command hangs for extended period or times out.

Diagnosis:

# Check Dogtag service status
systemctl status pki-tomcatd@pki-tomcat

# Check Dogtag logs
tail -100 /var/log/pki/pki-tomcat/ca/debug

# Check if CA role enabled
ipa server-role-find --role="CA server"

Resolution:

Ensure Dogtag service running: systemctl start pki-tomcatd@pki-tomcat
Check Dogtag logs for errors
Verify CA role installed on server: ipa-ca-install if not
Restart Dogtag if hung: systemctl restart pki-tomcatd@pki-tomcat
Retry CA creation after Dogtag stabilizes

5. Subject DN Already Exists Error

Symptom: Cannot create sub-CA; error indicates subject DN already in use.

Diagnosis:

# List all CAs and their subject DNs
ipa ca-find --all | grep -E "(CA name|Subject DN)"

# Check if subject DN matches existing CA

Resolution:

Subject DN must be unique across all CAs
Choose different subject DN:

  ipa ca-add puppet \
    --subject="CN=Puppet CA v2,O=EXAMPLE.COM"

Or delete existing CA with conflicting subject DN (if unused)

6. Certificates Issued by Sub-CA Fail Validation

Symptom: Clients reject certificates issued by sub-CA with chain validation errors.

Diagnosis:

# Check certificate chain
openssl x509 -in cert.pem -text -noout | grep Issuer

# Verify sub-CA certificate on client
openssl s_client -connect service.example.com:443 -showcerts

# Check if IPA CA certificate trusted on client
trust list | grep "IPA CA"

Resolution:

Ensure IPA CA certificate installed on client
On IPA-enrolled clients, SSSD should install CA cert automatically
Manual installation:

  curl http://ipa.example.com/ipa/config/ca.crt -o /etc/pki/ca-trust/source/anchors/ipa-ca.crt
  update-ca-trust

Verify complete chain present in server certificate bundle

7. Sub-CA Shows as Enabled But Cannot Issue Certificates

Symptom: CA appears enabled in ca-show but certificate requests fail.

Diagnosis:

# Check CA status
ipa ca-show puppet --all

# Check Dogtag authority status directly
curl -u admin:password \
  https://ipa.example.com:8443/ca/rest/authorities | jq

# Check Dogtag logs
tail -f /var/log/pki/pki-tomcat/ca/debug

Resolution:

Sub-CA may be enabled in IPA but disabled in Dogtag backend
Check Dogtag authority status and enable if necessary
Restart Dogtag to synchronize state: systemctl restart pki-tomcatd@pki-tomcat
Re-enable CA in IPA: ipa ca-disable puppet && ipa ca-enable puppet

8. Cannot Find Sub-CA After Creation

Symptom: Created sub-CA but ca-find doesn’t show it.

Diagnosis:

# List all CAs
ipa ca-find

# Show specific CA by name
ipa ca-show puppet

# Check replication if multi-master
ipa-replica-manage list

Resolution:

Check CA name spelling (case-sensitive)
If multi-master deployment, wait for replication (30-60 seconds)
Verify CA created on current server vs different replica
Check replication status: ipa topologysuffix-verify domain

9. CA Modification Fails - Cannot Change Subject DN

Symptom: Attempting to change sub-CA subject DN with ca-mod fails.

Diagnosis:

# Attempt modification
ipa ca-mod puppet --subject="CN=New Subject,O=EXAMPLE.COM"

# Error: Subject DN cannot be modified

Resolution:

Subject DN cannot be changed after creation (embedded in certificate)
To change subject DN, must delete and recreate CA:

  # Disable and delete old CA
  ipa ca-disable puppet
  ipa ca-del puppet

  # Create new CA with desired subject DN
  ipa ca-add puppet --subject="CN=New Subject,O=EXAMPLE.COM"

Warning: Deletion invalidates all certificates issued by old CA
Replace all existing certificates after recreating CA

10. Root CA Certificate Expired or Expiring Soon

Symptom: Root CA certificate approaching expiration; all certificates will become invalid.

Diagnosis:

# Check root CA certificate expiration
ipa ca-show ipa --all | grep -i "not after"

# Or check certificate file directly
openssl x509 -in /etc/ipa/ca.crt -noout -enddate

Resolution:

Root CA certificate renewal is complex and disruptive
Before expiration:
- Plan renewal well in advance (6-12 months)
- Contact Red Hat support for guidance (if using RHEL)
- May require ipa-cacert-manage renew with external CA
If using self-signed root CA: Renewal requires reissuing all certificates
Test renewal procedure in non-production environment first

11. Dogtag REST API Errors During CA Operations

Symptom: CA operations fail with Dogtag REST API errors in IPA logs.

Diagnosis:

# Check IPA logs
journalctl -u ipa -n 100 | grep -i dogtag

# Check Dogtag logs
tail -100 /var/log/pki/pki-tomcat/ca/debug
tail -100 /var/log/pki/pki-tomcat/ca/system

# Verify Dogtag service running
systemctl status pki-tomcatd@pki-tomcat

Resolution:

Restart Dogtag service: systemctl restart pki-tomcatd@pki-tomcat
Check Dogtag database connectivity (LDAP backend)
Verify IPA framework can authenticate to Dogtag (check RA agent cert)
Review Dogtag logs for specific error details
May require database recovery if corruption detected

12. Sub-CA Replication Inconsistency Across Replicas

Symptom: Sub-CA exists on one IPA server but not others.

Diagnosis:

# On each IPA server, list CAs
ssh ipa01.example.com ipa ca-find
ssh ipa02.example.com ipa ca-find

# Check LDAP replication
ipa-replica-manage list

# Check Dogtag replication (CA servers only)

Resolution:

LDAP replication issue: Fix LDAP replication first

  ipa topologysuffix-verify domain
  ipa-replica-manage force-sync --from=ipa01.example.com

Dogtag replication issue: Ensure all CA servers have CA role

  ipa server-role-find --role="CA server"

Restart Dogtag on affected servers
In severe cases, may need to reinitialize Dogtag clone

13. Cannot Enable/Disable Root CA

Symptom: Attempting to disable “ipa” root CA fails.

Diagnosis:

# Attempt to disable root CA
ipa ca-disable ipa

# Error: Cannot disable root CA

Resolution:

Root CA cannot be disabled by design (system dependency)
All IPA functionality requires root CA operational
To stop all certificate issuance, would need to stop Dogtag entirely
Not recommended; breaks IPA functionality
For emergency certificate issuance stop, disable specific sub-CAs instead

14. CA ACL Changes Not Taking Effect

Symptom: Modified CA ACL but users still cannot request certificates.

Diagnosis:

# Verify CA ACL modification
ipa caacl-show "CA ACL Name" --all

# Check if CA ACL enabled
ipa caacl-show "CA ACL Name" | grep Enabled

# Wait for replication if multi-master

Resolution:

Ensure CA ACL is enabled (not disabled)

  ipa caacl-enable "CA ACL Name"

Verify all required components present in CA ACL:
- CA (—cas)
- User/group/host/service (—users, —groups, etc.)
- Certificate profile (—certprofiles)
Wait 30-60 seconds for replication across servers
Test certificate request again

15. Sub-CA Certificate Renewal Failure

Symptom: Sub-CA signing certificate approaching expiration; renewal fails.

Diagnosis:

# Check sub-CA certificate expiration
ipa ca-show puppet --all | grep -i "certificate"

# Check if renewal was attempted
grep -i renewal /var/log/pki/pki-tomcat/ca/debug

Resolution:

Sub-CA certificate renewal requires root CA operational
Ensure root CA certificate not expired
Renew sub-CA certificate manually via Dogtag if automatic renewal failed:

  # Contact Red Hat support for manual sub-CA renewal procedure
  # Requires Dogtag expertise and may involve backend operations

Plan sub-CA certificate renewals 1+ year before expiration
Monitor Dogtag renewal agent logs for renewal failures

Commands

ca-add

Usage: ipa [global-options] ca-add NAME [options]

Create a CA.

Arguments

Argument	Required	Description
`NAME`	yes	Name for referencing the CA

Options

Option	Description
`--desc DESC`	Description of the purpose of the CA
`--subject SUBJECT`	Subject Distinguished Name
`--setattr SETATTR`	Set an attribute to a name/value pair. Format is attr=value.
`--addattr ADDATTR`	Add an attribute/value pair. Format is attr=value. The attribute
`--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.

ca-del

Usage: ipa [global-options] ca-del NAME [options]

Delete a CA (must be disabled first).

Arguments

Argument	Required	Description
`NAME`	yes	Name for referencing the CA

Options

Option	Description
`--continue`	Continuous mode: Don’t stop on errors.

ca-disable

Usage: ipa [global-options] ca-disable NAME [options]

Disable a CA.

Arguments

Argument	Required	Description
`NAME`	yes	Name for referencing the CA

ca-enable

Usage: ipa [global-options] ca-enable NAME [options]

Enable a CA.

Arguments

Argument	Required	Description
`NAME`	yes	Name for referencing the CA

ca-find

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

Search for CAs.

Arguments

Argument Required Description

CRITERIA no A string searched in all relevant object attributes

Options

Option	Description
`--name NAME`	Name for referencing the CA
`--desc DESC`	Description of the purpose of the CA
`--id ID`	Dogtag Authority ID
`--subject SUBJECT`	Subject Distinguished Name
`--issuer ISSUER`	Issuer Distinguished Name
`--randomserialnumberversion RANDOMSERIALNUMBERVERSION`	Random Serial Number Version
`--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.
`--pkey-only`	Results should contain primary key attribute only (“name”)

ca-mod

Usage: ipa [global-options] ca-mod NAME [options]

Modify CA configuration.

Arguments

Argument	Required	Description
`NAME`	yes	Name for referencing the CA

Options

Option	Description
`--desc DESC`	Description of the purpose of the CA
`--setattr SETATTR`	Set an attribute to a name/value pair. Format is attr=value.
`--addattr ADDATTR`	Add an attribute/value pair. Format is attr=value. The attribute
`--delattr DELATTR`	Delete an attribute/value pair. The option will be evaluated
`--rights`	Display the access rights of this entry (requires —all). See ipa man page for details.
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.
`--rename RENAME`	Rename the Certificate Authority object

ca-show

Usage: ipa [global-options] ca-show NAME [options]

Display the properties of a CA.

Arguments

Argument	Required	Description
`NAME`	yes	Name for referencing the CA

Options

Option	Description
`--rights`	Display the access rights of this entry (requires —all). See ipa man page for details.
`--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.