Certificate Mapping

Manage Certificate Identity Mapping configuration and rules.

Certificate mapping enables certificate-based authentication without storing full X.509 certificates in user entries. Instead of embedding certificates in LDAP (usercertificate attribute), mapping rules define how certificate attributes identify users, providing flexible smart card and PKI authentication with reduced storage overhead and simplified certificate lifecycle management.

Certificate mapping rules use two complementary components: match rules determine if a certificate is acceptable for authentication, while map rules define how to locate the user entry for an acceptable certificate. This two-stage architecture provides security policy enforcement (what certificates are trusted) and flexible user resolution (how certificates identify users).

Overview

Certificate Authentication Methods

FreeIPA supports two methods for certificate-based authentication:

Full certificate storage (traditional):

Certificate stored in usercertificate attribute (multi-valued)
LDAP search: (usercertificate=<full-cert-binary>)
Simple and deterministic
Storage overhead: ~2KB per certificate
Certificate renewal requires LDAP modification
Tight coupling between certificate lifecycle and user entry

Certificate mapping (rules-based):

No certificate storage in LDAP
Rules extract certificate attributes (subject, issuer, SAN, etc.)
LDAP search constructed from extracted attributes
Flexible user resolution based on certificate fields
Zero storage overhead
Certificate renewal transparent if attributes unchanged
Decouples certificate lifecycle from user entry

When to use mapping: Smart card deployments, external PKI, frequent certificate renewal, certificates issued by trusted CAs where full storage is impractical.

When to use full storage: Self-service certificate requests, certificates issued by FreeIPA CA, tight certificate lifecycle control, compliance requirements for certificate archival.

Architecture

Certificate Presentation          Mapping Rules Evaluation           User Resolution
─────────────────────            ────────────────────────           ───────────────

Smart card inserted              Priority-ordered rule list          LDAP search
  ↓                                ↓                                   ↓
X.509 certificate extracted      Match Rule 1: Issuer check        uid=alice,...
  Subject: CN=Alice              ✓ Matches (issuer trusted)          ↓
  Issuer: CN=Corp CA               ↓                                Authentication
  SAN: alice@example.com         Map Rule 1: Extract SAN           succeeds
  Serial: 0x1234                   <SAN:rfc822Name>
  ↓                                ↓
SSSD reads cert                  Construct LDAP filter:
  ↓                              (mail=alice@example.com)
Query IPA for mapping              ↓
rules (certmap-match)            SSSD searches LDAP
                                   ↓
                                 User alice found

Evaluation flow:

Certificate extraction: SSSD reads certificate from smart card or file
Rule retrieval: SSSD fetches enabled mapping rules from IPA, sorted by priority
Match evaluation: Rules evaluated in priority order; first matching rule wins
User search: Map rule constructs LDAP filter from certificate attributes
Disambiguation: If multiple users match, behavior depends on promptusername setting
Authentication: SSSD validates certificate signature, checks expiration, proceeds with auth

Mapping Rule Components

Each certificate mapping rule contains:

Metadata:

rulename - Unique identifier
description - Administrative documentation
priority - Evaluation order (lower number = higher priority, default 50000)
enabled - Active state (enabled/disabled)
domain - Target domain for user search (optional, defaults to IPA domain)

Match rule (matchrule):

Boolean expression evaluating certificate attributes
Determines if certificate is acceptable for this mapping
Syntax: SSSD certmap matching language (see sss-certmap man page)
Optional: If omitted, all certificates match

Map rule (maprule):

Template for constructing LDAP search filter
Extracts certificate attributes and builds user query
Syntax: SSSD certmap mapping language (see sss-certmap man page)
Required: Must specify how to find user

Match Rule Syntax

Match rules use boolean expressions with certificate attribute extractors:

Available extractors:

<ISSUER> - Certificate issuer DN
<SUBJECT> - Certificate subject DN
<KU> - Key usage extension
<EKU> - Extended key usage extension
<SAN> - Subject alternative name (all types)
<SAN:rfc822Name> - Email address from SAN
<SAN:dNSName> - DNS name from SAN
<SAN:x400Address> - X.400 address from SAN
<SAN:directoryName> - Directory name from SAN
<SAN:ediPartyName> - EDI party name from SAN
<SAN:uniformResourceIdentifier> - URI from SAN
<SAN:iPAddress> - IP address from SAN
<SAN:registeredID> - Registered OID from SAN

Boolean operators:

&& - Logical AND
|| - Logical OR
! - Logical NOT

