SSS-CERTMAP(5)

📦
version 2.13.1 · 20 versions
, in arch rolling

🌸 sss-certmap(5) — SSSD Certificate Matching and Mapping Rules 🌸

✨ NAME ✨

sss-certmap(5) — SSSD Certificate Matching and Mapping Rules. Yep, section 5, File Formats and Conventions, bestie. 💅

💖 DESCRIPTION 💖

Okay so this page is the whole vibe check for the rules that SSSD and other components use to match X.509 certificates and map them to accounts. 🦋

Every rule has four components: a “priority”, a “matching rule”, a “mapping rule”, and a “domain list”. All of them are optional, which is giving choose-your-own-adventure. A missing “priority” will add the rule with the lowest priority. The default “matching rule” will match certificates with the digitalSignature key usage and clientAuth extended key usage. If the “mapping rule” is empty, the certificates will be searched in the userCertificate attribute as DER encoded binary. If no domains are given, only the local domain will be searched. ✨

To allow extensions or a completely different style of rule, the “mapping” and “matching rules” can contain a prefix separated with a : from the main part of the rule. That prefix may only contain upper-case ASCII letters and numbers. If the prefix is omitted, the default type will be used: KRB5 for the matching rules and LDAP for the mapping rules. 👑

The sssctl utility provides the cert-eval-rule command to check if a given certificate matches a matching rule and how the output of a mapping rule would look like. Iconic little debugging bestie, fr fr. 🔥

🧩 RULE COMPONENTS 🧩

👑 PRIORITY 👑

Rules are processed by priority, and the number 0 (zero) means the highest priority. The higher the number, the lower the priority. A missing value means the lowest priority. Processing stops when a matched rule is found, and no further rules are checked. 🛑

Internally, priority is treated as an unsigned 32bit integer. Using a priority value larger than 4294967295 will cause an error. Do not test that limit for fun, bestie. 💀

If multiple rules have the same priority and only one of the related matching rules applies, that rule will be chosen. If there are multiple rules with the same priority that match, one is chosen, but which one is undefined. That’s undefined behavior — lowkey cursed — so either use different priorities or make the matching rules more specific, e.g. by using distinct <ISSUER> patterns. 🙈

🎯 MATCHING RULE 🎯

The matching rule is used to select a certificate to which the mapping rule should be applied. It uses a system similar to the one used by the pkinit_cert_match option of MIT Kerberos. It consists of a keyword enclosed by < and > which identifies a certain part of the certificate, plus a pattern that should be found for the rule to match. Multiple keyword pattern pairs can be joined with && (and) or || (or). 🎀

Given the similarity to MIT Kerberos, the type prefix for this rule is KRB5. But KRB5 will also be the default for “matching rules”, so <SUBJECT>.*,DC=MY,DC=DOMAIN and KRB5:<SUBJECT>.*,DC=MY,DC=DOMAIN are equivalent. Slay, consistency. ✨

The available options are:

  • <SUBJECT>regular-expression — With this, a part or the whole subject name of the certificate can be matched. For the matching, POSIX Extended Regular Expression syntax is used; see regex(7) for details. 🔍

For the matching, the subject name stored in the certificate in DER encoded ASN.1 is converted into a string according to RFC 4514. This means the most specific name component comes first. Please note that not all possible attribute names are covered by RFC 4514. The names included are 'CN', 'L', 'ST', 'O', 'OU', 'C', 'STREET', 'DC' and 'UID'. Other attribute names might be shown differently on different platform and by different tools. To avoid confusion, those attribute names are best not used or covered by a suitable regular-expression. 🧚

Example: <SUBJECT>.*,DC=MY,DC=DOMAIN

Please note that the characters "^.[$()|*+?{\" have a special meaning in regular expressions and must be escaped with the help of the '\' character so that they are matched as ordinary characters. ⚠️

Example: <SUBJECT>^CN=.* \(Admin\),DC=MY,DC=DOMAIN$

  • <ISSUER>regular-expression — With this, a part or the whole issuer name of the certificate can be matched. All comments for <SUBJECT> apply here as well. 💜

