1SSS-CERTMAP(5) File Formats and Conventions SSS-CERTMAP(5)
2
6 sss-certmap - SSSD Certificate Matching and Mapping Rules
7
9 The manual page describes the rules which can be used by SSSD and other
10 components to match X.509 certificates and map them to accounts.
11 Each rule has four components, a “priority”, a “matching rule”, a
13 “mapping rule” and a “domain list”. All components are optional. A
14 missing “priority” will add the rule with the lowest priority. The
15 default “matching rule” will match certificates with the
16 digitalSignature key usage and clientAuth extended key usage. If the
17 “mapping rule” is empty the certificates will be searched in the
18 userCertificate attribute as DER encoded binary. If no domains are
19 given only the local domain will be searched.
20
22 PRIORITY
23 The rules are processed by priority while the number '0' (zero)
24 indicates the highest priority. The higher the number the lower is the
25 priority. A missing value indicates the lowest priority. The rules
26 processing is stopped when a matched rule is found and no further rules
27 are checked.
28 Internally the priority is treated as unsigned 32bit integer, using a
30 priority value larger than 4294967295 will cause an error.
31 MATCHING RULE
33 The matching rule is used to select a certificate to which the mapping
34 rule should be applied. It uses a system similar to the one used by
35 “pkinit_cert_match” option of MIT Kerberos. It consists of a keyword
36 enclosed by '<' and '>' which identified a certain part of the
37 certificate and a pattern which should be found for the rule to match.
38 Multiple keyword pattern pairs can be either joined with '&&' (and) or
39 '||' (or).
40 The available options are:
42 <SUBJECT>regular-expression
44 With this a part or the whole subject name of the certificate can
45 be matched. For the matching POSIX Extended Regular Expression
46 syntax is used, see regex(7) for details.
47 For the matching the subject name stored in the certificate in DER
49 encoded ASN.1 is converted into a string according to RFC 4514.
50 This means the most specific name component comes first. Please
51 note that not all possible attribute names are covered by RFC 4514.
52 The names included are 'CN', 'L', 'ST', 'O', 'OU', 'C', 'STREET',
53 'DC' and 'UID'. Other attribute names might be shown differently on
54 different platform and by different tools. To avoid confusion those
55 attribute names are best not used or covered by a suitable
56 regular-expression.
57 Example: <SUBJECT>.*,DC=MY,DC=DOMAIN
59 Please note that the characters "^.[$()|*+?{\" have a special
61 meaning in regular expressions and must be escaped with the help of
62 the '\' character so that they are matched as ordinary characters.
63 Example: <SUBJECT>^CN=.* \(Admin\),DC=MY,DC=DOMAIN$
65 <ISSUER>regular-expression
67 With this a part or the whole issuer name of the certificate can be
68 matched. All comments for <SUBJECT> apply her as well.
69 Example: <ISSUER>^CN=My-CA,DC=MY,DC=DOMAIN$
71 <KU>key-usage
73 This option can be used to specify which key usage values the
74 certificate should have. The following values can be used in a
75 comma separated list:
76 · digitalSignature
78 · nonRepudiation
80 · keyEncipherment
82 · dataEncipherment
84 · keyAgreement
86 · keyCertSign
88 · cRLSign
90 · encipherOnly
92 · decipherOnly
94 A numerical value in the range of a 32bit unsigned integer can be
96 used as well to cover special use cases.
97 Example: <KU>digitalSignature,keyEncipherment
99 <EKU>extended-key-usage
101 This option can be used to specify which extended key usage the
102 certificate should have. The following value can be used in a comma
103 separated list:
104 · serverAuth
106 · clientAuth
108 · codeSigning
110 · emailProtection
112 · timeStamping
114 · OCSPSigning
116 · KPClientAuth
118 · pkinit
120 · msScLogin
122 Extended key usages which are not listed above can be specified
124 with their OID in dotted-decimal notation.
125 Example: <EKU>clientAuth,1.3.6.1.5.2.3.4
127 <SAN>regular-expression
129 To be compatible with the usage of MIT Kerberos this option will
130 match the Kerberos principals in the PKINIT or AD NT Principal SAN
131 as <SAN:Principal> does.
132 Example: <SAN>.*@MY\.REALM
134 <SAN:Principal>regular-expression
136 Match the Kerberos principals in the PKINIT or AD NT Principal SAN.
137 Example: <SAN:Principal>.*@MY\.REALM
139 <SAN:ntPrincipalName>regular-expression
141 Match the Kerberos principals from the AD NT Principal SAN.
142 Example: <SAN:ntPrincipalName>.*@MY.AD.REALM
144 <SAN:pkinit>regular-expression
146 Match the Kerberos principals from the PKINIT SAN.
147 Example: <SAN:ntPrincipalName>.*@MY\.PKINIT\.REALM
149 <SAN:dotted-decimal-oid>regular-expression
151 Take the value of the otherName SAN component given by the OID in
152 dotted-decimal notation, interpret it as string and try to match it
153 against the regular expression.
154 Example: <SAN:1.2.3.4>test
156 <SAN:otherName>base64-string
158 Do a binary match with the base64 encoded blob against all
159 otherName SAN components. With this option it is possible to match
160 against custom otherName components with special encodings which
161 could not be treated as strings.
162 Example: <SAN:otherName>MTIz
164 <SAN:rfc822Name>regular-expression
166 Match the value of the rfc822Name SAN.
167 Example: <SAN:rfc822Name>.*@email\.domain
169 <SAN:dNSName>regular-expression
171 Match the value of the dNSName SAN.
172 Example: <SAN:dNSName>.*\.my\.dns\.domain
174 <SAN:x400Address>base64-string
176 Binary match the value of the x400Address SAN.
177 Example: <SAN:x400Address>MTIz
179 <SAN:directoryName>regular-expression
181 Match the value of the directoryName SAN. The same comments as
182 given for <ISSUER> and <SUBJECT> apply here as well.
183 Example: <SAN:directoryName>.*,DC=com
185 <SAN:ediPartyName>base64-string
187 Binary match the value of the ediPartyName SAN.
188 Example: <SAN:ediPartyName>MTIz
190 <SAN:uniformResourceIdentifier>regular-expression
192 Match the value of the uniformResourceIdentifier SAN.
193 Example: <SAN:uniformResourceIdentifier>URN:.*
195 <SAN:iPAddress>regular-expression
197 Match the value of the iPAddress SAN.
198 Example: <SAN:iPAddress>192\.168\..*
200 <SAN:registeredID>regular-expression
202 Match the value of the registeredID SAN as dotted-decimal string.
203 Example: <SAN:registeredID>1\.2\.3\..*
205 MAPPING RULE
207 The mapping rule is used to associate a certificate with one or more
208 accounts. A Smartcard with the certificate and the matching private key
209 can then be used to authenticate as one of those accounts.
210 Currently SSSD basically only supports LDAP to lookup user information
212 (the exception is the proxy provider which is not of relevance here).
213 Because of this the mapping rule is based on LDAP search filter syntax
214 with templates to add certificate content to the filter. It is expected
215 that the filter will only contain the specific data needed for the
216 mapping and that the caller will embed it in another filter to do the
217 actual search. Because of this the filter string should start and stop
218 with '(' and ')' respectively.
219 In general it is recommended to use attributes from the certificate and
221 add them to special attributes to the LDAP user object. E.g. the
222 'altSecurityIdentities' attribute in AD or the 'ipaCertMapData'
223 attribute for IPA can be used.
224 This should be preferred to read user specific data from the
226 certificate like e.g. an email address and search for it in the LDAP
227 server. The reason is that the user specific data in LDAP might change
228 for various reasons would break the mapping. On the other hand it would
229 be hard to break the mapping on purpose for a specific user.
230 The templates to add certificate data to the search filter are based on
232 Python-style formatting strings. They consist of a keyword in curly
233 braces with an optional sub-component specifier separated by a '.' or
234 an optional conversion/formatting option separated by a '!'. Allowed
235 values are:
236 {issuer_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
238 This template will add the full issuer DN converted to a string
239 according to RFC 4514. If X.500 ordering (most specific RDN comes
240 last) an option with the '_x500' prefix should be used.
241 The conversion options starting with 'ad_' will use attribute names
243 as used by AD, e.g. 'S' instead of 'ST'.
244 The conversion options starting with 'nss_' will use attribute
246 names as used by NSS.
247 The default conversion option is 'nss', i.e. attribute names
249 according to NSS and LDAP/RFC 4514 ordering.
250 Example: (ipacertmapdata=X509:<I>{issuer_dn!ad}<S>{subject_dn!ad})
252 {subject_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
254 This template will add the full subject DN converted to string
255 according to RFC 4514. If X.500 ordering (most specific RDN comes
256 last) an option with the '_x500' prefix should be used.
257 The conversion options starting with 'ad_' will use attribute names
259 as used by AD, e.g. 'S' instead of 'ST'.
260 The conversion options starting with 'nss_' will use attribute
262 names as used by NSS.
263 The default conversion option is 'nss', i.e. attribute names
265 according to NSS and LDAP/RFC 4514 ordering.
266 Example:
268 (ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})
269 {cert[!(bin|base64)]}
271 This template will add the whole DER encoded certificate as a
272 string to the search filter. Depending on the conversion option the
273 binary certificate is either converted to an escaped hex sequence
274 '\xx' or base64. The escaped hex sequence is the default and can
275 e.g. be used with the LDAP attribute 'userCertificate;binary'.
276 Example: (userCertificate;binary={cert!bin})
278 {subject_principal[.short_name]}
280 This template will add the Kerberos principal which is taken either
281 from the SAN used by pkinit or the one used by AD. The 'short_name'
282 component represents the first part of the principal before the '@'
283 sign.
284 Example:
286 (|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name}))
287 {subject_pkinit_principal[.short_name]}
289 This template will add the Kerberos principal which is given by the
290 SAN used by pkinit. The 'short_name' component represents the first
291 part of the principal before the '@' sign.
292 Example:
294 (|(userPrincipal={subject_pkinit_principal})(uid={subject_pkinit_principal.short_name}))
295 {subject_nt_principal[.short_name]}
297 This template will add the Kerberos principal which is given by the
298 SAN used by AD. The 'short_name' component represent the first part
299 of the principal before the '@' sign.
300 Example:
302 (|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name}))
303 {subject_rfc822_name[.short_name]}
305 This template will add the string which is stored in the rfc822Name
306 component of the SAN, typically an email address. The 'short_name'
307 component represents the first part of the address before the '@'
308 sign.
309 Example:
311 (|(mail={subject_rfc822_name})(uid={subject_rfc822_name.short_name}))
312 {subject_dns_name[.short_name]}
314 This template will add the string which is stored in the dNSName
315 component of the SAN, typically a fully-qualified host name. The
316 'short_name' component represents the first part of the name before
317 the first '.' sign.
318 Example:
320 (|(fqdn={subject_dns_name})(host={subject_dns_name.short_name}))
321 {subject_uri}
323 This template will add the string which is stored in the
324 uniformResourceIdentifier component of the SAN.
325 Example: (uri={subject_uri})
327 {subject_ip_address}
329 This template will add the string which is stored in the iPAddress
330 component of the SAN.
331 Example: (ip={subject_ip_address})
333 {subject_x400_address}
335 This template will add the value which is stored in the x400Address
336 component of the SAN as escaped hex sequence.
337 Example: (attr:binary={subject_x400_address})
339 {subject_directory_name[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
341 This template will add the DN string of the value which is stored
342 in the directoryName component of the SAN.
343 Example: (orig_dn={subject_directory_name})
345 {subject_ediparty_name}
347 This template will add the value which is stored in the
348 ediPartyName component of the SAN as escaped hex sequence.
349 Example: (attr:binary={subject_ediparty_name})
351 {subject_registered_id}
353 This template will add the OID which is stored in the registeredID
354 component of the SAN as a dotted-decimal string.
355 Example: (oid={subject_registered_id})
357 DOMAIN LIST
359 If the domain list is not empty users mapped to a given certificate are
360 not only searched in the local domain but in the listed domains as well
361 as long as they are know by SSSD. Domains not know to SSSD will be
362 ignored.
363
365 The SSSD upstream - https://pagure.io/SSSD/sssd/
366SSSD 02/26/2020 SSS-CERTMAP(5)