Comparison operators (for DN components):

<ISSUER>:CN=Trusted CA - Issuer CN equals “Trusted CA”
<SUBJECT>:O=Example Corp - Subject organization equals “Example Corp”

Examples:

# Trust only certificates from specific issuer
<ISSUER>:CN=Corporate CA,O=Example Corp,C=US

# Require specific key usage (digital signature)
<KU>digitalSignature

# Require extended key usage for smart card logon
<EKU>1.3.6.1.4.1.311.20.2.2

# Trust multiple issuers
<ISSUER>:CN=Primary CA || <ISSUER>:CN=Backup CA

# Require issuer AND specific organization in subject
<ISSUER>:CN=Corp CA && <SUBJECT>:O=Example Corp

# Exclude specific SAN domains
!<SAN:rfc822Name>:.*@untrusted\.com

Map Rule Syntax

Map rules define LDAP search filters constructed from certificate attributes:

Template syntax:

<SUBJECT> - Full subject DN
<SUBJECT:CN> - Subject common name component
<SUBJECT:O> - Subject organization component
<SUBJECT:OU> - Subject organizational unit component
<SAN:rfc822Name> - Email from SAN
<SAN:dNSName> - DNS name from SAN
<SAN:x400Address> - X.400 address from SAN
(attr={val}) - LDAP filter template with attribute extraction

Special templates:

LDAPU1 - Traditional LDAP user mapping (subject/issuer)
AD - Active Directory altSecurityIdentities mapping
<ALT-SEC-ID-I-S:altSecurityIdentities> - AD issuer+serial mapping

Examples:

# Map using SAN email to mail attribute
(mail={<SAN:rfc822Name>})

# Map using subject CN to uid attribute
(uid={<SUBJECT:CN>})

# Map using Kerberos principal from SAN
(krbPrincipalName={<SAN:x400Address>})

# Combination: try multiple attributes
(|(mail={<SAN:rfc822Name>})(uid={<SUBJECT:CN>}))

# AD altSecurityIdentities mapping (issuer + serial)
<ALT-SEC-ID-I-S:altSecurityIdentities>

# Complex: extract OU for department-based search
(&(ou={<SUBJECT:OU>})(mail={<SAN:rfc822Name>}))

Priority and Rule Ordering

Certificate mapping rules are evaluated in priority order (lower number = higher priority):

Default priority: 50000

Evaluation algorithm:

Retrieve all enabled rules from IPA
Sort rules by priority (ascending: 10, 50, 100, …)
Evaluate match rules in order
First rule where match rule succeeds is used
Map rule from selected rule constructs LDAP filter
LDAP search executed

Priority strategies:

Specific before general (recommended):

# Priority 10: High-security certificates (narrow match)
ipa certmaprule-add high-security \
    --matchrule "<ISSUER>:CN=High-Security CA && <EKU>1.3.6.1.4.1.311.20.2.2" \
    --maprule "(employeeNumber={<SUBJECT:serialNumber>})" \
    --priority 10

# Priority 50: Standard employee certificates (medium match)
ipa certmaprule-add employee \
    --matchrule "<ISSUER>:CN=Employee CA" \
    --maprule "(mail={<SAN:rfc822Name>})" \
    --priority 50

# Priority 100: Any corporate certificate (broad match)
ipa certmaprule-add corporate \
    --matchrule "<ISSUER>:O=Example Corp" \
    --maprule "(uid={<SUBJECT:CN>})" \
    --priority 100

Domain-specific rules:

# Priority 20: AD trust user certificates
ipa certmaprule-add ad-users \
    --matchrule "<ISSUER>:CN=AD CA" \
    --maprule "<ALT-SEC-ID-I-S:altSecurityIdentities>" \
    --domain ad.example.com \
    --priority 20

# Priority 30: IPA user certificates
ipa certmaprule-add ipa-users \
    --matchrule "<ISSUER>:CN=IPA CA" \
    --maprule "(userCertificate;binary={cert!bin})" \
    --priority 30

Global Configuration

Certificate mapping global configuration (certmapconfig) controls system-wide behavior:

promptusername (boolean, default: FALSE):

FALSE: Fail authentication if multiple users match map rule
TRUE: Prompt for username to disambiguate multiple matches

Use cases:

promptusername=FALSE (strict mode, recommended for smart cards):

Security: Prevents ambiguous authentication
Certificate must uniquely identify exactly one user
Map rules must be carefully designed for uniqueness
Authentication fails if multiple users have same email/CN
Best for environments where certificates are personal devices