Example: <ISSUER>^CN=My-CA,DC=MY,DC=DOMAIN$

  • <KU>key-usage — This option can be used to specify which key usage values the certificate should have. The following values can be used in a comma separated list:
    • digitalSignature
    • nonRepudiation
    • keyEncipherment
    • dataEncipherment
    • keyAgreement
    • keyCertSign
    • cRLSign
    • encipherOnly
    • decipherOnly

A numerical value in the range of a 32bit unsigned integer can be used as well to cover special use cases. 🔢

Example: <KU>digitalSignature,keyEncipherment

  • <EKU>extended-key-usage — This option can be used to specify which extended key usage the certificate should have. The following value can be used in a comma separated list:
    • serverAuth
    • clientAuth
    • codeSigning
    • emailProtection
    • timeStamping
    • OCSPSigning
    • KPClientAuth
    • pkinit
    • msScLogin

Extended key usages which are not listed above can be specified with their OID in dotted-decimal notation. 🌈

Example: <EKU>clientAuth,1.3.6.1.5.2.3.4

  • <SAN>regular-expression — To be compatible with the usage of MIT Kerberos, this option will match the Kerberos principals in the PKINIT or AD NT Principal SAN as <SAN:Principal> does. 🦋

Example: <SAN>.*@MY\.REALM

  • <SAN:Principal>regular-expression — Match the Kerberos principals in the PKINIT or AD NT Principal SAN. 👑

Example: <SAN:Principal>.*@MY\.REALM

  • <SAN:ntPrincipalName>regular-expression — Match the Kerberos principals from the AD NT Principal SAN. 💫

Example: <SAN:ntPrincipalName>.*@MY.AD.REALM

  • <SAN:pkinit>regular-expression — Match the Kerberos principals from the PKINIT SAN. 🌟

Example: <SAN:ntPrincipalName>.*@MY\.PKINIT\.REALM

  • <SAN:dotted-decimal-oid>regular-expression — Take the value of the otherName SAN component given by the OID in dotted-decimal notation, interpret it as string, and try to match it against the regular expression. 🔍

Example: <SAN:1.2.3.4>test

  • <SAN:otherName>base64-string — Do a binary match with the base64 encoded blob against all otherName SAN components. With this option it is possible to match against custom otherName components with special encodings which could not be treated as strings. 🧬

Example: <SAN:otherName>MTIz

  • <SAN:rfc822Name>regular-expression — Match the value of the rfc822Name SAN. 📧

Example: <SAN:rfc822Name>.*@email\.domain

  • <SAN:dNSName>regular-expression — Match the value of the dNSName SAN. 🌐

Example: <SAN:dNSName>.*\.my\.dns\.domain

  • <SAN:x400Address>base64-string — Binary match the value of the x400Address SAN. 📦

Example: <SAN:x400Address>MTIz

  • <SAN:directoryName>regular-expression — Match the value of the directoryName SAN. The same comments as given for <ISSUER> and <SUBJECT> apply here as well. 🗂️

Example: <SAN:directoryName>.*,DC=com

  • <SAN:ediPartyName>base64-string — Binary match the value of the ediPartyName SAN. 🧾

Example: <SAN:ediPartyName>MTIz

  • <SAN:uniformResourceIdentifier>regular-expression — Match the value of the uniformResourceIdentifier SAN. 🔗

Example: <SAN:uniformResourceIdentifier>URN:.*

  • <SAN:iPAddress>regular-expression — Match the value of the iPAddress SAN. 🖥️

Example: <SAN:iPAddress>192\.168\..*

  • <SAN:registeredID>regular-expression — Match the value of the registeredID SAN as dotted-decimal string. 🪪

Example: <SAN:registeredID>1\.2\.3\..*

🗺️ MAPPING RULE 🗺️

The mapping rule is used to associate a certificate with one or more accounts. A Smartcard with the certificate and the matching private key can then be used to authenticate as one of those accounts. 💳✨

Currently SSSD basically only supports LDAP to lookup user information (the exception is the proxy provider, which is not of relevance here). Because of this, the mapping rule is based on LDAP search filter syntax with templates to add certificate content to the filter. It is expected that the filter will only contain the specific data needed for the mapping and that the caller will embed it in another filter to do the actual search. Because of this, the filter string should start and stop with '(' and ')' respectively. 🫶

