From 0c739e969a617bdb4c06cdfd63772bf6d283c518 Mon Sep 17 00:00:00 2001
From: Sumit Bose <sbose@redhat.com>
Date: Mon, 3 Sep 2018 18:38:42 +0200
Subject: [PATCH 31/83] doc: add certificate mapping section to man page
Related to https://pagure.io/SSSD/sssd/issue/3500
Reviewed-by: Jakub Hrozek <jhrozek@redhat.com>
---
src/man/sssd.conf.5.xml | 149 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 149 insertions(+)
diff --git a/src/man/sssd.conf.5.xml b/src/man/sssd.conf.5.xml
index 881ffc6..04143f1 100644
--- a/src/man/sssd.conf.5.xml
+++ b/src/man/sssd.conf.5.xml
@@ -3299,6 +3299,135 @@ ldap_user_extra_attrs = phone:telephoneNumber
</para>
</refsect1>
+ <refsect1 id='certmap'>
+ <title>CERTIFICATE MAPPING SECTION</title>
+ <para>
+ To allow authentication with Smartcards and certificates SSSD must
+ be able to map certificates to users. This can be done by adding the
+ full certificate to the LDAP object of the user or to a local
+ override. While using the full certificate is required to use the
+ Smartcard authentication feature of SSH (see
+ <citerefentry>
+ <refentrytitle>sss_ssh_authorizedkeys</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>
+ for details) it might be cumbersome or not even possible to do this
+ for the general case where local services use PAM for
+ authentication.
+ </para>
+ <para>
+ To make the mapping more flexible mapping and matching rules were
+ added to SSSD (see
+ <citerefentry>
+ <refentrytitle>sss-certmap</refentrytitle>
+ <manvolnum>5</manvolnum>
+ </citerefentry>
+ for details).
+ </para>
+ <para>
+ A mapping and matching rule can be added to the SSSD configuration
+ in a section on its own with a name like
+ <quote>[certmap/<replaceable>DOMAIN_NAME</replaceable>/<replaceable>RULE_NAME</replaceable>]</quote>.
+ In this section the following options are allowed:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>matchrule (string)</term>
+ <listitem>
+ <para>
+ Only certificates from the Smartcard which matches this
+ rule will be processed, all others are ignored.
+ </para>
+ <para>
+ Default: KRB5:<EKU>clientAuth, i.e. only
+ certificates which have the Extended Key Usage
+ <quote>clientAuth</quote>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>maprule (string)</term>
+ <listitem>
+ <para>
+ Defines how the user is found for a given certificate.
+ </para>
+ <para>
+ Default:
+ <itemizedlist>
+ <listitem>
+ <para>LDAP:(userCertificate;binary={cert!bin})
+ for LDAP based providers like
+ <quote>ldap</quote>, <quote>AD</quote> or
+ <quote>ipa</quote>.</para>
+ </listitem>
+ <listitem>
+ <para>The RULE_NAME for the <quote>files</quote>
+ provider which tries to find a user with the
+ same name.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>domains (string)</term>
+ <listitem>
+ <para>
+ Comma separated list of domain names the rule should be
+ applied. By default a rule is only valid in the domain
+ configured in sssd.conf. If the provider supports
+ subdomains this option can be used to add the rule to
+ subdomains as well.
+ </para>
+ <para>
+ Default: the configured domain in sssd.conf
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>priority (integer)</term>
+ <listitem>
+ <para>
+ Unsigned integer value defining the priority of the
+ rule. The higher the number the lower the priority.
+ <quote>0</quote> stands for the highest priority while
+ <quote>4294967295</quote> is the lowest.
+ </para>
+ <para>
+ Default: the lowest priority
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ To make the configuration simple and reduce the amount of
+ configuration options the <quote>files</quote> provider has some
+ special properties:
+ <itemizedlist>
+ <listitem>
+ <para>
+ if maprule is not set the RULE_NAME name is assumed to
+ be the name of the matching user
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ if a maprule is used both a single user name or a
+ template like
+ <quote>{subject_rfc822_name.short_name}</quote> must
+ be in braces like e.g. <quote>(username)</quote> or
+ <quote>({subject_rfc822_name.short_name})</quote>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the <quote>domains</quote> option is ignored
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </refsect1>
+
<refsect1 id='example'>
<title>EXAMPLES</title>
<para>
@@ -3343,6 +3472,26 @@ enumerate = False
use_fully_qualified_names = false
</programlisting>
</para>
+ <para>
+ 3. The following example shows the configuration for two certificate
+ mapping rules. The first is valid for the configured domain
+ <quote>my.domain</quote> and additionally for the subdomains
+ <quote>your.domain</quote> and uses the full certificate in the
+ search filter. The second example is valid for the domain
+ <quote>files</quote> where it is assumed the files provider is used
+ for this domain and contains a matching rule for the local user
+ <quote>myname</quote>.
+<programlisting>
+[certmap/my.domain/rule_name]
+matchrule = <ISSUER>^CN=My-CA,DC=MY,DC=DOMAIN$
+maprule = (userCertificate;binary={cert!bin})
+domains = my.domain, your.domain
+priority = 10
+
+[certmap/files/myname]
+matchrule = <ISSUER>^CN=My-CA,DC=MY,DC=DOMAIN$<SUBJECT>^CN=User.Name,DC=MY,DC=DOMAIN$
+</programlisting>
+ </para>
</refsect1>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/seealso.xml" />
--
2.9.5