promptusername=TRUE (lenient mode, for shared certs):

Flexibility: Supports shared certificates or ambiguous mappings
User provides username, certificate validates identity
Less secure: Opens potential for social engineering
Useful during migration or for group certificates
Best for testing or environments with legacy certificate practices

SSSD Integration

SSSD performs certificate mapping on IPA clients:

Configuration (/etc/sssd/sssd.conf):

[domain/example.com]
id_provider = ipa
auth_provider = ipa
pam_cert_auth = True          # Enable certificate authentication
pam_cert_db_path = /etc/pki/nssdb  # Certificate database path

Client-side flow:

User inserts smart card or presents certificate
SSSD detects certificate via pcscd (smart card) or NSS database
SSSD queries IPA for certificate mapping rules
SSSD caches rules locally (respects entry_cache_timeout)
Match rules evaluated in priority order
First matching map rule constructs LDAP filter
SSSD searches IPA LDAP for user matching filter
If single user found, SSSD validates certificate and authenticates
If multiple users found, behavior depends on promptusername setting

Cache behavior:

Mapping rules cached for entry_cache_timeout (default: 5400 seconds)
Rule changes require cache expiration: sssctl cache-expire --everything
Offline mode uses last cached rules
Certificate validation (signature, expiration) performed even offline (if cert chain cached)

Testing certificate matching:

# Server-side matching test
ipa certmap-match "$(cat user-cert.pem)"

# Client-side debugging
sssctl cert-show
sssctl cert-eval-rule --rule="<ISSUER>:CN=Corp CA"

Cross-Realm Support

The --domain parameter enables certificate mapping across trust boundaries:

Use cases:

Map certificates to AD trust users
Map certificates to users in specific IPA realm (multi-realm topology)
Isolate mapping rules by domain

Example:

# Rule for AD domain certificates
ipa certmaprule-add ad-corp-mapping \
    --matchrule "<ISSUER>:CN=ADCORP-CA" \
    --maprule "<ALT-SEC-ID-I-S:altSecurityIdentities>" \
    --domain ad.example.com \
    --priority 20

# Rule for IPA domain certificates
ipa certmaprule-add ipa-corp-mapping \
    --matchrule "<ISSUER>:CN=IPA CA" \
    --maprule "(mail={<SAN:rfc822Name>})" \
    --domain ipa.example.com \
    --priority 30

Domain resolution:

If --domain specified, LDAP search restricted to that domain
If --domain omitted, search in local IPA domain
For AD trust users, use AD domain name (e.g., ad.example.com)
For local users, use IPA domain or omit

Use Cases

Smart Card Logon

Scenario: 500 employees with PIV smart cards issued by external CA.

Solution:

# Create mapping rule for PIV cards
ipa certmaprule-add piv-cards \
    --desc "PIV card authentication for employees" \
    --matchrule "<ISSUER>:CN=PIV CA,O=US Government && <EKU>1.3.6.1.4.1.311.20.2.2" \
    --maprule "(employeeNumber={<SUBJECT:serialNumber>})" \
    --priority 10

# Users can authenticate with smart card without storing certs in LDAP

Email-Based Mapping

Scenario: Certificates contain email in SAN, map to IPA mail attribute.

Solution:

ipa certmaprule-add email-mapping \
    --desc "Map certificates using email address" \
    --matchrule "<ISSUER>:O=Example Corp && <SAN:rfc822Name>:.*@example\\.com" \
    --maprule "(mail={<SAN:rfc822Name>})" \
    --priority 20

# Certificate with SAN:rfc822Name=alice@example.com maps to user with mail=alice@example.com

Active Directory Integration

Scenario: AD trust users authenticate with certificates issued by AD CA.

Solution:

ipa certmaprule-add ad-trust-certs \
    --desc "Map AD user certificates via altSecurityIdentities" \
    --matchrule "<ISSUER>:CN=ADCORP-CA" \
    --maprule "<ALT-SEC-ID-I-S:altSecurityIdentities>" \
    --domain ad.example.com \
    --priority 15

# AD users authenticate with certificates, mapped via altSecurityIdentities attribute

Multi-Issuer Environment

Scenario: Multiple trusted CAs for different user populations.

Solution:

# Priority 10: Executive certificates (highest assurance)
ipa certmaprule-add executive-certs \
    --matchrule "<ISSUER>:CN=Executive CA && <EKU>1.3.6.1.4.1.311.20.2.2" \
    --maprule "(employeeType=executive)(mail={<SAN:rfc822Name>})" \
    --priority 10