In general it is recommended to use attributes from the certificate and add them to special attributes to the LDAP user object. E.g. the altSecurityIdentities attribute in AD or the ipaCertMapData attribute for IPA can be used. 🏆

This should be preferred to read user specific data from the certificate like e.g. an email address and search for it in the LDAP server. The reason is that the user specific data in LDAP might change for various reasons and would break the mapping. On the other hand, it would be hard to break the mapping on purpose for a specific user. 😭

The default “mapping rule” type is LDAP, which can be added as a prefix to a rule like e.g. LDAP:(userCertificate;binary={cert!bin}). There is an extension called LDAPU1 which offers more templates for more flexibility. To allow older versions of this library to ignore the extension, the prefix LDAPU1 must be used when using the new templates in a “mapping rule”; otherwise the old version of this library will fail with a parsing error. The new templates are described in the section called “LDAPU1 extension”. 🚨

The templates to add certificate data to the search filter are based on Python-style formatting strings. They consist of a keyword in curly braces with an optional sub-component specifier separated by a . or an optional conversion/formatting option separated by a !. Allowed values are: 🐍

  • {issuer_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]} — This template will add the full issuer DN converted to a string according to RFC 4514. If X.500 ordering (most specific RDN comes last) an option with the _x500 prefix should be used. 🗺️

The conversion options starting with ad_ will use attribute names as used by AD, e.g. 'S' instead of 'ST'.

The conversion options starting with nss_ will use attribute names as used by NSS.

The default conversion option is nss, i.e. attribute names according to NSS and LDAP/RFC 4514 ordering.

Example: (ipacertmapdata=X509:<I>{issuer_dn!ad}<S>{subject_dn!ad})

  • {subject_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]} — this one drops in the whole subject DN, converted to a string the RFC 4514 way ✨. If you want X.500 ordering (where the most specific RDN comes last), use the _x500 prefix option, kthx.

The ad_ conversion options use attribute names the way AD does — so S instead of ST, iconic honestly.

The nss_ conversion options use attribute names the way NSS does.

The default conversion option is nss, meaning NSS attribute names plus LDAP/RFC 4514 ordering. No cap, that's just the default.

Example:

(ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})
  • {cert[!(bin|base64)]} — this template yeets the entire DER-encoded certificate, as a string, into the search filter 💅. Depending on the conversion option, the binary cert gets turned into either an escaped hex sequence '\xx' or base64. The escaped hex sequence is the default and can be used with the LDAP attribute userCertificate;binary, for example.

Example: (userCertificate;binary={cert!bin})

  • {subject_principal[.short_name]} — adds the Kerberos principal, taken from either the SAN used by pkinit or the one AD uses 🎀. The short_name component is literally the first part of the principal before the @ sign.

Example:

(|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name}))
  • {subject_pkinit_principal[.short_name]} — adds the Kerberos principal given by the SAN used by pkinit. The short_name component is the first part of the principal before the @ sign.

Example:

(|(userPrincipal={subject_pkinit_principal})(uid={subject_pkinit_principal.short_name}))
  • {subject_nt_principal[.short_name]} — adds the Kerberos principal given by the SAN used by AD. The short_name component represents the first part of the principal before the @ sign.

Example:

(|(userPrincipalName={subject_nt_principal})(samAccountName={subject_nt_principal.short_name}))
  • {subject_rfc822_name[.short_name]} — adds the string stored in the rfc822Name component of the SAN — typically an email address 📧. The short_name component is the first part of the address before the @ sign.

Example:

(|(mail={subject_rfc822_name})(uid={subject_rfc822_name.short_name}))
  • {subject_dns_name[.short_name]} — adds the string stored in the dNSName component of the SAN, typically a fully-qualified host name 🌐. The short_name component is the first part of the name before the first . sign.

Example:

(|(fqdn={subject_dns_name})(host={subject_dns_name.short_name}))
  • {subject_uri} — adds the string stored in the uniformResourceIdentifier component of the SAN.