# Priority 30: Employee certificates (standard assurance)
ipa certmaprule-add employee-certs \
    --matchrule "<ISSUER>:CN=Employee CA" \
    --maprule "(mail={<SAN:rfc822Name>})" \
    --priority 30

# Priority 50: Contractor certificates (limited assurance)
ipa certmaprule-add contractor-certs \
    --matchrule "<ISSUER>:CN=Contractor CA" \
    --maprule "(employeeType=contractor)(mail={<SAN:rfc822Name>})" \
    --priority 50

VPN Certificate Mapping

Scenario: VPN concentrator validates certificates, map to users for authorization.

Solution:

ipa certmaprule-add vpn-access \
    --desc "VPN certificate mapping" \
    --matchrule "<ISSUER>:CN=VPN CA && <EKU>1.3.6.1.5.5.7.3.2" \
    --maprule "(uid={<SUBJECT:CN>})" \
    --priority 25

# VPN users authenticate with certificates, mapped to IPA users for HBAC evaluation

Fallback Mapping Strategy

Scenario: Prefer SAN email mapping, fall back to subject CN if email absent.

Solution:

# Priority 10: Map using SAN email (preferred, more specific)
ipa certmaprule-add email-primary \
    --matchrule "<ISSUER>:CN=Corp CA && <SAN:rfc822Name>:.*" \
    --maprule "(mail={<SAN:rfc822Name>})" \
    --priority 10

# Priority 50: Map using subject CN (fallback for certs without SAN)
ipa certmaprule-add subject-fallback \
    --matchrule "<ISSUER>:CN=Corp CA" \
    --maprule "(uid={<SUBJECT:CN>})" \
    --priority 50

# Certificates with SAN:rfc822Name use rule 1
# Certificates without SAN use rule 2

Examples

Global Configuration

Show current certificate mapping configuration:

ipa certmapconfig-show
ipa certmapconfig-show --all --raw

Enable username prompt for ambiguous mappings:

ipa certmapconfig-mod --promptusername=TRUE

Disable username prompt (strict mode):

ipa certmapconfig-mod --promptusername=FALSE

Creating Mapping Rules

Create basic mapping rule (map by email):

ipa certmaprule-add email-rule \
    --desc "Map certificates using SAN email address" \
    --maprule "(mail={<SAN:rfc822Name>})"

Create rule with match criteria (trust specific issuer):

ipa certmaprule-add corporate-rule \
    --desc "Corporate CA certificates only" \
    --matchrule "<ISSUER>:CN=Corporate CA,O=Example Corp,C=US" \
    --maprule "(mail={<SAN:rfc822Name>})" \
    --priority 20

Create rule with extended key usage requirement:

ipa certmaprule-add smart-card-logon \
    --desc "Smart card logon certificates" \
    --matchrule "<EKU>1.3.6.1.4.1.311.20.2.2" \
    --maprule "(employeeNumber={<SUBJECT:serialNumber>})" \
    --priority 10

Create rule mapping subject CN to uid:

ipa certmaprule-add cn-to-uid \
    --desc "Map subject CN to user ID" \
    --matchrule "<ISSUER>:O=Example Corp" \
    --maprule "(uid={<SUBJECT:CN>})" \
    --priority 30

Create rule for AD trust users:

ipa certmaprule-add ad-users \
    --desc "AD trust user certificate mapping" \
    --matchrule "<ISSUER>:CN=ADCORP-CA" \
    --maprule "<ALT-SEC-ID-I-S:altSecurityIdentities>" \
    --domain ad.example.com \
    --priority 15

Create rule with complex match criteria:

ipa certmaprule-add multi-issuer \
    --desc "Multiple trusted issuers" \
    --matchrule "(<ISSUER>:CN=Primary CA || <ISSUER>:CN=Backup CA) && <EKU>1.3.6.1.5.5.7.3.2" \
    --maprule "(mail={<SAN:rfc822Name>})" \
    --priority 25

Create rule with OR mapping (try multiple attributes):

ipa certmaprule-add flexible-mapping \
    --desc "Try email then username" \
    --matchrule "<ISSUER>:O=Example Corp" \
    --maprule "(|(mail={<SAN:rfc822Name>})(uid={<SUBJECT:CN>}))" \
    --priority 40

Create rule extracting organizational unit:

ipa certmaprule-add department-based \
    --desc "Map by department OU" \
    --matchrule "<ISSUER>:CN=Dept CA && <SUBJECT>:OU=.*" \
    --maprule "(&(ou={<SUBJECT:OU>})(mail={<SAN:rfc822Name>}))" \
    --priority 35

Managing Mapping Rules

List all certificate mapping rules:

ipa certmaprule-find
ipa certmaprule-find --all
ipa certmaprule-find --pkey-only  # Rule names only

Find rules by priority:

ipa certmaprule-find --priority 10
ipa certmaprule-find --all | grep -i priority

Find rules for specific domain:

ipa certmaprule-find --domain ad.example.com

Find rules by description:

ipa certmaprule-find --desc "smart card"

Show rule details:

ipa certmaprule-show email-rule
ipa certmaprule-show email-rule --all --raw

Modify rule description:

ipa certmaprule-mod email-rule \
    --desc "Updated description for email-based mapping"

Change rule priority:

ipa certmaprule-mod corporate-rule --priority 15

Update match rule:

ipa certmaprule-mod corporate-rule \
    --matchrule "<ISSUER>:CN=New Corporate CA"

Update map rule:

ipa certmaprule-mod email-rule \
    --maprule "(|(mail={<SAN:rfc822Name>})(uid={<SUBJECT:CN>}))"

Change rule domain:

ipa certmaprule-mod ad-users --domain ipa.example.com

Enabling and Disabling Rules

Disable a mapping rule (stops evaluation):

ipa certmaprule-disable email-rule

Enable a mapping rule:

ipa certmaprule-enable email-rule

Temporarily disable rule for testing:

# Disable production rule
ipa certmaprule-disable production-mapping

# Enable test rule
ipa certmaprule-enable test-mapping

# Test authentication

# Re-enable production rule
ipa certmaprule-enable production-mapping

# Disable test rule
ipa certmaprule-disable test-mapping

Deleting Mapping Rules

Delete a single mapping rule:

ipa certmaprule-del obsolete-rule

Delete multiple mapping rules:

ipa certmaprule-del old-rule1 old-rule2 old-rule3
ipa certmaprule-del old-rule1 old-rule2 --continue  # Continue on errors

Testing Certificate Matching

Test certificate matching (server-side):

# From PEM file
ipa certmap-match "$(cat user-cert.pem)"

# From base64-encoded certificate
ipa certmap-match "MIIEXzCCA0egAwIBAgIUfTx..."

# Verbose output
ipa certmap-match "$(cat user-cert.pem)" --all

Test matching returns matched users:

$ ipa certmap-match "$(cat alice-cert.pem)"
1 user matched
  User login: alice
Number of entries returned 1

Test matching with multiple matches (if promptusername=FALSE, auth would fail):

$ ipa certmap-match "$(cat shared-cert.pem)"
2 users matched
  User login: alice
  User login: bob
Number of entries returned 2

Client-side certificate evaluation (SSSD):

# Show certificates visible to SSSD
sssctl cert-show

# Evaluate specific match rule
sssctl cert-eval-rule --rule="<ISSUER>:CN=Corp CA"

Advanced Workflows

Progressive rule deployment:

# Week 1: Create disabled rule
ipa certmaprule-add new-mapping \
    --desc "New certificate mapping strategy" \
    --matchrule "<ISSUER>:CN=New CA" \
    --maprule "(mail={<SAN:rfc822Name>})" \
    --priority 20
# Rule created but disabled by default

# Week 2: Enable for testing
ipa certmaprule-enable new-mapping

# Test with pilot users
for user in alice bob charlie; do
    ipa certmap-match "$(cat ${user}-cert.pem)"
done

# Week 3: Validate in production
# (Rule already enabled, monitor authentication logs)

# Week 4: Disable old rule after validation
ipa certmaprule-disable old-mapping

Issuer migration:

# Old CA rule (priority 50, lower priority)
ipa certmaprule-mod old-ca-rule --priority 50

# New CA rule (priority 10, higher priority)
ipa certmaprule-add new-ca-rule \
    --matchrule "<ISSUER>:CN=New Corporate CA" \
    --maprule "(mail={<SAN:rfc822Name>})" \
    --priority 10

# New CA certs use new-ca-rule (priority 10)
# Old CA certs still work via old-ca-rule (priority 50)
# Gradual user certificate renewal

# After all certs renewed, delete old rule
ipa certmaprule-del old-ca-rule

Department-specific rules:

# Engineering: Map by employee number
ipa certmaprule-add engineering \
    --matchrule "<ISSUER>:CN=Eng CA && <SUBJECT>:OU=Engineering" \
    --maprule "(employeeNumber={<SUBJECT:serialNumber>})" \
    --priority 10