Example: (uri={subject_uri})

  • {subject_ip_address} — adds the string stored in the iPAddress component of the SAN.

Example: (ip={subject_ip_address})

  • {subject_x400_address} — adds the value stored in the x400Address component of the SAN, as an escaped hex sequence.

Example: (attr:binary={subject_x400_address})

  • {subject_directory_name[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]} — adds the DN string of the value stored in the directoryName component of the SAN.

Example: (orig_dn={subject_directory_name})

  • {subject_ediparty_name} — adds the value stored in the ediPartyName component of the SAN as an escaped hex sequence.

Example: (attr:binary={subject_ediparty_name})

  • {subject_registered_id} — adds the OID stored in the registeredID component of the SAN, as a dotted-decimal string.

Example: (oid={subject_registered_id})

🦋 LDAPU1 extension 🦋

These following templates are available when you're using the LDAPU1 extension, bestie 💜:

  • {serial_number[!(dec|hex[_ucr])]} — adds the serial number of the certificate. By default it prints as a hexadecimal number with lower-case letters.

With the formatting option !dec the number prints as a decimal string. The hexadecimal output can be printed with upper-case letters (!hex_u), with a colon separating the hexadecimal bytes (!hex_c), or with the hexadecimal bytes in reverse order (!hex_r). The postfix letters can be combined, so like, !hex_uc gives you a colon-separated hexadecimal string with upper-case letters ✨.

Example: LDAPU1:(serial={serial_number})

  • {subject_key_id[!hex[_ucr]]} — adds the subject key id of the certificate. By default it prints as a hexadecimal number with lower-case letters.

The hexadecimal output can be printed with upper-case letters (!hex_u), with a colon separating the hexadecimal bytes (!hex_c), or with the hexadecimal bytes in reverse order (!hex_r). Postfix letters combine, so !hex_uc produces a colon-separated hexadecimal string with upper-case letters 💅.

Example: LDAPU1:(ski={subject_key_id})

  • {cert[!DIGEST[_ucr]]} — adds the hexadecimal digest/hash of the certificate, where DIGEST must be replaced with the name of a digest/hash function supported by OpenSSL, e.g. sha512 🔥.

The hexadecimal output can be printed with upper-case letters (!sha512_u), with a colon separating the hexadecimal bytes (!sha512_c), or with the hexadecimal bytes in reverse order (!sha512_r). Postfix letters combine, so !sha512_uc gives a colon-separated hexadecimal string with upper-case letters.

Example: LDAPU1:(dgst={cert!sha256})

  • {subject_dn_component[(.attr_name|[number]]} — adds an attribute value of a component of the subject DN; by default it's the value of the most specific component 🎯.

A different component can be picked by attribute name, e.g. {subject_dn_component.uid}, or by position, e.g. {subject_dn_component.[2]} — where positive numbers start counting from the most specific component and negative numbers start counting from the least specific component. Attribute name and position can be combined, e.g. {subject_dn_component.uid[2]}, which means the name of the second component must be uid.

Example: LDAPU1:(uid={subject_dn_component.uid})

  • {issuer_dn_component[(.attr_name|[number]]} — adds an attribute value of a component of the issuer DN; by default the value of the most specific component.

Peep subject_dn_component for the details on the attribute name and position specifiers, k?

Example:

LDAPU1:(domain={issuer_dn_component.[-2]}.{issuer_dn_component.dc[-1]})
  • {sid[.rid]} — adds the SID if the corresponding extension that Microsoft introduced with the OID 1.3.6.1.4.1.311.25.2 is available 👑. With the .rid selector, only the last component — i.e. the RID — gets added.

Example: LDAPU1:(objectsid={sid})

🌈 DOMAIN LIST 🌈

Okay so if the domain list is not empty, users mapped to a given certificate get searched not just in the local domain but in the listed domains too — as long as SSSD knows about them 🫶. Domains SSSD doesn't know about? Ignored. Bye 💀.

💖 AUTHORS 💖

The SSSD upstream — https://github.com/SSSD/sssd/ ✨

And that's the whole vibe check, bestie — page straight out of SSSD, dated 06/09/2026 🎀 go forth and certmap slay 💅

📦 where this page comes from