# HR: Map by email (more flexible for non-technical users)
ipa certmaprule-add hr \
    --matchrule "<ISSUER>:CN=Eng CA && <SUBJECT>:OU=HR" \
    --maprule "(mail={<SAN:rfc822Name>})" \
    --priority 11

# All others: Map by username
ipa certmaprule-add general \
    --matchrule "<ISSUER>:CN=Eng CA" \
    --maprule "(uid={<SUBJECT:CN>})" \
    --priority 50

Debugging mapping issues:

# 1. Test certificate matching
ipa certmap-match "$(cat problem-cert.pem)"

# 2. If no match, check enabled rules
ipa certmaprule-find --all

# 3. Check rule priorities
ipa certmaprule-find --all | grep -E "(Rule name|Priority)"

# 4. Verify match rule syntax
ipa certmaprule-show suspected-rule --all

# 5. Test on client
ssh client.example.com
sssctl cert-show
sssctl cache-expire --everything
systemctl restart sssd
tail -f /var/log/sssd/sssd_example.com.log

Best Practices

Rule Design

Use specific match rules: Narrow match criteria prevent unintended certificates from being accepted. Prefer <ISSUER>:CN=Specific CA over <ISSUER>:O=Org.

Map to unique attributes: Map rules should target attributes that uniquely identify users (email, employee number) rather than ambiguous attributes (department, title).

Test before deployment: Use certmap-match to validate rules with real certificates before enabling in production.

Document rule purpose: Use --desc to explain match criteria, map strategy, and intended user population.

Prefer higher priorities for specific rules: Assign low priority numbers (10-20) to narrow, specific rules and high numbers (50-100) to broad, general rules.

Priority Management

Leave gaps in priorities: Use priorities 10, 20, 30 instead of 1, 2, 3 to allow inserting rules between existing ones.

Group related rules: Assign priority ranges by category (10-19: executives, 20-29: employees, 30-39: contractors).

Default rule at low priority: If using a catch-all rule, assign it high priority number (90-100) so it’s evaluated last.

Review priority order periodically: As rules are added, ensure priority order still reflects intended evaluation sequence.

Global Configuration

Start with promptusername=FALSE: Strict mode encourages proper rule design and prevents ambiguous authentication.

Only enable promptusername for migrations: Lenient mode useful during certificate deployment but should be temporary.

Document promptusername setting: Note in operational documentation why setting was changed and when it should be reverted.

SSSD Integration

Clear cache after rule changes: Rule modifications don’t take effect on clients until cache expires or is manually cleared.

Monitor SSSD logs during deployment: Watch /var/log/sssd/sssd_example.com.log when deploying new rules to catch issues.

Test offline authentication: Ensure certificate validation works offline (requires cached certificate chain).

Coordinate with PAM configuration: Verify /etc/pam.d/ configuration enables certificate auth (pam_sss.so try_cert_auth).

Operational Practices

Version control rule definitions: Export rules to version control for disaster recovery and audit trail.

Staged deployment: Enable new rules on pilot systems first, expand gradually.

Monitor authentication logs: Track certificate authentication success/failure rates after rule changes.

Regular rule audit: Review rules quarterly to remove obsolete entries and optimize priorities.

Communicate rule changes: Inform affected users before changing rules that might impact their authentication.

Security Considerations

Match rules enforce security policy: Only trusted issuers and appropriate key usages should pass match rules. Overly permissive match rules undermine certificate security.

Map rule uniqueness prevents impersonation: Ambiguous map rules (mapping to non-unique attributes) allow attacker certificates to authenticate as legitimate users if match rule is bypassed.

Priority order affects security: Higher-priority weak rules can bypass lower-priority strong rules. Review priority order holistically.

promptusername=TRUE reduces security: Allowing username prompts enables authentication with any valid certificate from trusted issuer, relying on user knowledge rather than certificate uniqueness.

Cross-realm rules require trust validation: Mapping rules for AD trust users assume AD CA is trustworthy. Compromise of AD CA compromises IPA authentication.

SSSD cache can serve stale rules: Cached rules may not reflect recent revocations or policy changes. Balance cache timeout against security responsiveness.

Certificate validation occurs separately: Mapping rules identify users but don’t validate certificate signatures or expiration. SSSD performs validation; ensure SSSD has current CA certificates.

Rule visibility: Mapping rules are visible to all authenticated IPA users. Don’t encode sensitive information in rule descriptions.

Integration Points

SSSD: Client-side daemon retrieves mapping rules from IPA, evaluates certificates, constructs LDAP searches

Certmonger: Certificate lifecycle management tool; certificate renewal transparent to mapping if certificate attributes unchanged

PKINIT: Kerberos authentication via certificates; mapping rules apply to PKINIT authentication

Smart Card Daemons (pcscd): Interfaces with smart card hardware; SSSD retrieves certificates from cards via pcscd

PAM: Pluggable Authentication Modules; pam_sss.so module uses mapping rules for certificate-based login

Active Directory Trusts: AD altSecurityIdentities attribute enables mapping AD user certificates; requires trust relationship

LDAP: Map rules construct LDAP filters executed against IPA LDAP directory; ensure LDAP indices exist for mapped attributes

Web UI: SSSD certificate mapping supports web applications configured for certificate authentication via mod_lookup_identity

Troubleshooting

Certificate matching returns no users:

# Test matching
ipa certmap-match "$(cat cert.pem)"

# If no match, check enabled rules
ipa certmaprule-find

# Verify certificate issuer matches rule
openssl x509 -in cert.pem -noout -issuer
ipa certmaprule-show rule-name | grep "Match rule"

# Enable rule if disabled
ipa certmaprule-enable rule-name

Certificate matching returns multiple users:

# Check global config
ipa certmapconfig-show | grep promptusername

# If promptusername=FALSE, auth will fail with multiple matches
# Refine map rule to target unique attribute

# Identify conflicting users
ipa certmap-match "$(cat cert.pem)"

# Update map rule for uniqueness
ipa certmaprule-mod ambiguous-rule \
    --maprule "(employeeNumber={<SUBJECT:serialNumber>})"

Rule not taking effect on client:

# Clear SSSD cache
ssh client.example.com
sssctl cache-expire --everything
systemctl restart sssd

# Verify rule retrieval
sssctl cache-expire --everything
getent passwd username  # Triggers LDAP query and rule cache refresh

Match rule syntax errors:

# Validate match rule
ipa certmaprule-show rule-name | grep "Match rule"

# Common errors:
# - Missing quotes around regex: <SAN:rfc822Name>:.*@example.com (correct)
# - Wrong operator: & instead of && (use &&)
# - Unescaped dots in regex: @example.com instead of @example\.com

# Test corrected syntax
ipa certmaprule-mod rule-name \
    --matchrule "<ISSUER>:CN=CA && <SAN:rfc822Name>:.*@example\.com"

Map rule returns no LDAP results:

# Test LDAP filter manually
ldapsearch -x -h ipa.example.com -b cn=users,cn=accounts,dc=example,dc=com \
    "(mail=alice@example.com)"

# If no results, check:
# - Attribute exists in user entry
# - LDAP index exists for attribute
# - Certificate actually contains expected value

# View certificate attributes
openssl x509 -in cert.pem -noout -text | grep -A5 "Subject Alternative Name"

Priority order not respected:

# List rules with priorities
ipa certmaprule-find --all | grep -E "(Rule name|Priority)" | paste - -

# Verify lower number = higher priority
# If rule A (priority 10) should override rule B (priority 50), ensure match rule A is more specific

# Adjust priorities
ipa certmaprule-mod rule-a --priority 5
ipa certmaprule-mod rule-b --priority 60

AD trust certificate mapping fails:

# Verify domain parameter
ipa certmaprule-show ad-rule | grep Domain

# Should be AD domain name
ipa certmaprule-mod ad-rule --domain ad.example.com

# Verify AD trust is established
ipa trust-show ad.example.com

# Check altSecurityIdentities in AD
# (requires AD admin access)

SSSD certificate not detected:

# Check SSSD config
grep pam_cert_auth /etc/sssd/sssd.conf  # Should be True

# Verify certificate visibility
sssctl cert-show

# If empty, check smart card reader
pcsc_scan

# Check SSSD debug logs
sssctl debug-level 6
tail -f /var/log/sssd/sssd_example.com.log
# Insert smart card, check for certificate detection

Commands

certmap-match

Usage: ipa [global-options] certmap-match CERTIFICATE [options]

Search for users matching the provided certificate.

This command relies on SSSD to retrieve the list of matching users and
may return cached data. For more information on purging SSSD cache,
please refer to sss_cache documentation.

Arguments

Argument	Required	Description
`CERTIFICATE`	yes	Base-64 encoded user certificate

Options

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

certmapconfig-mod

Usage: ipa [global-options] certmapconfig-mod [options]

Modify Certificate Identity Mapping configuration.

Options

Option	Description
`--promptusername PROMPTUSERNAME`	Prompt for the username when multiple identities are mapped to a certificate
`--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.

certmapconfig-show

Usage: ipa [global-options] certmapconfig-show [options]

Show the current Certificate Identity Mapping configuration.

Options

Option	Description
`--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.

certmaprule-add

Usage: ipa [global-options] certmaprule-add RULENAME [options]

Create a new Certificate Identity Mapping Rule.

Arguments

Argument	Required	Description
`RULENAME`	yes	Certificate Identity Mapping Rule name

Options

Option	Description
`--desc DESC`	Certificate Identity Mapping Rule description
`--maprule MAPRULE`	Rule used to map the certificate with a user entry
`--matchrule MATCHRULE`	Rule used to check if a certificate can be used for authentication
`--domain DOMAIN`	Domain where the user entry will be searched
`--priority PRIORITY`	Priority of the rule (higher number means lower priority
`--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
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.

certmaprule-del

Usage: ipa [global-options] certmaprule-del RULENAME [options]

Delete a Certificate Identity Mapping Rule.

Arguments

Argument	Required	Description
`RULENAME`	yes	Certificate Identity Mapping Rule name

Options

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

certmaprule-disable

Usage: ipa [global-options] certmaprule-disable RULENAME [options]

Disable a Certificate Identity Mapping Rule.

Arguments

Argument	Required	Description
`RULENAME`	yes	Certificate Identity Mapping Rule name

certmaprule-enable

Usage: ipa [global-options] certmaprule-enable RULENAME [options]

Enable a Certificate Identity Mapping Rule.

Arguments

Argument	Required	Description
`RULENAME`	yes	Certificate Identity Mapping Rule name

certmaprule-find

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

Search for Certificate Identity Mapping Rules.

Arguments

Argument Required Description

CRITERIA no A string searched in all relevant object attributes

Options

Option	Description
`--rulename RULENAME`	Certificate Identity Mapping Rule name
`--desc DESC`	Certificate Identity Mapping Rule description
`--maprule MAPRULE`	Rule used to map the certificate with a user entry
`--matchrule MATCHRULE`	Rule used to check if a certificate can be used for authentication
`--domain DOMAIN`	Domain where the user entry will be searched
`--priority PRIORITY`	Priority of the rule (higher number means lower priority
`--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 (“rulename”)

certmaprule-mod

Usage: ipa [global-options] certmaprule-mod RULENAME [options]

Modify a Certificate Identity Mapping Rule.

Arguments

Argument	Required	Description
`RULENAME`	yes	Certificate Identity Mapping Rule name

Options

Option	Description
`--desc DESC`	Certificate Identity Mapping Rule description
`--maprule MAPRULE`	Rule used to map the certificate with a user entry
`--matchrule MATCHRULE`	Rule used to check if a certificate can be used for authentication
`--domain DOMAIN`	Domain where the user entry will be searched
`--priority PRIORITY`	Priority of the rule (higher number means lower priority
`--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.

certmaprule-show

Usage: ipa [global-options] certmaprule-show RULENAME [options]

Display information about a Certificate Identity Mapping Rule.

Arguments

Argument	Required	Description
`RULENAME`	yes	Certificate Identity Mapping Rule name

Options

Option	Description
`--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.

Overview

Certificate Authentication Methods

Architecture

Mapping Rule Components

Match Rule Syntax

Map Rule Syntax

Priority and Rule Ordering

Global Configuration

SSSD Integration

Cross-Realm Support

Use Cases

Smart Card Logon

Email-Based Mapping

Active Directory Integration

Multi-Issuer Environment

VPN Certificate Mapping

Fallback Mapping Strategy

Examples

Global Configuration

Creating Mapping Rules

Managing Mapping Rules

Enabling and Disabling Rules

Deleting Mapping Rules

Testing Certificate Matching

Advanced Workflows

Best Practices

Rule Design

Priority Management

Global Configuration

SSSD Integration

Operational Practices

Security Considerations

Integration Points

Troubleshooting

Commands

certmap-match

Arguments

Options

certmapconfig-mod

Options

certmapconfig-show

Options

certmaprule-add

Arguments

Options

certmaprule-del

Arguments

Options

certmaprule-disable

Arguments

certmaprule-enable

Arguments

certmaprule-find

Arguments

Options

certmaprule-mod

Arguments

Options

certmaprule-show

Arguments

Options

Related Topics