[system-administrators-guide] updating docs for latest version of SSSD (1.8)
Ella Lackey
elladeon at fedoraproject.org
Tue Oct 9 20:19:12 UTC 2012
commit abaa090c946012da5797731eef706382acb0a0fe
Author: elladeon <dlackey at redhat.com.com>
Date: Tue Oct 9 15:18:54 2012 -0500
updating docs for latest version of SSSD (1.8)
en-US/Configuring_Authentication.xml | 4480 ++++++++++++++++++++++++++--------
1 files changed, 3503 insertions(+), 977 deletions(-)
---
diff --git a/en-US/Configuring_Authentication.xml b/en-US/Configuring_Authentication.xml
index 1dd400e..18ca48c 100644
--- a/en-US/Configuring_Authentication.xml
+++ b/en-US/Configuring_Authentication.xml
@@ -1,987 +1,3513 @@
-<?xml version='1.0'?>
+<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<chapter id="ch-Configuring_Authentication">
- <title>Configuring Authentication</title>
- <section id="sect-The_Authentication_Configuration_Tool">
- <title>The Authentication Configuration Tool</title>
- <indexterm significance="normal">
- <primary>authentication</primary>
- <secondary>
- Authentication Configuration Tool
- </secondary>
- </indexterm>
- <indexterm significance="normal">
- <primary>tool</primary>
- <secondary>
- Authentication Configuration Tool
- </secondary>
- </indexterm>
- <para>When a user logs in to a &MAJOROS; system, the username and password combination must be verified, or <firstterm>authenticated</firstterm>, as a valid and active user. Sometimes the information to verify the user is located on the local system, and other times the system defers the authentication to a user database on a remote system.</para>
- <para>The <application>Authentication Configuration Tool</application> provides a graphical interface for configuring user information retrieval from <firstterm>Lightweight Directory Access Protocol</firstterm> (LDAP), <firstterm> Network Information Service</firstterm> (NIS), and <firstterm>Winbind</firstterm> user account databases. This tool also allows you to configure Kerberos to be used as the authentication protocol when using LDAP or NIS.</para>
- <note>
- <title>Using a high or medium security level</title>
- <para>If you configured a medium or high security level during installation (or with the <application>Security Level Configuration Tool</application>), then the firewall will prevent NIS authentication. For more information about firewalls, refer to the <citetitle pubwork="section">"Firewalls"</citetitle> section of the &MAJOROSVER; <citetitle>Security Guide</citetitle>.
- </para>
- </note>
- <indexterm significance="normal">
- <primary>
- system-config-authentication
- </primary>
- <see>
- Authentication Configuration Tool
- </see>
- </indexterm>
- <indexterm significance="normal">
- <primary>
- authconfig
- </primary>
- <see>
- Authentication Configuration Tool
- </see>
- </indexterm>
- <para>To start the graphical version of the <application>Authentication Configuration</application> tool from the desktop, select <menuchoice><guimenu>Applications</guimenu><guisubmenu>Other</guisubmenu><guimenuitem>Authentication</guimenuitem></menuchoice> form the <guimenu>Activities</guimenu> menu or type the command <command>system-config-authentication</command> at a shell prompt (for example, in an <application>XTerm</application> or a <application>GNOME</application> terminal).</para>
- <important>
- <title>Your changes are immediately applied</title>
- <para>After exiting the authentication program, any changes you made take effect immediately.</para>
- </important>
- <section id="sect-The_Authentication_Configuration_Tool-Identity_and_Authentication">
- <title>Identity & Authentication</title>
- <para>
- The <guilabel>Identity & Authentication</guilabel> tab allows you to configure how users should be authenticated, and has several options for each method of authentication. To select which user account database should be used, select an option from the drop-down list.
- </para>
- <figure>
- <title>Identity & Authentication; changing the option in the User Account Database drop-down list changes the contents of the tab</title>
- <mediaobject id="mediaobj-authconfig_LDAP_kerb">
- <imageobject>
- <imagedata align="center" fileref="images/authconfig_LDAP_kerb.png" format="PNG" />
- </imageobject>
- </mediaobject>
- </figure>
- <para>
- The following list explains what each option configures:
- </para>
- <bridgehead>LDAP</bridgehead>
- <indexterm significance="normal">
- <primary>
- Authentication Configuration Tool
- </primary>
- <secondary>
- and LDAP
- </secondary>
- </indexterm>
- <para>The <guilabel>LDAP</guilabel> option instructs the system to retrieve user information via LDAP. It contains the following specifications:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <guilabel>LDAP Search Base DN</guilabel> — Specifies that user information should be retrieved using the listed Distinguished Name (DN).</para>
- </listitem>
- <listitem>
- <para>
- <guilabel>LDAP Server</guilabel> — Specifies the address of the <systemitem class="service">LDAP</systemitem> server.
- </para>
- </listitem>
- <listitem>
- <para>
- <guilabel>Use TLS to encrypt connections</guilabel> — When enabled, <systemitem class="protocol">Transport Layer Security</systemitem> (TLC) will be used to encrypt passwords sent to the <systemitem class="service">LDAP</systemitem> server. The <guibutton>Download CA Certificate</guibutton> option allows you to specify a URL from which to download a valid <firstterm>Certificate Authority certificate</firstterm> (CA). A valid CA certificate must be in the <firstterm>Privacy Enhanced Mail</firstterm> (PEM) format.</para>
- <important>
- <title>Using ldaps:// in the LDAP Server field</title>
- <para>
- The <guilabel>Use TLS to encrypt connections</guilabel> option must not be ticked if an <systemitem class="protocol">ldaps://</systemitem> server address is specified in the <guilabel>LDAP Server</guilabel> field.
- </para>
- </important>
- <para>
- For more information about CA Certificates, refer to <xref linkend="s3-apache-mod_ssl-certificates" />.
- </para>
- </listitem>
- </itemizedlist>
- <para>The <filename>openldap-clients</filename> package must be installed for this option to work.</para>
- <para>For more information about LDAP, refer to <xref linkend="s1-OpenLDAP" />.
- </para>
- <para>
- LDAP provides the following methods of authentication:
- </para>
- <itemizedlist>
- <listitem>
- <indexterm significance="normal">
- <primary>
- Authentication Configuration Tool
- </primary>
- <secondary>
- and Kerberos authentication
- </secondary>
- </indexterm>
- <para>
- <guilabel>Kerberos password</guilabel> — This option enables Kerberos authentication. It contains the following specifications:
- <itemizedlist>
- <listitem>
- <para>
- <guilabel>Realm</guilabel> — Configures the realm for the Kerberos server. The realm is the network that uses Kerberos, composed of one or more KDCs and a potentially large number of clients.
- </para>
- </listitem>
- <listitem>
- <para>
- <guilabel>KDCs</guilabel> — Defines the Key Distribution Centers (KDC), which are servers that issue Kerberos tickets.
- </para>
- </listitem>
- <listitem>
- <para>
- <guilabel>Admin Servers</guilabel> — Specifies the administration server(s) running <command>kadmind</command>.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- The <guimenu>Kerberos Settings</guimenu> dialog also allows you to use DNS to resolve hosts to realms and locate KDCs for realms.
- </para>
- <para>
- The <filename>krb5-libs</filename> and <filename>krb5-workstation</filename> packages must be installed for this option to work. For more information about Kerberos, refer to section <citetitle pubwork="section">Using Kerberos</citetitle> of the &MAJOROSVER; <citetitle>Managing Single Sign-On and Smart Cards</citetitle> guide<!-- TBD6: link to Managing Single Sign-On and Smart Cards guide -->.
- </para>
- </listitem>
- <listitem>
- <para>
- <guilabel>LDAP password</guilabel> — This option instructs standard PAM-enabled applications to use LDAP authentication with options specified in the User Account Configuration of LDAP. When using this option, you must provide an <systemitem class="protocol">ldaps://</systemitem> server address or use TLS for LDAP authentication.
- </para>
- </listitem>
- </itemizedlist>
- <note>
- <title>Setting up the SSSD service</title>
- <para>
- The SSSD service is used as a client for LDAP and Kerberos servers. Thus, offline login is enabled and supported by default. No user interaction is needed to set up the SSSD service with the <application>Authentication Configuration Tool</application>. For more information about the SSSD service, refer to <xref linkend="chap-SSSD_User_Guide-Introduction"/>
- </para>
- </note>
- <bridgehead>NIS</bridgehead>
- <indexterm significance="normal">
- <primary>
- Authentication Configuration Tool
- </primary>
- <secondary>
- and NIS
- </secondary>
- </indexterm>
- <para>
- The <guilabel>NIS</guilabel> option configures the system to connect to a NIS server (as an NIS client) for user and password authentication. To configure this option, specify the NIS domain and NIS server. If the NIS server is not specified, the daemon attempts to find it via broadcast.
- </para>
- <para>The <package>ypbind</package> package must be installed for this option to work. If the NIS user account database is used, the <systemitem class="daemon">portmap</systemitem> and <systemitem class="daemon">ypbind</systemitem> services are started and are also enabled to start at boot time.</para>
- <para>For more information about NIS, refer to section <citetitle pubwork="section">"Securing NIS"</citetitle> of the &MAJOROSVER; <citetitle>Security Guide</citetitle><!-- TBD6: link to Section 2.2.3., “Securing NIS” section of the Security Guide -->.</para>
- <para>
- NIS provides the following methods of authentication:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <guilabel>Kerberos password</guilabel> — This option enables Kerberos authentication. For more information about configuration of the Kerberos authentication method, refer to the previous section on LDAP.<!-- TBD6: link to the Kerberos password option in the previous section on LDAP -->
- </para>
- </listitem>
- <listitem>
- <para>
- <indexterm significance="normal">
- <primary>
- Authentication Configuration Tool
- </primary>
- <secondary>
- and NIS authentication
- </secondary>
- </indexterm>
- <guilabel>NIS password</guilabel> — This option enables NIS authentication. NIS can provide authentication information to outside processes to authenticate users.
- </para>
- </listitem>
- </itemizedlist>
-
- <bridgehead>Winbind</bridgehead>
- <indexterm significance="normal">
- <primary>
- Authentication Configuration Tool
- </primary>
- <secondary>
- and Winbind
- </secondary>
- </indexterm>
- <para>The <guilabel>Winbind</guilabel> option configures the system to connect to a Windows Active Directory or a Windows domain controller. User information from the specified directory or domain controller can then be accessed, and server authentication options can be configured. It contains the following specifications:</para>
- <itemizedlist>
- <listitem>
- <para>
- <guilabel>Winbind Domain</guilabel> — Specifies the Windows Active Directory or domain controller to connect to.</para>
- </listitem>
- <listitem>
- <para>
- <guilabel>Security Model</guilabel> — Allows you to select a security model, which configures the Samba client mode of operation. The drop-down list allows you to select any of the following:
- <itemizedlist>
- <listitem>
- <para>
- <guilabel>ads</guilabel> — This mode instructs Samba to act as a domain member in an Active Directory Server (ADS) realm. To operate in this mode, the <filename>krb5-server</filename> package must be installed, and Kerberos must be configured properly.</para>
- </listitem>
- <listitem>
- <para>
- <guilabel>domain</guilabel> — In this mode, Samba will attempt to validate the username/password by authenticating it through a Windows NT Primary or Backup Domain Controller, similar to how a Windows NT Server would.</para>
- </listitem>
- <listitem>
- <para>
- <guilabel>server</guilabel> — In this mode, Samba will attempt to validate the username/password by authenticating it through another SMB server (for example, a Windows NT Server). If the attempt fails, the <guilabel>user</guilabel> mode will take effect instead.</para>
- </listitem>
- <listitem>
- <para>
- <guilabel>user</guilabel> — This is the default mode. With this level of security, a client must first log in with a valid username and password. Encrypted passwords can also be used in this security mode.</para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- <guilabel>Winbind ADS Realm</guilabel> — When the <guilabel>ads</guilabel> Security Model is selected, this allows you to specify the ADS Realm the Samba server should act as a domain member of.</para>
- </listitem>
- <listitem>
- <para>
- <guilabel>Winbind Domain Controllers</guilabel> — Use this option to specify which domain controller <command>winbind</command> should use. For more information about domain controllers, please refer to <xref linkend="s3-samba-domain-controller"/>.
- </para>
- </listitem>
- <listitem>
- <para>
- <guilabel>Template Shell</guilabel> — When filling out the user information for a Windows NT user, the <command>winbindd</command> daemon uses the value chosen here to specify the login shell for that user.</para>
- </listitem>
- <listitem>
- <para>
- <guilabel>Allow offline login</guilabel> — By checking this option, you allow authentication information to be stored in a local cache (provided by SSSD). This information is then used when a user attempts to authenticate while offline.
- </para>
- </listitem>
- </itemizedlist>
-
-
- <para>For more information about the <command>winbindd</command> service, refer to <xref linkend="s2-samba-daemons"/>.
- </para>
- <indexterm significance="normal">
- <primary>
- Authentication Configuration Tool
- </primary>
- <secondary>
- and Winbind authentication
- </secondary>
- </indexterm>
- <para>
- Winbind provides only one method of authentication, <guilabel>Winbind password</guilabel>. This method of authentication uses the options specified in the User Account Configuration of Winbind to connect to a Windows Active Directory or a Windows domain controller.
- </para>
- </section>
- <section id="sect-The_Authentication_Configuration_Tool-Advanced_Options">
- <title>Advanced Options</title>
- <para>
- This tab allows you to configure advanced options, as listed below.
- </para>
- <figure>
- <title>Advanced Options</title>
- <mediaobject id="mediaobj-authconfig_advanced">
- <imageobject>
- <imagedata align="center" fileref="images/authconfig_advanced.png" format="PNG" />
- </imageobject>
- </mediaobject>
- </figure>
- <bridgehead>Local Authentication Options</bridgehead>
- <itemizedlist>
- <listitem>
- <indexterm significance="normal">
- <primary>
- authentication
- </primary>
- <secondary>
- using fingerprint support
- </secondary>
- </indexterm>
- <para>
- <guilabel>Enable fingerprint reader support</guilabel> — By checking this option, you enable fingerprint authentication to log in by scanning your finger with the fingerprint reader.
- </para>
- </listitem>
- <listitem>
- <para>
- <guilabel>Enable local access control</guilabel> — When enabled, <filename>/etc/security/access.conf</filename> is consulted for authorization of a user.
- </para>
- </listitem>
- <listitem>
- <para>
- <guilabel>Password Hashing Algorithm</guilabel> — This option lets you specify which hashing or cryptographic algorithm should be used to encrypt locally stored passwords.
- </para>
- </listitem>
- </itemizedlist>
- <bridgehead>Other Authentication Options</bridgehead>
- <para>
- <guilabel>Create home directories on the first login</guilabel> — When enabled, the user's home directory is automatically created when they log in if it does not already exist.
- </para>
- <bridgehead>Smart Card Authentication Options</bridgehead>
- <indexterm significance="normal">
- <primary>
- authentication
- </primary>
- <secondary>
- using smart card authentication
- </secondary>
- </indexterm>
- <para>
- <guilabel>Enable smart card support</guilabel> — This option enables smart card authentication. Smart card authentication allows you to log in using a certificate and a key associated with a smart card.
- </para>
- <para>
- When the <guilabel>Enable smart card support</guilabel> option is checked, the following options can be specified:
- <itemizedlist>
- <listitem>
- <para>
- <guilabel>Card Removal Action</guilabel> — This option defines what action the system performs when the card is removed from the card reader during an active session. Two alternatives are available:
- <itemizedlist>
- <listitem>
- <para>
- <guilabel>Ignore</guilabel> — The card removal is ignored and the system continues to function as normal.
- </para>
- </listitem>
- <listitem>
- <para>
- <guilabel>Lock</guilabel> — The current session is immediately locked.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- <guilabel>Require smart card login</guilabel> — Requires the user to login and authenticate with a smart card. It essentially disables any other type of password authentication. This option should not be selected until after you have successfully logged in using a smart card.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- The <package>pam_pkcs11</package> and the <package>coolkey</package> packages must be installed for this option to work. For more information about smart cards, refer to the Red Hat Enterprise Linux 6 <ulink url="http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Managing_Smart_Cards/enabling-smart-card-login.html">Managing Single Sign-On and Smart Cards Guide</ulink>.
- <note>
- <title>Click Revert to restore the previous configuration</title>
- <para>
- You can restore all of the options specified in the <application>Authentication Configuration Tool</application> to the previous configuration setup by clicking <guibutton>Revert</guibutton>.
- </para>
- </note>
-
- </para>
- </section>
- <section id="sect-The_Authentication_Configuration_Tool-Command_Line_Version">
- <title>Command Line Version</title>
- <indexterm significance="normal">
- <primary>
- authconfig
- </primary>
- <secondary>
- commands
- </secondary>
- </indexterm>
- <para>
- The <application>Authentication Configuration</application> tool also supports a command line interface. The command line version can be used in a configuration script or a kickstart script. The authentication options are summarized in <xref linkend="tb-authconfig-cmd-line"/>.
- </para>
- <note>
- <title>Getting the list of supported authentication options</title>
- <para>These options can also be found in the <command>authconfig</command> man page or by typing <command>authconfig --help</command> at the shell prompt.</para>
- </note>
-
- <table id="tb-authconfig-cmd-line">
- <title>Command line options</title>
- <tgroup cols="2">
- <colspec colname="option" colnum="1" colwidth="15*"/>
- <colspec colname="description" colnum="2" colwidth="10*"/>
- <thead>
- <row>
- <entry>
- Option
- </entry>
- <entry>
- Description
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <command>--enableshadow, --useshadow</command>
- </entry>
- <entry>
- Enable shadow passwords
- </entry>
- </row>
- <row>
- <entry>
- <command>--disableshadow</command>
- </entry>
- <entry>
- Disable shadow passwords
- </entry>
- </row>
- <row>
- <entry>
- <command>--passalgo=<replaceable>descrypt|bigcrypt|md5|sha256|sha512</replaceable></command>
- </entry>
- <entry>
- Hash/crypt algorithm to be used
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablenis</command>
- </entry>
- <entry>
- Enable NIS for user account configuration
- </entry>
- </row>
- <row>
- <entry>
- <command>--disablenis</command>
- </entry>
- <entry>
- Disable NIS for user account configuration
- </entry>
- </row>
- <row>
- <entry>
- <command>--nisdomain=<replaceable>domain</replaceable>
- </command>
- </entry>
- <entry>Specify an NIS domain</entry>
- </row>
- <row>
- <entry>
- <command>--nisserver=<replaceable>server</replaceable>
- </command>
- </entry>
- <entry>
- Specify an NIS server
- </entry>
- </row>
- <row>
- <entry>
- <command>--enableldap</command>
- </entry>
- <entry>
- Enable LDAP for user account configuration
- </entry>
- </row>
- <row>
- <entry>
- <command>--disableldap</command>
- </entry>
- <entry>
- Disable LDAP for user account configuration
- </entry>
- </row>
- <row>
- <entry>
- <command>--enableldaptls</command>
- </entry>
- <entry>
- Enable use of TLS with LDAP
- </entry>
- </row>
- <row>
- <entry>
- <command>--disableldaptls</command>
- </entry>
- <entry>
- Disable use of TLS with LDAP
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablerfc2307bis</command>
- </entry>
- <entry>
- Enable use of RFC-2307bis schema for LDAP user information lookups
- </entry>
- </row>
- <row>
- <entry>
- <command>--disablerfc2307bis</command>
- </entry>
- <entry>
- Disable use of RFC-2307bis schema for LDAP user information lookups
- </entry>
- </row>
- <row>
- <entry>
- <command>--enableldapauth</command>
- </entry>
- <entry>
- Enable LDAP for authentication
- </entry>
- </row>
- <row>
- <entry>
- <command>--disableldapauth</command>
- </entry>
- <entry>
- Disable LDAP for authentication
- </entry>
- </row>
- <row>
- <entry>
- <command>--ldapserver=<replaceable>server</replaceable>
- </command>
- </entry>
- <entry>
- Specify an LDAP server
- </entry>
- </row>
- <row>
- <entry>
- <command>--ldapbasedn=<replaceable>dn</replaceable>
- </command>
- </entry>
- <entry>
- Specify an LDAP base DN (Distinguished Name)
- </entry>
- </row>
- <row>
- <entry>
- <command>--ldaploadcacert=<replaceable>URL</replaceable>
- </command>
- </entry>
- <entry>
- Load a CA certificate from the specified URL
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablekrb5</command>
- </entry>
- <entry>
- Enable Kerberos for authentication
- </entry>
- </row>
- <row>
- <entry>
- <command>--disablekrb5</command>
- </entry>
- <entry>
- Disable Kerberos for authentication
- </entry>
- </row>
- <row>
- <entry>
- <command>--krb5kdc=<replaceable>server</replaceable>
- </command>
- </entry>
- <entry>
- Specify Kerberos KDC server
- </entry>
- </row>
- <row>
- <entry>
- <command>--krb5adminserver=<replaceable>server</replaceable>
- </command>
- </entry>
- <entry>
- Specify Kerberos administration server
- </entry>
- </row>
- <row>
- <entry>
- <command>--krb5realm=<replaceable>realm</replaceable>
- </command>
- </entry>
- <entry>
- Specify Kerberos realm
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablekrb5kdcdns</command>
- </entry>
- <entry>
- Enable use of DNS to find Kerberos KDCs
- </entry>
- </row>
- <row>
- <entry>
- <command>--disablekrb5kdcdns</command>
- </entry>
- <entry>
- Disable use of DNS to find Kerberos KDCs
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablekrb5realmdns</command>
- </entry>
- <entry>
- Enable use of DNS to find Kerberos realms
- </entry>
- </row>
- <row>
- <entry>
- <command>--disablekrb5realmdns</command>
- </entry>
- <entry>
- Disable use of DNS to find Kerberos realms
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablewinbind</command>
- </entry>
- <entry>
- Enable winbind for user account configuration
- </entry>
- </row>
- <row>
- <entry>
- <command>--disablewinbind</command>
- </entry>
- <entry>
- Disable winbind for user account configuration
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablewinbindauth</command>
- </entry>
- <entry>
- Enable winbindauth for authentication
- </entry>
- </row>
- <row>
- <entry>
- <command>--disablewinbindauth</command>
- </entry>
- <entry>
- Disable winbindauth for authentication
- </entry>
- </row>
- <row>
- <entry>
- <command>--winbindseparator=<replaceable>\</replaceable>
- </command>
- </entry>
- <entry>
- Character used to separate the domain and user part of winbind usernames if <command>winbindusedefaultdomain</command> is not enabled
- </entry>
- </row>
- <row>
- <entry>
- <command>--winbindtemplatehomedir=<replaceable>/home/%D/%U</replaceable>
- </command>
- </entry>
- <entry>
- Directory that winbind users have as their home
- </entry>
- </row>
- <row>
- <entry>
- <command>--winbindtemplateprimarygroup=<replaceable>nobody</replaceable>
- </command>
- </entry>
- <entry>
- Group that winbind users have as their primary group
- </entry>
- </row>
- <row>
- <entry>
- <command>--winbindtemplateshell=<replaceable>/bin/false</replaceable>
- </command>
- </entry>
- <entry>
- Shell that winbind users have as their default login shell
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablewinbindusedefaultdomain</command>
- </entry>
- <entry>
- Configures winbind to assume that users with no domain in their usernames are domain users
+ <title>Configuring Authentication</title>
+ <para>
+ <emphasis>Authentication</emphasis> is the way that a user is identified and verified to a system. The authentication process requires presenting some sort of identity and credentials, like a username and password. The credentials are then compared to information stored in some data store on the system. In &MAJOROS;, the Authentication Configuration Tool helps configure what kind of data store to use for user credentials, such as LDAP.
+ </para>
+ <para>
+ For convenience and potentially part of single sign-on, &MAJOROS; can use a central daemon to store user credentials for a number of different data stores. The System Security Services Daemon (SSSD) can interact with LDAP, Kerberos, and external applications to verify user credentials. The Authentication Configuration Tool can configure SSSD along with NIS, Winbind, and LDAP, so that authentication processing and caching can be combined.
+ </para>
+ <section id="sect-The_Authentication_Configuration_Tool">
+ <title>Configuring System Authentication</title>
+ <indexterm>
+ <primary>authentication</primary>
+ <secondary>Authentication Configuration Tool</secondary>
+
+ </indexterm>
+ <indexterm>
+ <primary>tool</primary>
+ <secondary>Authentication Configuration Tool</secondary>
+
+ </indexterm>
+ <para>
+ When a user logs into a &MAJOROS; system, that user presents some sort of <emphasis>credential</emphasis> to establish the user identity. The system then checks those credentials against the configured authentication service. If the credentials match and the user account is active, then the user is <emphasis>authenticated</emphasis>. (Once a user is authenticated, then the information is passed to the access control service to determine what the user is permitted to do. Those are the resources the user is <emphasis>authorized</emphasis> to access.)
+ </para>
+ <para>
+ The information to verify the user can be located on the local system or the local system can reference a user database on a remote system, such as LDAP or Kerberos.
+ </para>
+ <para>
+ The system must have a configured list of valid account databases for it to check for user authentication. On &MAJOROS;, the Authentication Configuration Tool has both GUI and command-line options to configure any user data stores.
+ </para>
+ <para>
+ A local system can use a variety of different data stores for user information, including Lightweight Directory Access Protocol (LDAP), Network Information Service (NIS), and Winbind. Additionally, both LDAP and NIS data stores can use Kerberos to authenticate users.
+ </para>
+ <important>
+ <para>
+ If a medium or high security level is set during installation or with the Security Level Configuration Tool, then the firewall prevents NIS authentication. For more information about firewalls, see the "Firewalls" section of the <citetitle>Security Guide</citetitle>.
+ </para>
+
+ </important>
+ <indexterm>
+ <primary>system-config-authentication</primary>
+ <see>Authentication Configuration Tool</see>
+
+ </indexterm>
+ <indexterm>
+ <primary>authconfig</primary>
+ <see>Authentication Configuration Tool</see>
+
+ </indexterm>
+ <section id="launching-authconfig">
+ <title>Launching the Authentication Configuration Tool UI</title>
+ <orderedlist>
+ <listitem>
+ <para>
+ Log into the system as root.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Open the <guimenu>System</guimenu>.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Select the <guimenu>Administration</guimenu> menu.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Select the <guimenuitem>Authentication</guimenuitem> item.
+ </para>
+ <informalfigure> <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/authconfig-ui.png" />
+ </imageobject>
+
+ </mediaobject>
+ </informalfigure>
+ </listitem>
+
+ </orderedlist>
+ <para>
+ Alternatively, run the <command>system-config-authentication</command> command.
+ </para>
+ <important>
+ <title>Important</title>
+ <para>
+ Any changes take effect immediately when the Authentication Configuration Tool UI is closed.
+ </para>
+
+ </important>
+ <para>
+ There are two configuration tabs in the <guilabel>Authentication</guilabel> dialog box:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <guilabel>Identity & Authentication</guilabel>, which configures the resource used as the identity store (the data repository where the user IDs and corresponding credentials are stored).
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>Advanced Options</guilabel>, which allows authentication methods other than passwords or certificates, like smart cards and fingerprint.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
+ <section id="Setting-Auth-Stores">
+ <title>Selecting the Identity Store for Authentication</title>
+ <para>
+ The <guilabel>Identity & Authentication</guilabel> tab sets how users should be authenticated. The default is to use local system authentication, meaning the users and their passwords are checked against local system accounts. A &MAJOROS; machine can also use external resources which contain the users and credentials, including LDAP, NIS, and Winbind.
+ </para>
+ <figure id="fig.authconfig-local">
+ <title>Local Authentication</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/authconfig-local.png" />
+ </imageobject>
+
+ </mediaobject>
+
+ </figure>
+ <section id="configuring-ldap-auth">
+ <title>Configuring LDAP Authentication</title>
+ <indexterm>
+ <primary>Authentication Configuration Tool</primary>
+ <secondary>and LDAP</secondary>
+
+ </indexterm>
+ <para>
+ Either the <filename>openldap-clients</filename> package or the <filename>sssd</filename> package is used to configure an LDAP server for the user database. Both packages are installed by default.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Open the Authentication Configuration Tool, as in <xref linkend="launching-authconfig" />.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Select <guimenuitem>LDAP</guimenuitem> in the <guilabel>User Account Database</guilabel> drop-down menu.
+ </para>
+ <informalfigure> <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/authconfig_LDAP.png" />
+ </imageobject>
+
+ </mediaobject>
+ </informalfigure>
+ </listitem>
+ <listitem>
+ <para>
+ Set the information that is required to connect to the LDAP server.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <guilabel>LDAP Search Base DN</guilabel> gives the root suffix or <emphasis>distinguished name</emphasis> (DN) for the user directory. All of the user entries used for identity/authentication will exist below this parent entry. For example, <emphasis>ou=people,dc=example,dc=com</emphasis>.
+ </para>
+ <para>
+ This field is optional. If it is not specified, then SSSD attempts to detect the search base using the <parameter>namingContexts</parameter> and <parameter>defaultNamingContext</parameter> attributes in the LDAP server's configuration entry.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>LDAP Server</guilabel> gives the URL of the LDAP server. This usually requires both the hostname and port number of the LDAP server, such as <emphasis>ldap://ldap.example.com:389</emphasis>.
+ </para>
+ <para>
+ Entering the secure protocol in the URL, <command>ldaps://</command>, enables the <guibutton>Download CA Certificate</guibutton> button.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>Use TLS to encrypt connections</guilabel> sets whether to use Start TLS to encrypt the connections to the LDAP server. This enables a secure connection over a standard port.
+ </para>
+ <para>
+ Selecting TLS enables the <guibutton>Download CA Certificate</guibutton> button, which retrieves the issuing CA certificate for the LDAP server from whatever certificate authority issued it. The CA certificate must be in the privacy enhanced mail (PEM) format.
+ </para>
+ <important>
+ <title>Important</title>
+ <para>
+ <emphasis>Do not</emphasis> select <guilabel>Use TLS to encrypt connections</guilabel> if the server URL uses a secure protocol (<command>ldaps</command>). This option uses Start TLS, which initiates a secure connection over a standard port; if a secure port is specified, then a protocol like SSL must be used instead of Start TLS.
+ </para>
+
+ </important>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </listitem>
+ <listitem>
+ <para>
+ Select the authentication method. LDAP allows simple password authentication or Kerberos authentication.
+ </para>
+ <para>
+ Using Kerberos is described in <xref linkend="using-kerb-ldap-nis" />.
+ </para>
+ <para>
+ The <guilabel>LDAP password</guilabel> option uses PAM applications to use LDAP authentication. This option requires either a secure (<command>ldaps://</command>) URL or the TLS option to connect to the LDAP server.
+ </para>
+
+ </listitem>
+
+ </orderedlist>
+
+ </section>
+
+ <section id="configuring-nis-auth">
+ <title>Configuring NIS Authentication</title>
+ <indexterm>
+ <primary>Authentication Configuration Tool</primary>
+ <secondary>and NIS</secondary>
+
+ </indexterm>
+ <para>
+
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Install the <filename>ypbind</filename> package. This is required for NIS services, but is not installed by default.
+ </para>
+<screen>[root at server ~]# yum install ypbind</screen>
+ <para>
+ When the <filename>ypbind</filename> service is installed, the <systemitem>portmap</systemitem> and <systemitem>ypbind</systemitem> services are started and enabled to start at boot time.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Open the Authentication Configuration Tool, as in <xref linkend="launching-authconfig" />.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Select <guimenuitem>NIS</guimenuitem> in the <guilabel>User Account Database</guilabel> drop-down menu.
+ </para>
+ <informalfigure> <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/authconfig_nis.png" />
+ </imageobject>
+
+ </mediaobject>
+ </informalfigure>
+ </listitem>
+ <listitem>
+ <para>
+ Set the information to connect to the NIS server, meaning the NIS domain name and the server hostname. If the NIS server is not specified, the <command>authconfig</command> daemon scans for the NIS server.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Select the authentication method. NIS allows simple password authentication or Kerberos authentication.
+ </para>
+ <para>
+ Using Kerberos is described in <xref linkend="using-kerb-ldap-nis" />.
+ </para>
+
+ </listitem>
+
+ </orderedlist>
+ <para>
+ For more information about NIS, see the "Securing NIS" section of the <citetitle>Security Guide</citetitle>.
+ </para>
+
+ </section>
+
+ <section id="winbind-auth">
+ <title>Configuring Winbind Authentication</title>
+ <indexterm>
+ <primary>Authentication Configuration Tool</primary>
+ <secondary>and Winbind</secondary>
+
+ </indexterm>
+ <para>
+ Using Winbind as an authentication provider requires the <filename>samba-winbind</filename> package, which is installed by default.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Open the Authentication Configuration Tool, as in <xref linkend="launching-authconfig" />.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Select <guimenuitem>Winbind</guimenuitem> in the <guilabel>User Account Database</guilabel> drop-down menu.
+ </para>
+ <informalfigure> <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/authconfig_winbind.png" />
+ </imageobject>
+
+ </mediaobject>
+ </informalfigure>
+ </listitem>
+ <listitem>
+ <para>
+ Set the information that is required to connect to the Microsoft Active Directory domain controller.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <guilabel>Winbind Domain</guilabel> gives the Windows domain to connect to.
+ </para>
+ <para>
+ This should be in the Windows 2000 format, such as <command>DOMAIN</command>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>Security Model</guilabel> sets the security model to use for Samba clients. <command>authconfig</command> supports four types of security models:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <guilabel>ads</guilabel> configures Samba to act as a domain member in an Active Directory Server realm. To operate in this mode, the <filename>krb5-server</filename> package must be installed and Kerberos must be configured properly.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>domain</guilabel> has Samba validate the username/password by authenticating it through a Windows primary or backup domain controller, much like a Windows server.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>server</guilabel> has a local Samba server validate the username/password by authenticating it through another server, such as a Windows server. If the server authentication attempt fails, the system then attempts to authentication using <command>user</command> mode.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>user</guilabel> requires a client to log in with a valid username and password. This mode does support encrypted passwords.
+ </para>
+ <para>
+ The username format must be <emphasis>domain\user</emphasis>, such as <command>EXAMPLE\jsmith</command>.
+ </para>
+ <note>
+ <para>
+ When verifying that a given user exists in the Windows domain, always use Windows 2000-style formats and escape the backslash (\) character. For example:
+<screen>[root at server ~]# getent passwd domain\\user DOMAIN\user:*:16777216:16777216:Name Surname:/home/DOMAIN/user:/bin/bash</screen>
+ </para>
+ </note>
+ <para>
+ This is the default option.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>Winbind ADS Realm</guilabel> gives the Active Directory realm that the Samba server will join. This is only used with the <guilabel>ads</guilabel> security model.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>Winbind Domain Controllers</guilabel> gives the domain controller to use. For more information about domain controllers, refer to <xref linkend="s3-samba-domain-controller" />.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>Template Shell</guilabel> sets which login shell to use for Windows user account settings.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>Allow offline login</guilabel> allows authentication information to be stored in a local cache. The cache is referenced when a user attempts to authenticate to system resources while the system is offline.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </listitem>
+
+ </orderedlist>
+ <para>
+ For more information about the <command>winbindd</command> service, refer to <xref linkend="s2-samba-daemons" />.
+ </para>
+ <indexterm>
+ <primary>Authentication Configuration Tool</primary>
+ <secondary>and Winbind authentication</secondary>
+
+ </indexterm>
+
+ </section>
+
+ <section id="using-kerb-ldap-nis">
+ <title>Using Kerberos with LDAP or NIS Authentication</title>
+ <indexterm>
+ <primary>Authentication Configuration Tool</primary>
+ <secondary>and Kerberos authentication</secondary>
+
+ </indexterm>
+ <para>
+ Both LDAP and NIS authentication stores support Kerberos authentication methods. Using Kerberos has a couple of benefits:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ It uses a security layer for communication while still allowing connections over standard ports.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ It automatically uses credentials caching with SSSD, which allows offline logins.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+ <para>
+ Using Kerberos authentication requires the <filename>krb5-libs</filename> and <filename>krb5-workstation</filename> packages.
+ </para>
+ <para>
+ The <guimenuitem>Kerberos password</guimenuitem> option from the <guilabel>Authentication Method</guilabel> drop-down menu automatically opens the fields required to connect to the Kerberos realm.
+ </para>
+ <figure>
+ <title>Kerberos Fields</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/authconfig_LDAP_kerb.png" />
+ </imageobject>
+
+ </mediaobject>
+
+ </figure>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <guilabel>Realm</guilabel> gives the name for the realm for the Kerberos server. The realm is the network that uses Kerberos, composed of one or more <emphasis>key distribution centers</emphasis> (KDC) and a potentially large number of clients.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>KDCs</guilabel> gives a comma-separated list of servers that issue Kerberos tickets.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>Admin Servers</guilabel> gives a list of administration servers running the <command>kadmind</command> process in the realm.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Optionally, use DNS to resolve server hostname and to find additional KDCs within the realm.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+ <para>
+ For more information about Kerberos, refer to section "Using Kerberos" of the &MAJOROSVER; <citetitle>Managing Single Sign-On and Smart Cards</citetitle> guide.
+ </para>
+
+ </section>
+
+
+ </section>
+
+ <section id="sect-The_Authentication_Configuration_Tool-Advanced_Options">
+ <title>Configuring Alternative Authentication Features</title>
+ <para>
+ The Authentication Configuration Tool also configures settings related to authentication behavior, apart from the identity store. This includes entirely different authentication methods (fingerprint scans and smart cards) or local authentication rules. These alternative authentication options are configured in the <guilabel>Advanced Options</guilabel> tab.
+ </para>
+ <figure>
+ <title>Advanced Options</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/authconfig_advanced.png" />
+ </imageobject>
+
+ </mediaobject>
+
+ </figure>
+
+ <section id="authconfig-fingerprint">
+ <title>Using Fingerprint Authentication</title>
+ <indexterm>
+ <primary>authentication</primary>
+ <secondary>using fingerprint support</secondary>
+
+ </indexterm>
+ <para>
+ When there is appropriate hardware available, the <guilabel>Enable fingerprint reader support</guilabel> option allows fingerprint scans to be used to authenticate local users in addition to other credentials.
+ </para>
+
+ </section>
+ <section id="authconfig-local-auth">
+ <title>Setting Local Authentication Parameters</title>
+ <para>
+ There are two options in the <guilabel>Local Authentication Options</guilabel> area which define authentication behavior on the local system:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <guilabel>Enable local access control</guilabel> instructs the <filename>/etc/security/access.conf</filename> file to check for local user authorization rules.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>Password Hashing Algorithm</guilabel> sets the hashing algorithm to use to encrypt locally-stored passwords.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
+ <section id="authconfig-smartcard">
+ <title>Enabling Smart Card Authentication</title>
+ <indexterm>
+ <primary>authentication</primary>
+ <secondary>using smart card authentication</secondary>
+
+ </indexterm>
+ <para>
+ When there are appropriate smart card readers available, a system can accept smart cards (or <emphasis>tokens</emphasis>) instead of other user credentials to authenticate.
+ </para>
+ <para>
+ Once the <guilabel>Enable smart card support</guilabel> option is selected, then the behaviors of smart card authentication can be defined:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <guilabel>Card Removal Action</guilabel> tells the system how to respond when the card is removed from the card reader during an active session. A system can either ignore the removal and allow the user to access resources as normal, or a system can immediately lock until the smart card is supplied.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>Require smart card login</guilabel> sets whether a smart card is required for logins or simply allowed for logins. When this option is selected, all other methods of authentication are immediately blocked.
+ </para>
+ <warning>
+ <para>
+ Do not select this option until you have successfully authenticated to the system using a smart card.
+ </para>
+
+ </warning>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+ <para>
+ Using smart cards requires the <filename>pam_pkcs11</filename> package.
+ </para>
+
+ </section>
+
+ <section id="authconfig-homedirs">
+ <title>Creating User Home Directories</title>
+ <para>
+ There is an option (<guilabel>Create home directories on the first login</guilabel>) to create a home directory automatically the first time that a user logs in.
+ </para>
+ <para>
+ This option is beneficial with accounts that are managed centrally, such as with LDAP. However, this option should not be selected if a system like automount is used to manage user home directories.
+ </para>
+
+ </section>
+
+
+ </section>
+
+ <section id="sect-The_Authentication_Configuration_Tool-Command_Line_Version">
+ <title>Configuring Authentication from the Command Line</title>
+ <indexterm>
+ <primary>authconfig</primary>
+ <secondary>commands</secondary>
+
+ </indexterm>
+ <para>
+ The <command>authconfig</command> command-line tool updates all of the configuration files and services required for system authentication, according to the settings passed to the script. Along with allowing all of the identity and authentication configuration options that can be set through the UI, the <command>authconfig</command> tool can also be used to create backup and kickstart files.
+ </para>
+ <para>
+ For a complete list of <command>authconfig</command> options, check the help output and the man page.
+ </para>
+ <section id="tips-for-authconfig">
+ <title>Tips for Using authconfig</title>
+ <para>
+ There are some things to remember when running <command>authconfig</command>:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ With every command, use either the <option>--update</option> or <option>--test</option> option. One of those options is required for the command to run successfully. Using <option>--update</option> writes the configuration changes. <option>--test</option> prints the changes to stdout but does not apply the changes to the configuration.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Each enable option has a corresponding disable option.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
+ <section id="authconfig-ldap-cmd">
+ <title>Configuring LDAP User Stores</title>
+ <para>
+ To use an LDAP identity store, use the <option>--enableldap</option>. To use LDAP as the authentication source, use <option>--enableldapauth</option> and then the requisite connection information, like the LDAP server name, base DN for the user suffix, and (optionally) whether to use TLS. The <command>authconfig</command> command also has options to enable or disable RFC 2307bis schema for user entries, which is not possible through the Authentication Configuration UI.
+ </para>
+ <para>
+ Be sure to use the full LDAP URL, including the protocol (<command>ldap</command> or <command>ldaps</command>) and the port number. Do <emphasis>not</emphasis> use a secure LDAP URL (<command>ldaps</command>) with the <option>--enableldaptls</option> option.
+ </para>
+
+<screen>authconfig --enableldap --enableldapauth --ldapserver=ldap://ldap.example.com:389,ldap://ldap2.example.com:389 --ldapbasedn="ou=people,dc=example,dc=com" --enableldaptls --ldaploadcacert=https://ca.server.example.com/caCert.crt --update
+</screen>
+ <para>
+ Instead of using <option>--ldapauth</option> for LDAP password authentication, it is possible to use Kerberos with the LDAP user store. These options are described in <xref linkend="authconfig-kerberos-cmd" />.
+ </para>
+
+ </section>
+
+ <section id="authconfig-nis-cmd">
+ <title>Configuring NIS User Stores</title>
+ <para>
+ To use a NIS identity store, use the <option>--enablenis</option>. This automatically uses NIS authentication, unless the Kerberos parameters are explicitly set, so it uses Kerberos authentication (<xref linkend="authconfig-kerberos-cmd" />). The only parameters are to identify the NIS server and NIS domain; if these are not used, then the <systemitem>authconfig</systemitem> service scans the network for NIS servers.
+ </para>
+
+<screen>authconfig --enablenis --nisdomain=EXAMPLE --nisserver=nis.example.com --update</screen>
+
+ </section>
+
+ <section id="authconfig-winbind-cmd">
+ <title>Configuring Winbind User Stores</title>
+ <para>
+ Windows domains have several different security models, and the security model used in the domain determines the authentication configuration for the local system.
+ </para>
+ <para>
+ For user and server security models, the Winbind configuration requires only the domain (or workgroup) name and the domain controller hostnames.
+ </para>
+
+<screen>authconfig --enablewinbind --enablewinbindauth --smbsecurity=user|server --enablewinbindoffline --smbservers=ad.example.com --smbworkgroup=EXAMPLE --update</screen>
+<note>
+ <para>
+ The username format must be <emphasis>domain\user</emphasis>, such as <command>EXAMPLE\jsmith</command>.
+ </para>
+ <para>
+ When verifying that a given user exists in the Windows domain, always use Windows 2000-style formats and escape the backslash (\) character. For example:
+<screen>[root at server ~]# getent passwd domain\\user DOMAIN\user:*:16777216:16777216:Name Surname:/home/DOMAIN/user:/bin/bash</screen>
+ </para>
+ </note>
+ <para>
+ For ads and domain security models, the Winbind configuration allows additional configuration for the template shell and realm (ads only). For example:
+ </para>
+
+<screen>authconfig --enablewinbind --enablewinbindauth --smbsecurity ads --enablewinbindoffline --smbservers=ad.example.com --smbworkgroup=EXAMPLE --smbrealm EXAMPLE.COM --winbindtemplateshell=/bin/sh --update</screen>
+ <para>
+ There are a lot of other options for configuring Windows-based authentication and the information for Windows user accounts, such as name formats, whether to require the domain name with the username, and UID ranges. These options are listed in the <command>authconfig</command> help.
+ </para>
+
+ </section>
+
+ <section id="authconfig-kerberos-cmd">
+ <title>Configuring Kerberos Authentication</title>
+ <para>
+ Both LDAP and NIS allow Kerberos authentication to be used in place of their native authentication mechanisms. At a minimum, using Kerberos authentication requires specifying the realm, the KDC, and the administrative server. There are also options to use DNS to resolve client names and to find additional admin servers.
+ </para>
+
+<screen>authconfig <replaceable>NIS or LDAP options</replaceable> --enablekrb5 --krb5realm EXAMPLE --krb5kdc kdc.example.com:88,server.example.com:88 --krb5adminserver server.example.com:749 --enablekrb5kdcdns --enablekrb5realmdns --update</screen>
+
+ </section>
+
+ <section id="authconfig-local-cmd">
+ <title>Configuring Local Authentication Settings</title>
+ <para>
+ The Authentication Configuration Tool can also control some user settings that relate to security, such as creating home directories, setting password hash algorithms, and authorization. These settings are done independently of identity/user store settings.
+ </para>
+ <para>
+ For example, to create user home directories:
+ </para>
+
+<screen>authconfig --enablemkhomedir --update</screen>
+ <para>
+ To set or change the hash algorithm used to encrypt user passwords:
+ </para>
+
+<screen>authconfig --passalgo=sha512 --update</screen>
+
+ </section>
+
+ <section id="authconfig-fingerprint-cmd">
+ <title>Configuring Fingerprint Authentication</title>
+ <para>
+ There is one option to enable support for fingerprint readers. This option can be used alone or in conjunction with other <systemitem>authconfig</systemitem> settings, like LDAP user stores.
+ </para>
+
+<screen>authconfig --enablefingerprint --update</screen>
+
+ </section>
+
+ <section id="authconfig-smartcards-cmd">
+ <title>Configuring Smart Card Authentication</title>
+ <para>
+ All that is required to use smart cards with a system is to set the <option>--enablesmartcard</option> option:
+ </para>
+
+<screen>authconfig --enablesmartcard --update</screen>
+ <para>
+ There are other configuration options for smart cards, such as changing the default smart card module, setting the behavior of the system when the smart card is removed, and requiring smart cards for login.
+ </para>
+ <para>
+ For example, this command instructs the system to lock out a user immediately if the smart card is removed (a setting of 1 ignores it if the smart card is removed):
+ </para>
+<screen>authconfig --enablesmartcard --smartcardaction=0 --update</screen>
+ <para>
+ Once smart card authentication has been successfully configured and tested, then the system can be configured to require smart card authentication for users rather than simple password-based authentication.
+ </para>
+<screen>authconfig --enablerequiresmartcard --update</screen>
+ <warning>
+ <para>
+ Do not use the <option>--enablerequiresmartcard</option> option until you have successfully authenticated to the system using a smart card. Otherwise, users may be unable to log into the system.
+ </para>
+
+ </warning>
+
+ </section>
+
+ <section id="authconfig-kickstart-cmd">
+ <title>Managing Kickstart and Configuration Files</title>
+ <para>
+ The <option>--update</option> option updates all of the configuration files with the configuration changes. There are a couple of alternative options with slightly different behavior:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>--kickstart</option> writes the updated configuration to a kickstart file.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <option>--test</option> prints the full configuration, with changes, to stdout but does not edit any configuration files.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+ <para>
+ Additionally, <systemitem>authconfig</systemitem> can be used to back up and restore previous configurations. All archives are saved to a unique subdirectory in the <filename>/var/lib/authconfig/</filename> directory. For example, the <option>--savebackup</option> option gives the backup directory as <command>2011-07-01</command>:
+ </para>
+
+<screen>authconfig --savebackup=2011-07-01</screen>
+ <para>
+ This backs up all of the authentication configuration files beneath the <filename>/var/lib/authconfig/backup-2011-07-01</filename> directory.
+ </para>
+ <para>
+ Any of the saved backups can be used to restore the configuration using the <option>--restorebackup</option> option, giving the name of the manually-saved configuration:
+ </para>
+<screen>authconfig --restorebackup=2011-07-01</screen>
+<para>
+ Additionally, <command>authconfig</command> automatically makes a backup of the configuration before it applies any changes (with the <option>--update</option> option).
+ The configuration can be restored from the most recent automatic backup, without having to specify the exact backup, using the <option>--restorelastbackup</option> option.
+ </para>
+
+ </section>
+
+
+ </section>
+
+ <section>
+ <title>Using Custom Home Directories </title>
+ <para>
+ If LDAP users have home directories that are not in <filename>/home</filename> and the system is configured to
+ create home directories the first time users log in, then these directories are created with the wrong permissions.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Apply the correct SELinux context and permissions from the <filename>/home</filename> directory to the home directory that
+ is created on the local system. For example:
+<screen># semanage fcontext -a -e /home /home/locale</screen>
+
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Install the <filename>oddjob-mkhomedir</filename> package on the system.
+ </para>
+ <para>
+ This package provides the <systemitem class="library">pam_oddjob_mkhomedir.so</systemitem> library, which the Authentication Configuration Tool uses to create home directories. The <systemitem class="library">pam_oddjob_mkhomedir.so</systemitem> library, unlike the default <systemitem class="library">pam_mkhomedir.so</systemitem> library, can create SELinux labels.
+ </para>
+ <para>
+ The Authentication Configuration Tool automatically uses the <systemitem class="library">pam_oddjob_mkhomedir.so</systemitem> library if it is available. Otherwise, it will default to using <systemitem class="library">pam_mkhomedir.so</systemitem>.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Make sure the <systemitem>oddjobd</systemitem> service is running.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Re-run the Authentication Configuration Tool and enable home directories, as in <xref linkend="sect-The_Authentication_Configuration_Tool-Advanced_Options" />.
+ </para>
+ </listitem>
+
+ </orderedlist>
+ <para>
+ If home directories were created before the home directory configuration was changed, then correct the permissions and SELinux contexts. For example:
+<screen># semanage fcontext -a -e /home /home/locale
+# restorecon -R -v /home/locale</screen>
+
+ </para>
+
+ </section>
+
+
+ </section>
+
+ <section id="SSSD-Introduction">
+ <title>Using and Caching Credentials with SSSD</title>
+ <para>
+ The System Security Services Daemon (SSSD) provides access to different identity and authentication providers. SSSD is an intermediary between local clients and any configured data store. The local clients connect to SSSD and then SSSD contacts the external providers. This brings a number of benefits for administrators:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>Reducing the load on identification/authentication servers.</emphasis> Rather than having every client service attempt to contact the identification server directly, all of the local clients can contact SSSD which can connect to the identification server or check its cache.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Permitting offline authentication.</emphasis> SSSD can optionally keep a cache of user identities and credentials that it retrieves from remote services. This allows users to authenticate to resources successfully, even if the remote identification server is offline or the local machine is offline.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Using a single user account.</emphasis> Remote users frequently have two (or even more) user accounts, such as one for their local system and one for the organizational system. This is necessary to connect to a virtual private network (VPN). Because SSSD supports caching and offline authentication, remote users can connect to network resources simply by authenticating to their local machine and then SSSD maintains their network credentials.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+ <para>
+ The System Security Services Daemon does not require any additional configuration or tuning to work with the Authentication Configuration Tool. However, SSSD can work with other applications, and the daemon may require configuration changes to improve the performance of those applications.
+ </para>
+
+ <section id="about-sssd">
+ <title>About the sssd.conf File</title>
+ <para>
+ SSSD services and domains are configured in a <filename>.conf</filename> file. The default file is <filename>/etc/sssd/sssd.conf</filename>, although alternative files can be passed to SSSD by using the <option>-c</option> option with the <command>sssd</command> command:
+ </para>
+
+<screen># sssd -c /etc/sssd/customfile.conf</screen>
+ <para>
+ Both services and domains are configured individually, in separate sections on the configuration identified by <emphasis>[type/name]</emphasis> divisions, such as <command>[domain/LDAP]</command>. The configuration file uses simple <emphasis>key = value</emphasis> lines to set the configuration. Comment lines are set by either a hash sign (#) or a semicolon (;)
+ </para>
+ <para>
+ For example:
+ </para>
+
+<programlisting>[section]
+# Comment line
+key1 = val1
+key10 = val1,val2
+</programlisting>
+
+ </section>
+
+ <section id="Installing_SSSD-Starting_and_Stopping_SSSD">
+ <title>Starting and Stopping SSSD</title>
+ <note>
+ <para>
+ Configure at least one domain before starting SSSD for the first time. See <xref linkend="Configuring_Domains" />.
+ </para>
+
+ </note>
+ <para>
+ Either the <command>service</command> command or the <filename>/etc/init.d/sssd</filename> script can start SSSD. For example:
+ </para>
+
+<screen># service sssd start</screen>
+ <para>
+ By default, SSSD is configured not to start automatically. There are two ways to change this behavior:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Using the <command>authconfig</command> command:
+ </para>
+
+<screen>[root at server ~]# authconfig --enablesssd --enablesssdauth --update</screen>
+ </listitem>
+ <listitem>
+ <para>
+ Using the <command>chkconfig</command> command:
+ </para>
+<screen>[root at server ~]# chkconfig sssd on</screen>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="Configuring_Services">
+ <title>Configuring SSSD to Work with System Services</title>
+ <para>
+ SSSD worked with specialized services that run in tandem with the SSSD process itself. SSSD and its associated services are configured in the <filename>sssd.conf</filename> file. The <literal>[sssd]</literal> section also lists the services that are active and should be started when <systemitem class="daemon">sssd</systemitem> starts within the <command>services</command> directive.
+ </para>
+ <para>
+ SSSD currently provides several services:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ A Name Service Switch (NSS) provider service that answers name service requests from the <systemitem>sssd_nss</systemitem> module. This is configured in the <command>[nss]</command> section of the SSSD configuration.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ A PAM provider service that manages a PAM conversation through the <systemitem>sssd_pam</systemitem> module. This is configured in the <command>[pam]</command> section of the configuration.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <systemitem class="service">monitor</systemitem>, a special service that monitors and starts or restarts all other SSSD services. Its options are specified in the <literal>[sssd]</literal> section of the <filename>/etc/sssd/sssd.conf</filename> configuration file.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+ <note>
+ <para>
+ If a DNS lookup fails to return an IPv4 address for a hostname, SSSD attempts to look up an IPv6 address before returning a failure. This only ensures that the asynchronous resolver identifies the correct address.
+ </para>
+ <para>
+ The hostname resolution behavior is configured in the <parameter>lookup family order</parameter> option in the <filename>sssd.conf</filename> configuration file.
+ </para>
+ </note>
+
+
+ <section id="Configuration_Options-NSS_Configuration_Options">
+ <title>Configuring NSS Services</title>
+ <para>
+ SSSD provides an NSS module, <systemitem>sssd_nss</systemitem>, which instructs the system to use SSSD to retrieve user information. The NSS configuration must include a reference to the SSSD module, and then the SSSD configuration sets how SSSD interacts with NSS.
+ </para>
+ <section id="nss-maps"><title>About NSS Service Maps and SSSD</title>
+ <para>
+ The Name Service Switch (NSS) provides a central configuration for services to look up a number of configuration and name resolution services. NSS provides one method of mapping system identities and services with configuration sources.
+ </para>
+ <para>
+ SSSD works with NSS as a provider services for several types of NSS maps:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Passwords (<command>passwd</command>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ User groups (<command>shadow</command>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Groups (<command>groups</command>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Netgroups (<command>netgroups</command>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Services (<command>services</command>)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="nss-sssd"><title>Configuring NSS Services to Use SSSD</title>
+ <para>
+ NSS can use multiple identity and configuration providers for any and all of its service maps. The default is to use system files for services; for SSSD to be included, the <command>nss_sss</command> module has to be included for the desired service type.
+ </para>
+ <orderedlist>
+ <listitem>
+
+ <para>
+ Use the Authentication Configuration tool to enable SSSD. This automatically configured the <filename>nsswitch.conf</filename> file to use SSSD as a provider.
+ </para>
+<screen>[root at server ~]# authconfig --enablesssd --update</screen>
+ <para>
+ This automatically configures the password, shadow, group, and netgroups services maps to use the SSSD module:
+ </para>
+<screen>passwd: files sss
+shadow: files sss
+group: files sss
+
+netgroup: files sss</screen>
+ </listitem>
+ <listitem>
+ <para>
+ The services map is not enabled by default when SSSD is enabled with <command>authconfig</command>. To include that map, open the <filename>nsswitch.conf</filename> file and add the <command>sss</command> module to the <command>services</command> map:
+ </para>
+<screen>[root at server ~]# vim /etc/nsswitch.conf
+
+...
+services: file <userinput>sss</userinput>
+...</screen>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section id="nss-sssd-config"><title>Configuring SSSD to Work with NSS</title>
+ <para>
+ The options and configuration that SSSD uses to service NSS requests are configured in the SSSD configuration file, in the <command>[nss]</command> services section.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Open the <filename>sssd.conf</filename> file.
+ </para>
+
+<screen>[root at server ~]# vim /etc/sssd/sssd.conf</screen>
+
+ </listitem>
+ <listitem>
+ <para>
+ Make sure that NSS is listed as one of the services that works with SSSD.
+ </para>
+
+<screen>[sssd]
+config_file_version = 2
+reconnection_retries = 3
+sbus_timeout = 30
+services = <userinput>nss</userinput>, pam</screen>
+
+ </listitem>
+ <listitem>
+ <para>
+ In the <command>[nss]</command> section, change any of the NSS parameters. These are listed in <xref linkend="tab.nss-sssd" />.
+ </para>
+
+<screen>[nss]
+filter_groups = root
+filter_users = root
+reconnection_retries = 3
+entry_cache_timeout = 300
+entry_cache_nowait_percentage = 75</screen>
+
+ </listitem>
+ <listitem>
+ <para>
+ Restart SSSD.
+ </para>
+<screen>[root at server ~]# service sssd restart</screen>
+ </listitem>
+ </orderedlist>
+ <table id="tab.nss-sssd">
+ <title>SSSD [nss] Configuration Parameters</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>
+ Parameter
+ </entry>
+ <entry>
+ Value Format
+ </entry>
+ <entry>
+ Description
+ </entry>
+
+ </row>
+
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ enum_cache_timeout
+ </entry>
+ <entry>
+ integer
+ </entry>
+ <entry>
+ Specifies how long, in seconds, <filename>sssd_nss</filename> should cache requests for information about all users (enumerations).
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ entry_cache_nowait_percentage
+ </entry>
+ <entry>
+ integer
+ </entry>
+ <entry>
+ Specifies how long <filename>sssd_nss</filename> should return cached entries before refreshing the cache. Setting this to zero (<literal>0</literal>) disables the entry cache refresh.
+ <para>
+ This configures the entry cache to update entries in the background automatically if they are requested if the time before the next update is a certain percentage of the next interval. For example, if the interval is 300 seconds and the cache percentage is 75, then the entry cache will begin refreshing when a request comes in at 225 seconds — 75% of the interval.
+ </para>
+ <para>
+ The allowed values for this option are 0 to 99, which sets the percentage based on the <option>entry_cache_timeout</option> value. The default value is 50%.
+ </para>
+
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ entry_negative_timeout
+ </entry>
+ <entry>
+ integer
+ </entry>
+ <entry>
+ Specifies how long, in seconds, <filename>sssd_nss</filename> should cache <emphasis>negative</emphasis> cache hits. A negative cache hit is a query for an invalid database entries, including non-existent entries.
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ filter_users, filter_groups
+ </entry>
+ <entry>
+ string
+ </entry>
+ <entry>
+ Tells SSSD to exclude certain users from being fetched from the NSS database. This is particularly useful for system accounts such as <systemitem class="username">root</systemitem>.
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ filter_users_in_groups
+ </entry>
+ <entry>
+ Boolean
+ </entry>
+ <entry>
+ Sets whether users listed in the <option>filter_users</option> list appear in group memberships when performing group lookups. If set to <literal>FALSE</literal>, group lookups return all users that are members of that group. If not specified, this value defaults to <literal>true</literal>, which filters the group member lists.
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ debug_level
+ </entry>
+ <entry>
+ integer, 0 - 9
+ </entry>
+ <entry>
+ Sets a debug logging level.
+ </entry>
+
+ </row>
+ </tbody>
+
+ </tgroup>
+
+ </table>
+
+ </section>
+ </section>
+
+ <section id="Configuration_Options-PAM_Configuration_Options">
+ <title>Configuring the PAM Service</title>
+ <warning>
+ <para>
+ A mistake in the PAM configuration file can lock users out of the system completely. Always back up the configuration files before performing any changes, and keep a session open so that any changes can be reverted.
+ </para>
+
+ </warning>
+ <para>
+ SSSD provides a PAM module, <systemitem>sssd_pam</systemitem>, which instructs the system to use SSSD to retrieve user information. The PAM configuration must include a reference to the SSSD module, and then the SSSD configuration sets how SSSD interacts with PAM.
+ </para>
+ <para>
+ To configure the PAM service:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Use <command>authconfig</command> to enable SSSD for system authentication.
+<programlisting># authconfig --update --enablesssd --enablesssdauth</programlisting>
+ This automatically updates the PAM configuration to reference all of the SSSD modules:
+ </para>
+
+<programlisting>#%PAM-1.0
+# This file is auto-generated.
+# User changes will be destroyed the next time authconfig is run.
+auth required pam_env.so
+auth sufficient pam_unix.so nullok try_first_pass
+auth requisite pam_succeed_if.so uid >= 500 quiet
+<userinput>auth sufficient pam_sss.so use_first_pass</userinput>
+auth required pam_deny.so
+
+account required pam_unix.so
+account sufficient pam_localuser.so
+account sufficient pam_succeed_if.so uid < 500 quiet
+<userinput>account [default=bad success=ok user_unknown=ignore] pam_sss.so</userinput>
+account required pam_permit.so
+
+password requisite pam_cracklib.so try_first_pass retry=3
+password sufficient pam_unix.so sha512 shadow nullok try_first_pass use_authtok
+<userinput>password sufficient pam_sss.so use_authtok</userinput>
+password required pam_deny.so
+
+session optional pam_keyinit.so revoke
+session required pam_limits.so
+session [success=1 default=ignore] pam_succeed_if.so service in crond quiet use_uid
+<userinput>session sufficient pam_sss.so</userinput>
+session required pam_unix.so
+</programlisting>
+ <para>
+ These modules can be set to <literal>include</literal> statements, as necessary.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Open the <filename>sssd.conf</filename> file.
+ </para>
+
+<screen># vim /etc/sssd/sssd.conf</screen>
+
+ </listitem>
+ <listitem>
+ <para>
+ Make sure that PAM is listed as one of the services that works with SSSD.
+ </para>
+
+<screen>[sssd]
+config_file_version = 2
+reconnection_retries = 3
+sbus_timeout = 30
+services = nss, <userinput>pam</userinput></screen>
+
+ </listitem>
+ <listitem>
+ <para>
+ In the <command>[pam]</command> section, change any of the PAM parameters. These are listed in <xref linkend="tab.pam-sssd" />.
+ </para>
+
+<screen>[pam]
+reconnection_retries = 3
+offline_credentials_expiration = 2
+offline_failed_login_attempts = 3
+offline_failed_login_delay = 5</screen>
+
+ </listitem>
+ <listitem>
+ <para>
+ Restart SSSD.
+ </para>
+<screen>[root at server ~]# service sssd restart</screen>
+ </listitem>
+ </orderedlist>
+ <table id="tab.pam-sssd">
+ <title>SSSD [pam] Configuration Parameters</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>
+ Parameter
+ </entry>
+ <entry>
+ Value Format
+ </entry>
+ <entry>
+ Description
+ </entry>
+
+ </row>
+
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ offline_credentials_expiration </entry><entry>integer
</entry>
- </row>
- <row>
- <entry>
- <command>--disablewinbindusedefaultdomain</command>
- </entry>
- <entry>
- Configures winbind to assume that users with no domain in their usernames are not domain users
+ <entry>
+ Sets how long, in days, to allow cached logins if the authentication provider is offline. This value is measured from the last successful online login. If not specified, this defaults to zero (<literal>0</literal>), which is unlimited.
</entry>
- </row>
- <row>
- <entry>
- <command>--winbindjoin=<replaceable>Administrator</replaceable>
- </command>
- </entry>
- <entry>
- Joins the winbind domain or ADS realm as the specified administrator
+
+ </row>
+ <row>
+ <entry>
+ offline_failed_login_attempts </entry><entry>integer
</entry>
- </row>
- <row>
- <entry>
- <command>--enablewinbindoffline</command>
- </entry>
- <entry>
- Configures winbind to allow offline login
+ <entry>
+ Sets how many failed login attempts are allowed if the authentication provider is offline. If not specified, this defaults to zero (<literal>0</literal>), which is unlimited.
</entry>
- </row>
- <row>
- <entry>
- <command>--disablewinbindoffline</command>
- </entry>
- <entry>
- Configures winbind to prevent offline login
- </entry>
- </row>
- <row>
- <entry>
- <command>--smbsecurity=<replaceable>user|server|domain|ads</replaceable></command>
- </entry>
- <entry>
- Security mode to use for the Samba and Winbind services
- </entry>
- </row>
- <row>
- <entry>
- <command>--smbrealm=<replaceable>realm</replaceable></command>
- </entry>
- <entry>
- Default realm for Samba and Winbind services when <guilabel>security</guilabel> is set to <guimenuitem>ads</guimenuitem>
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablewins</command>
- </entry>
- <entry>
- Enable Wins for hostname resolution
- </entry>
- </row>
- <row>
- <entry>
- <command>--disablewins</command>
- </entry>
- <entry>
- Disable Wins for hostname resolution
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablesssd</command>
- </entry>
- <entry>
- Enable SSSD for user information
- </entry>
- </row>
- <row>
- <entry>
- <command>--disablesssd</command>
- </entry>
- <entry>
- Disable SSSD for user information
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablecache</command>
- </entry>
- <entry>
- Enable <command>nscd</command>
- </entry>
- </row>
- <row>
- <entry>
- <command>--disablecache</command>
- </entry>
- <entry>
- Disable <command>nscd</command>
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablelocauthorize</command>
- </entry>
- <entry>
- Local authorization is sufficient for local users
- </entry>
- </row>
- <row>
- <entry>
- <command>--disablelocauthorize</command>
- </entry>
- <entry>
- Local users are also authorized through a remote service
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablesysnetauth</command>
- </entry>
- <entry>
- Authenticate system accounts with network services
- </entry>
- </row>
- <row>
- <entry>
- <command>--disablesysnetauth</command>
- </entry>
- <entry>
- Authenticate system accounts with local files only
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablepamaccess</command>
- </entry>
- <entry>
- Check <filename>/etc/security/access.conf</filename> during account authorization
- </entry>
- </row>
- <row>
- <entry>
- <command>--disablepamaccess</command>
- </entry>
- <entry>
- Do not check <filename>/etc/security/access.conf</filename> during account authorization
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablemkhomedir</command>
- </entry>
- <entry>
- Create a home directory for a user on the first login
- </entry>
- </row>
- <row>
- <entry>
- <command>--disablemkhomedir</command>
- </entry>
- <entry>
- Do not create a home directory for a user on the first login
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablesmartcard</command>
- </entry>
- <entry>
- Enable authentication with a smart card
- </entry>
- </row>
- <row>
- <entry>
- <command>--disablesmartcard</command>
- </entry>
- <entry>
- Disable authentication with a smart card
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablerequiresmartcard</command>
- </entry>
- <entry>
- Require smart card for authentication
- </entry>
- </row>
- <row>
- <entry>
- <command>--disablerequiresmartcard</command>
- </entry>
- <entry>
- Do not require smart card for authentication
- </entry>
- </row>
- <row>
- <entry>
- <command>--smartcardmodule=<replaceable>module</replaceable></command>
- </entry>
- <entry>
- Default smart card module to use
- </entry>
- </row>
- <row>
- <entry>
- <command>--smartcardaction=<replaceable>0=Lock|1=Ignore</replaceable></command>
- </entry>
- <entry>
- Action to be taken when smart card removal is detected
- </entry>
- </row>
- <row>
- <entry>
- <command>--enablefingerprint</command>
- </entry>
- <entry>
- Enable fingerprint authentication
- </entry>
- </row>
- <row>
- <entry>
- <command>--disablefingerprint</command>
- </entry>
- <entry>
- Disable fingerprint authentication
- </entry>
- </row>
- <row>
- <entry>
- <command>--nostart</command>
- </entry>
- <entry>
- Do not start or stop the <command>portmap</command>, <command>ypbind</command>, or <command>nscd</command> services even if they are configured
- </entry>
- </row>
- <row>
- <entry>
- <command>--test</command>
- </entry>
- <entry>
- Do not update the configuration files, only print the new settings
- </entry>
- </row>
- <row>
- <entry>
- <command>--update, --kickstart</command>
- </entry>
- <entry>
- Opposite of <command>--test</command>, update configuration files with changed settings
- </entry>
- </row>
- <row>
- <entry>
- <command>--updateall</command>
- </entry>
- <entry>
- Update all configuration files
- </entry>
- </row>
- <row>
- <entry>
- <command>--probe</command>
- </entry>
- <entry>
- Probe and display network defaults
+
+ </row>
+ <row>
+ <entry>
+ offline_failed_login_delay </entry><entry>integer
</entry>
- </row>
- <row>
- <entry>
- <command>--savebackup=<replaceable>name</replaceable></command>
- </entry>
- <entry>
- Save a backup of all configuration files
- </entry>
- </row>
- <row>
- <entry>
- <command>--restorebackup=<replaceable>name</replaceable></command>
- </entry>
- <entry>
- Restore a backup of all configuration files
- </entry>
- </row>
- <row>
- <entry>
- <command>--restorelastbackup</command>
- </entry>
- <entry>
- Restore the backup of configuration files saved before the previous configuration change
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- </section>
-
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="SSSD.xml" />
+ <entry>
+ Sets how long to prevent login attempts if a user hits the failed login attempt limit.
+ If set to zero (<literal>0</literal>), the user cannot authenticate while the provider is offline once he hits the failed attempt limit. Only a successful online authentication can re-enable offline authentication. If not specified, this defaults to five (<literal>5</literal>).
+ </entry>
+
+ </row>
+ </tbody>
+
+ </tgroup>
+
+ </table>
+
+ </section>
+
+
+ </section>
+
+ <section id="Configuring_Domains">
+ <title>Creating Domains</title>
+ <para>
+ SSSD recognizes <emphasis>domains</emphasis>, which are associated with the different identity servers. Domains are a combination of an identity provider and an authentication method. SSSD works with LDAP identity providers (including OpenLDAP, Red Hat Directory Server, and Microsoft Active Directory) and can use native LDAP authentication or Kerberos authentication.
+ </para>
+ <para>
+ As long as they belong to different domains, SSSD can recognize different users with the same username. For example, SSSD can successfully authenticate both <systemitem>jsmith</systemitem> in the <systemitem>ldap.example.com</systemitem> domain and <systemitem class="username">jsmith</systemitem> in the <systemitem>ldap.otherexample.com</systemitem> domain. SSSD allows requests using fully-qualified domain names, so requesting information for <systemitem>jsmith at ldap.example.com</systemitem> returns the proper user account. Specifying only the username returns the user for whichever domain comes first in the lookup order.
+ </para>
+ <note>
+ <title>Tip</title>
+ <para>
+ SSSD has a <option>filter_users</option> option, which excludes the specified users from being returned in a search.
+ </para>
+
+ </note>
+ <para>
+ Configuring a domain defines both <emphasis>where</emphasis> user information is stored and <emphasis>how</emphasis> those users are allowed to authenticate to the system. The possible combinations are listed in <xref linkend="tab.domain-combo" />.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <xref linkend="Configuring_Domains-Domain_Configuration_Options" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref linkend="Configuring_Domains-Configuring_a_Native_LDAP_Domain" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref linkend="Configuring_Domains-Setting_up_Kerberos_Authentication" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref linkend="Domain_Configuration_Options-Configuring_a_Proxy_Domain" />
+ </para>
+ </listitem>
+ </itemizedlist>
+ <table id="tab.domain-combo"><title>Identity Store and Authentication Type Combinations</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ Identification Provider
+ </entry>
+ <entry>
+ Authentication Provider
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ LDAP
+ </entry>
+ <entry>
+ LDAP
+ </entry>
+ </row>
+ <row>
+ <entry>
+ LDAP
+ </entry>
+ <entry>
+ Kerberos
+ </entry>
+ </row>
+ <row>
+ <entry>
+ proxy
+ </entry>
+ <entry>
+ LDAP
+ </entry>
+ </row>
+ <row>
+ <entry>
+ proxy
+ </entry>
+ <entry>
+ Kerberos
+ </entry>
+ </row>
+ <row>
+ <entry>
+ proxy
+ </entry>
+ <entry>
+ proxy
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+
+
+ <section id="Configuring_Domains-Domain_Configuration_Options">
+ <title>General Rules and Options for Configuring a Domain</title>
+ <para>
+ A domain configuration defines the <emphasis>identity provider</emphasis>, the <emphasis>authentication provider</emphasis>, and
+ any specific configuration to access the information in those providers. There are two types of identity providers
+ — LDAP and proxy —three types of authentication providers — LDAP, Kerberos, and proxy. The identity and authentication
+ providers can be configured in any combination in a domain entry.
+ </para>
+ <para>
+ Along with the domain entry itself, the domain name must be added to the list of domains that SSSD will query. For example:
+ </para>
+<screen>domains = LOCAL,<replaceable>Name</replaceable>
+
+[domain/<replaceable>Name</replaceable>]
+id_provider = <replaceable>type</replaceable>
+auth_provider = <replaceable>type</replaceable>
+<replaceable>provider_specific = value</replaceable>
+<replaceable>global = value</replaceable></screen>
+ <para>
+ <emphasis>global</emphasis> attributes are available to any type of domain, such as cache and time out settings. Each identity and authentication
+ provider has its own set of required and optional configuration parameters.
+ </para>
+
+ <table id="tab.sss-general-config">
+ <title>General [domain] Configuration Parameters</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>
+ Parameter
+ </entry>
+ <entry>
+ Value Format
+ </entry>
+ <entry>
+ Description
+ </entry>
+
+ </row>
+
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ id_provider </entry><entry>string
+ </entry>
+ <entry>
+ Specifies the data provider identity backend to use for this domain. The supported identity backends are:
+ <itemizedlist>
+ <listitem>
+ <para>
+ ldap
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ ipa, compatible with FreeIPA version 2.x and Identity Management in &MAJOROS;
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ proxy for a legacy NSS provider, such as <systemitem>nss_nis</systemitem>. Using a proxy ID provider
+ also requires specifying the legacy NSS library to load to start successfully, set in the
+ <option>proxy_lib_name</option> option.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ local, the SSSD internal local provider
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ auth_provider </entry><entry>string
+ </entry>
+ <entry>
+ Sets the authentication provider used for the domain. The default value for this option is the value of <option>id_provider</option>.
+ The supported authentication providers are ldap, ipa, krb5 (Kerberos), proxy, and none.
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ min_id,max_id </entry><entry>integer
+ </entry>
+ <entry>
+ <emphasis>Optional.</emphasis> Specifies the UID and GID range for the domain. If a domain contains entries that are outside that range, they are ignored.
+ The default value for <option>min_id</option> is <literal>1</literal>; the default value for <option>max_id</option> is <literal>0</literal>, which is unlimited.
+ <important>
+ <para>
+ The default <option>min_id</option> value is the same for all types of identity provider. If LDAP directories are using UID numbers that start at one, it could cause conflicts with users in the local <filename>/etc/passwd</filename> file. To avoid these conflicts, set <option>min_id</option> to <literal>1000</literal> or higher as possible.
+ </para>
+ </important>
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ enumerate </entry><entry>Boolean
+ </entry>
+ <entry>
+ <emphasis>Optional.</emphasis> Specifies whether to list the users and groups of a domain.
+ Enumeration means that the entire set of available users and groups on the remote source is cached on the local machine. When enumeration is disabled, users and groups are only cached as they are requested.
+ <warning>
+ <para>
+ When enumeration is enabled, reinitializing a client results in a complete refresh of the entire set of available users and groups from the remote source. Similarly, when SSSD is connected to a new server, the entire set of available users and groups from the remote source is pulled and cached on the local machine. In a domain with a large number of clients connected to a remote source, this refresh process can harm the network performance because of frequent queries from the clients. If the set of available users and groups is large enough, it degrades client performance as well.
+ </para>
+
+ </warning>
+ The default value for this parameter is <literal>false</literal>, which disables enumeration.
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ cache_credentials </entry><entry>Boolean
+ </entry>
+ <entry>
+ <emphasis>Optional.</emphasis> Specifies whether to store user credentials in the local SSSD domain database cache.
+ The default value for this parameter is <literal>false</literal>. Set this value to <literal>true</literal> for domains other than the LOCAL domain to enable offline authentication.
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ entry_cache_timeout </entry><entry>integer
+ </entry>
+ <entry>
+ <emphasis>Optional.</emphasis> Specifies how long, in seconds, SSSD should cache <emphasis>positive</emphasis> cache hits. A positive cache hit is a successful query.
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ use_fully_qualified_names </entry><entry>Boolean
+ </entry>
+ <entry>
+ <emphasis>Optional.</emphasis> Specifies whether requests to this domain require fully-qualified domain names.
+ If set to <literal>true</literal>, all requests to this domain must use fully-qualified domain names. It also means that the output from the request displays the fully-qualified name.
+ Restricting requests to fully-qualified user names allows SSSD to differentiate between domains with users with conflicting usernames.
+ <para>
+ If <parameter>use_fully_qualified_names</parameter> is set to <literal>false</literal>, it is possible to use the fully-qualified name in the requests, but only the simplified version is displayed in the output.
+ </para>
+ <para>
+ SSSD can only parse names based on the domain name, not the realm name. The same name can be used for both domains and realms, however.
+ </para>
+ </entry>
+
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </section>
+
+ <section id="Configuring_Domains-Configuring_a_Native_LDAP_Domain">
+ <title>Configuring an LDAP Domain</title>
+ <indexterm>
+ <primary>SSSD</primary>
+ <secondary>LDAP domain</secondary>
+ </indexterm>
+ <para>
+ An LDAP domain simply means that SSSD uses an LDAP directory as the identity provider (and, optionally, also as an
+ authentication provider). SSSD supports several major directory services:
+ </para>
+ <indexterm>
+ <primary>SSSD</primary>
+ <secondary>LDAP domain</secondary>
+ <tertiary>supported LDAP directories</tertiary>
+ </indexterm>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Red Hat Directory Server
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ OpenLDAP
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Microsoft Active Directory 2008, with Subsystem for UNIX-based Applications
+ </para>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <para>
+ DNS service discovery allows the LDAP backend to find the appropriate DNS servers to connect to automatically using a special DNS query.
+ </para>
+
+ </note>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <xref linkend="ldap-domain-param" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref linkend="ldap-domain-example" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref linkend="ad2008-example" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref linkend="sssd-ldap-domain-ip" />
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <section id="ldap-domain-param"><title>Parameters for Configuring an LDAP Domain</title>
+ <para>
+ An LDAP directory can function as both an identity provider and an authentication provider. The configuration requires enough information
+ to identify and connect to the user directory in the LDAP server, but the way that those connection parameters are defined is flexible.
+ </para>
+ <para>
+ Other options are available to provide more fine-grained control, like
+ specifying a user account to use to connect to the LDAP server or using different LDAP servers for password operations. The most common
+ options are listed in <xref linkend="tab.sss-ldap-config" />. All of the options listed in <xref linkend="Configuring_Domains-Domain_Configuration_Options" />
+ are also available for LDAP domains.
+ </para>
+ <note><title>Tip</title>
+ <para>
+ Many other options are listed in the man page for LDAP domain configuration, <filename>sssd-ldap(5)</filename>.
+ </para>
+ </note>
+
+ <table id="tab.sss-ldap-config">
+ <title>LDAP Domain Configuration Parameters</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ Parameter
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ ldap_uri
+ </entry>
+ <entry>
+ Gives a comma-separated list of the URIs of the LDAP servers to which SSSD will connect. The list is given in order of preference, so the first server in the list is tried first. Listing additional servers provides failover protection. This can be detected from the DNS SRV records if it is not given.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ ldap_search_base
+ </entry>
+ <entry>
+ Gives the base DN to use for performing LDAP user operations.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ ldap_tls_reqcert
+ </entry>
+ <entry>
+ Specifies how to check for SSL server certificates in a TLS session. There are four options:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>never</emphasis> disables requests for certificates.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>allow</emphasis> requests a certificate, but proceeds normally even if no certificate is given or a bad certificate is given.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>try</emphasis> requests a certificate and proceeds normally if no certificate is given, If a bad certificate is given, the session terminates.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>demand</emphasis> and <emphasis>hard</emphasis> are the same option. This requires a valid certificate or the session is terminated.
+ </para>
+ </listitem>
+ </itemizedlist>
+ The default is <emphasis>hard</emphasis>.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ ldap_tls_cacert
+ </entry>
+ <entry>
+ Gives the full path and file name to the file that contains the CA certificates for all of the CAs that SSSD recognizes. SSSD will accept any certificate issued by these CAs.
+ <para>
+ This uses the OpenLDAP system defaults if it is not given explicitly.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ ldap_referrals
+ </entry>
+ <entry>
+ Sets whether SSSD will use LDAP referrals, meaning forwarding queries from one LDAP database to another. SSSD supports database-level and subtree referrals. For referrals within the same LDAP server, SSSD will adjust the DN of the entry being queried. For referrals that go to different LDAP servers, SSSD does an exact match on the DN. Setting this value to <literal>true</literal> enables referrals; this is the default.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ ldap_schema
+ </entry>
+ <entry>
+ Sets what version of schema to use when searching for user entries. This can be either <literal>rfc2307</literal> or <literal>rfc2307bis</literal>. The default is <literal>rfc2307</literal>.
+ <para>
+ In RFC 2307, group objects use a multi-valued attribute, <parameter>memberuid</parameter>, which lists the names of the users that belong to that group. In RFC 2307bis, group objects use the <parameter>member</parameter> attribute, which contains the full distinguished name (DN) of a user or group entry. RFC 2307bis allows nested groups usning the <parameter>member</parameter> attribute. Because these different schema use different definitions for group membership, using the wrong LDAP schema with SSSD can affect both viewing and managing network resources, even if the appropriate permissions are in place.
+ </para>
+ <para>
+ For example, with RFC 2307bis, all groups are returned when using nested groups or primary/secondary groups.
+ </para>
+
+<screen>$ id
+uid=500(myserver) gid=500(myserver) groups=500(myserver),510(myothergroup)
+</screen>
+ <para>
+ If SSSD is using RFC 2307 schema, only the primary group is returned.
+ </para>
+ <para>
+ This setting only affects how SSSD determines the group members. It does not change the actual user data.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ ldap_search_timeout
+ </entry>
+ <entry>
+ Sets the time, in seconds, that LDAP searches are allowed to run before they are canceled and cached results are returned. This defaults to five when the <option>enumerate</option> value is false and defaults to 30 when <option>enumerate</option> is true.
+ <para>
+ When an LDAP search times out, SSSD automatically switches to offline mode.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ ldap_network_timeout
+ </entry>
+ <entry>
+ Sets the time, in seconds, SSSD attempts to poll an LDAP server after a connection attempt fails. The default is six seconds.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ ldap_opt_timeout
+ </entry>
+ <entry>
+ Sets the time, in seconds, to wait before aborting synchronous LDAP operations if no response is received from the server. This option also controls the timeout when communicating with the KDC in case of a SASL bind. The default is five seconds.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ <section id="ldap-domain-example"><title>LDAP Domain Example</title>
+ <para>
+ The LDAP configuration is very flexible, depending on your specific environment and the SSSD behavior. These are some common examples of an LDAP domain, but the SSSD configuration is not limited to these examples.
+ </para>
+ <note>
+ <para>
+ Along with creating the domain entry, add the new domain to the list of domains for SSSD to query in the <filename>sssd.conf</filename> file. For example:
+ </para>
+<screen>domains = LOCAL,LDAP1,AD,PROXYNIS</screen>
+ </note>
+ <example id="ex.basic-ldap-domain"><title>A Basic LDAP Domain Configuration</title>
+ <para>
+ An LDAP domain requires three things:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ An LDAP server
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The search base
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A way to establish a secure connection
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ The last item depends on the LDAP environment. SSSD requires a secure connection since it handles sensitive information. This connection can be
+ a dedicated TLS/SSL connection or it can use Start TLS.
+ </para>
+ <para>
+ Using a dedicated TLS/SSL connection simply uses an LDAPS connection to connect to the server and is therefore set as part of the <option>ldap_uri</option>
+ option:
+ </para>
+<screen># An LDAP domain
+[domain/LDAP]
+enumerate = false
+cache_credentials = true
+
+id_provider = ldap
+auth_provider = ldap
+
+ldap_uri = ldaps://ldap.example.com:636
+ldap_search_base = dc=example,dc=com
+</screen>
+ <para>
+ Using Start TLS requires a way to input the certificate information to establish a secure connection dynamically over an insecure port. This is done using
+ the <option>ldap_id_use_start_tls</option> option to use Start TLS and then <option>ldap_tls_cacert</option> to identify the CA certificate which issued the
+ SSL server certificates.
+ </para>
+<screen># An LDAP domain
+[domain/LDAP]
+enumerate = false
+cache_credentials = true
+
+id_provider = ldap
+auth_provider = ldap
+
+ldap_uri = ldap://ldap.example.com
+ldap_search_base = dc=example,dc=com
+ldap_id_use_start_tls = true
+ldap_tls_reqcert = demand
+ldap_tls_cacert = /etc/pki/tls/certs/ca-bundle.crt
+</screen>
+ </example>
+ </section>
+
+ <section id="ad2008-example"><title>Active Directory Domain Example</title>
+
+ <indexterm>
+ <primary>SSSD</primary>
+ <secondary>Microsoft Active Directory Domain</secondary>
+
+ </indexterm>
+ <para>
+ For SSSD to work with an Active Directory domain, both the Active Directory domain and the local system have to be configured specially to communicate with one another.
+ </para>
+ <note>
+ <para>
+ The Microsoft Active Directory documentation has complete procedures for configuring the Active Directory domain.
+ </para>
+ </note>
+ <orderedlist>
+ <listitem>
+ <para>
+ Using <command>authconfig</command>, set the Linux client to use Active Directory as its LDAP identity provider. For example:
+ </para>
+<screen>authconfig --enableldap --enableldapauth --ldapserver=ldap://ad.example.com:389 --enablekrb5 --krb5realm AD-REALM.EXAMPLE.COM --krb5kdc ad-kdc.example.com:88 --krb5adminserver ad-kdc.example.com:749 --update</screen>
+ <para>
+ The <command>authconfig</command> command is described in <xref linkend="sect-The_Authentication_Configuration_Tool" />.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create the Active Directory Domain Services role.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the Identity Management for UNIX service to the Active Directory Domain Services role. Use the Unix NIS domain as the domain name in the configuration.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ On the Active Directory server, create a new <guilabel>Computer</guilabel> object with the name of the Linux client.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ In the <guilabel>Administrative Tools</guilabel> menu, select the <guilabel>Active Directory Users and Computers</guilabel> application.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Expand the Active Directory root object, such as <command>ad.example.com</command>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Right-click <guilabel>Computers</guilabel>, and select the <guimenu>New</guimenu> and the <guimenuitem>Computer</guimenuitem> item.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Enter the name for the Linux client, such as <command>rhel-server</command>, and click <guibutton>OK</guibutton>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Expand the <guilabel>Computers</guilabel> object.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Right-click the <command>rhel-server</command> object, and select <guimenuitem>Properties</guimenuitem>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In the <guilabel>UNIX Attributes</guilabel>, enter the name of the Linux NIS domain and the IP address of the Linux server.
+ </para>
+ <para>
+ Click <guibutton>OK</guibutton>.
+ </para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem>
+ <para>
+ From the command prompt on the Active Directory server, create a machine account, password, and UPN for the Linux host principal.
+ </para>
+<screen>C:\> setspn -A host/rhel-server.example.com at AD-REALM.EXAMPLE.COM rhel-server
+Registering ServicePrincipalNames for CN=rhel server,CN=Computers,DC=ad,DC=example,DC=com
+ host/rhel server.example.com at AD-REALM.EXAMPLE.COM
+Updated object
+
+C:\> setspn -L rhel-server
+Registered ServicePrincipalNames for CN=rhel server,CN=Computers,DC=ad,DC=example,DC=com:
+ host/rhel server.example.com at AD-REALM.EXAMPLE.COM
+
+C:\> ktpass /princ host/rhel-server.example.com at AD-REALM.EXAMPLE.COM /out rhel-server.keytab /crypto all /ptype KRB5_NT_PRINCIPAL -desonly /mapuser AD\rhel-server$ +rndPass
+
+Targeting domain controller:
+ ad.example.com
+Using legacy password setting method
+Successfully mapped host/rhel server.redhat.com
+... 8< ...</screen>
+ </listitem>
+ <listitem>
+ <para>
+ Copy the keytab from the Active Directory server to the Linux client, and save it as <filename>/etc/krb5.keytab</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ On the Linux system, reset the permissions and owner for the keytab file.
+ </para>
+<screen>[root at rhel-server ~]# chown root:root /etc/krb5.keytab
+
+[root at rhel-server ~]# chmod 0600 /etc/krb5.keytab </screen>
+ </listitem>
+ <listitem>
+ <para>
+ Restore the SELinux file permissions for the keytab.
+ </para>
+<screen>[root at rhel-server ~]# restorecon /etc/krb5.keytab</screen>
+ </listitem>
+ <listitem>
+ <para>
+ Verify that the host can connect to the Active Directory domain.
+ </para>
+<screen>[root at rhel-server ~]# kinit -k -t /etc/krb5.keytab host/rhel-server.example.com at AD-REALM.EXAMPLE.COM</screen>
+ </listitem>
+ <listitem>
+ <para>
+ On the Active Directory server, create a a group for the Linux users.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Create a new group named <emphasis>unixusers</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Open the <guilabel>unixusers</guilabel> group and open the <guilabel>Unix Attributes</guilabel> tab.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Configure the Unix settings:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The NIS domain
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The UID
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The login shell, to <command>/bin/bash</command>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The home directory, to <command>/home/aduser</command>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The primary group name, to <command>unixusers</command>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ <listitem>
+ <para>
+ Then, configure the SSSD domain on the Linux machine.
+ </para>
+ <example id="ex.microstof2008-domain"><title>An Active Directory 2008 Domain</title>
+<screen>[root at rhel-server ~]# vim /etc/sssd/sssd.conf
+
+[sssd]
+config_file_version = 2
+domains = ad.example.com
+services = nss, pam
+
+[nss]
+
+[pam]
+
+[domain/ad.example.com]
+cache_credentials = true
+enumerate = false
+
+id_provider = ldap
+auth_provider = krb5
+chpass_provider = krb5
+access_provider = ldap
+
+ldap_sasl_mech = GSSAPI
+ldap_sasl_authid = host/rhel-server.example.com at AD-REALM.EXAMPLE.COM
+
+
+ldap_schema = rfc2307bis
+
+ldap_user_search_base = ou=user accounts,dc=ad,dc=example,dc=com
+ldap_user_object_class = user
+ldap_user_home_directory = unixHomeDirectory
+ldap_user_principal = userPrincipalName
+ldap_user_name = sAMAccountName
+
+ldap_group_search_base = ou=groups,dc=ad,dc=example,dc=com
+ldap_group_object_class = group
+
+ldap_access_order = expire
+ldap_account_expire_policy = ad
+ldap_force_upper_case_realm = true
+ldap_disable_referrals = true
+
+#krb5_server = server.ad.example.com
+krb5_realm = AD-REALM.EXAMPLE.COM</screen>
+ </example>
+ <para>
+ These options are described in the man page for LDAP domain configuration, <filename>sssd-ldap(5)</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Restart SSSD.
+ </para>
+<screen>[root at rhel-server ~]# service sssd restart</screen>
+ </listitem>
+ </orderedlist>
+
+
+
+
+ </section>
+ <section id="sssd-ldap-domain-ip"><title>Using IP Addresses in Certificate Subject Names</title>
+ <para>
+ Using an IP address in the <option>ldap_uri</option> option instead of the server name may cause the TLS/SSL connection to fail.
+ TLS/SSL certificates contain the server name, not the IP address. However, the <emphasis>subject alternative name</emphasis>
+ field in the certificate can be used to include the IP address of the server, which allows a successful secure connection using an IP address.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Convert an existing certificate into a certificate request. The signing key (<option>-signkey</option>) is the key of the issuer of whatever CA originally issued the certificate. If this is done by an external CA, it requires a separate PEM file; if the certificate is self-signed, then this is the certificate itself. For example:
+ </para>
+
+<screen>openssl x509 -x509toreq -in old_cert.pem -out req.pem -signkey key.pem</screen>
+ <para>
+ With a self-signed certificate:
+ </para>
+
+<screen>openssl x509 -x509toreq -in old_cert.pem -out req.pem -signkey old_cert.pem</screen>
+
+ </listitem>
+ <listitem>
+ <para>
+ Edit the <filename>/etc/pki/tls/openssl.cnf</filename> configuration file to include the server's IP address under the <parameter>[ v3_ca ]</parameter> section:
+ </para>
+
+<screen>subjectAltName = IP:10.0.0.10</screen>
+ </listitem>
+ <listitem>
+ <para>
+ Use the generated certificate request to generate a new self-signed certificate with the specified IP address:
+ </para>
+
+<screen>openssl x509 -req -in req.pem -out new_cert.pem -extfile ./openssl.cnf -extensions v3_ca -signkey old_cert.pem</screen>
+ <para>
+ The <option>-extensions</option> option sets which extensions to use with the certificate. For this, it should be v3_ca to load the appropriate section.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Copy the private key block from the <filename>old_cert.pem</filename> file into the <filename>new_cert.pem</filename> file to keep all relevant information in one file.
+ </para>
+
+ </listitem>
+
+ </orderedlist>
+
+ <para>
+ When creating a certificate through the <application>certutil</application> utility provided by the <filename>nss-utils</filename> package, note that <application>certutil</application> supports DNS subject alternative names for certificate creation only.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="Configuring_Domains-Setting_up_Kerberos_Authentication">
+ <title>Configuring Kerberos Authentication with a Domain</title>
+ <indexterm>
+ <primary>SSSD</primary>
+ <secondary>Kerberos authentication</secondary>
+
+ </indexterm>
+ <para>
+ Both LDAP and proxy identity providers can use a separate Kerberos domain to supply authentication. Configuring a Kerberos
+ authentication provider requires the <firstterm>key distribution center</firstterm> (KDC) and the Kerberos domain. All of the principal
+ names must be available in the specified identity provider; if they are not, SSSD constructs the principals using the format
+ <emphasis>username at REALM</emphasis>.
+ </para>
+ <note>
+ <para>
+ Kerberos can only provide authentication; it cannot provide an identity database.
+ </para>
+ </note>
+ <para>
+ SSSD assumes that the Kerberos KDC is also a Kerberos kadmin server. However, production environments commonly have multiple, read-only replicas of the KDC and only a single kadmin server. Use the <option>krb5_kpasswd</option> option to specify where the password changing service is running or if it is running on a non-default port. If the <option>krb5_kpasswd</option> option is not defined, SSSD tries to use the Kerberos KDC to change the password.
+ </para>
+ <para>
+ The basic Kerberos configuration options are listed in <xref linkend="tab.sssd-krb-params" />. The <filename>sssd-krb5(5)</filename> man page has more information about Kerberos configuration options.
+ </para>
+ <example id="ex.sssd-krbauth"><title>Basic Kerberos Authentication</title>
+<screen># A domain with identities provided by LDAP and authentication by Kerberos
+[domain/KRBDOMAIN]
+enumerate = false
+id_provider = ldap
+chpass_provider = krb5
+ldap_uri = ldap://ldap.example.com
+ldap_search_base = dc=example,dc=com
+ldap-tls_reqcert = demand
+ldap_tls_cacert = /etc/pki/tls/certs/ca-bundle.crt
+
+auth_provider = krb5
+krb5_server = 192.168.1.1, kerberos.example.com
+krb5_realm = EXAMPLE.COM
+krb5_kpasswd = kerberos.admin.example.com
+krb5_auth_timeout = 15
+</screen>
+ </example>
+
+ <table id="tab.sssd-krb-params">
+ <title>Kerberos Authentication Configuration Parameters</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ Parameter
+ </entry>
+ <entry>
+ Description
+ </entry>
+
+ </row>
+
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ chpass_provider
+ </entry>
+ <entry>
+ Specifies which service to use for password change operations. This is assumed to be the same as the authentication provider. To use Kerberos, set this to <emphasis>krb5</emphasis>.
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ krb5_server
+ </entry>
+ <entry>
+ Gives a comma-separated list of IP addresses or hostnames of Kerberos servers to which SSSD will connect. The list is given in order of preference, so the first server in the list is tried first. Listing additional servers provides failover protection.
+ <para>
+ When using service discovery for KDC or kpasswd servers, SSSD first searches for DNS entries that specify UDP as the connection protocol, and then falls back to TCP.
+ </para>
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ krb5_realm
+ </entry>
+ <entry>
+ Identies the Kerberos realm served by the KDC.
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ krb5_lifetime
+ </entry>
+ <entry>
+ Requests a Kerberos ticket with the specified lifetime in seconds (s), minutes (m), hours (h) or days (d).
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ krb5_renewable_lifetime
+ </entry>
+ <entry>
+ Requests a renewable Kerberos ticket with a total lifetime that is specified in seconds (s), minutes (m), hours (h) or days (d).
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ krb5_renew_interval
+ </entry>
+ <entry>
+ Sets the time, in seconds, for SSSD to check if tickets should be renewed. Tickets are renewed automatically once they exceed half their lifetime. If this option is missing or set to zero, then automatic ticket renewal is disabled.
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ krb5_store_password_if_offline
+ </entry>
+ <entry>
+ Sets whether to store user passwords if the Kerberos authentication provider is offline, and then to use that cache to request tickets when the provider is back online. The default is <command>false</command>, which does not store passwords.
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ krb5_kpasswd
+ </entry>
+ <entry>
+ Lists alternate Kerberos kadmin servers to use if the change password service is not running on the KDC.
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ krb5_ccname_template
+ </entry>
+ <entry>
+ Gives the directory to use to store the user's credential cache. This can be templatized, and the following tokens are supported:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>%u</emphasis>, the user's login name
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>%U</emphasis>, the user's login UID
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>%p</emphasis>, the user's principal name
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>%r</emphasis>, the realm name
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>%h</emphasis>, the user's home directory
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>%d</emphasis>, the value of the <option>krb5ccache_dir</option> parameter
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>%P</emphasis>, the process ID of the SSSD client.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>%%</emphasis>, a literal percent sign (%)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>XXXXXX</emphasis>, a string at the end of the template which instructs SSSD to create a unique filename safely
+ </para>
+ </listitem>
+ </itemizedlist>
+ For example:
+<screen>krb5_ccname_template = FILE:%d/krb5cc_%U_XXXXXX</screen>
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ krb5_ccachedir
+ </entry>
+ <entry>
+ Specifies the directory to store credential caches. This can be templatized, using the same tokens as <option>krb5_ccname_template</option>, except for <option>%d</option> and <option>%P</option>.
+ If <option>%u</option>, <option>%U</option>, <option>%p</option>, or <option>%h</option> are used, then SSSD creates a private directory for each user; otherwise, it creates a public directory.
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ krb5_auth_timeout
+ </entry>
+ <entry>
+ Gives the time, in seconds, before an online authentication or change password request is aborted. If possible, the authentication request is continued offline. The default is 15 seconds.
+ </entry>
+
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section id="Domain_Configuration_Options-Configuring_a_Proxy_Domain">
+ <title>Configuring a Proxy Domain</title>
+ <indexterm>
+ <primary>SSSD</primary>
+ <secondary>proxy domain</secondary>
+
+ </indexterm>
+ <para>
+ A proxy with SSSD is just a relay, an intermediary configuration. SSSD connects to its proxy service, and then that proxy loads the
+ specified libraries. This allows SSSD to use some resources that it otherwise would not be able to use. For example,
+ SSSD only supports LDAP and Kerberos as authentication providers, but using a proxy allows SSSD to use alternative authentication
+ methods like a fingerprint scanner or smart card.
+ </para>
+
+ <table id="tab.sss-proxy-config">
+ <title>Proxy Domain Configuration Parameters</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ Parameter
+ </entry>
+ <entry>
+ Description
+ </entry>
+
+ </row>
+
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ proxy_pam_target
+ </entry>
+ <entry>
+ Specifies the target to which PAM must proxy as an authentication provider.
+ The PAM target is a file containing PAM stack information in the default PAM directory, <filename>/etc/pam.d/</filename>.
+ <para>
+ This is used to proxy an authentication provider.
+ </para>
+ <important>
+ <para>
+ Ensure that the proxy PAM stack does <emphasis>not</emphasis> recursively include <filename>pam_sss.so</filename>.
+ </para>
+
+ </important>
+ </entry>
+
+ </row>
+ <row>
+ <entry>
+ proxy_lib_name
+ </entry>
+ <entry>
+ Specifies which existing NSS library to proxy identity requests through.
+ <para>
+ This is used to proxy an identity provider.
+ </para>
+ </entry>
+
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <example id="sect-SSSD-proxy-krb5"><title>Proxy Identity and Kerberos Authentication</title>
+ <para>
+ The proxy library is loaded using the <option>proxy_lib_name</option> parameter. This library can be anything as long as it is compatible with the given authentication service. For a Kerberos authentication provider, it must be a Kerberos-compatible library, like NIS.
+ </para>
+
+<screen>
+[domain/PROXY_KRB5]
+auth_provider = krb5
+krb5_server = 192.168.1.1
+krb5_realm = EXAMPLE.COM
+
+id_provider = proxy
+proxy_lib_name = nis
+enumerate = true
+cache_credentials = true</screen>
+ </example>
+
+ <example id="sect-SSSD-LDAP-proxy">
+ <title>LDAP Identity and Proxy Authentication</title>
+ <para>
+ The proxy library is loaded using the <option>proxy_pam_target</option> parameter. This library must be a PAM module that is
+ compatible with the given identity provider. For example, this uses a PAM fingerprint module with LDAP:
+ </para>
+<screen>
+[domain/LDAP_PROXY]
+id_provider = ldap
+ldap_uri = ldap://example.com
+ldap_search_base = dc=example,dc=com
+
+auth_provider = proxy
+proxy_pam_target = sssdpamproxy
+enumerate = true
+cache_credentials = true
+</screen>
+ <para>
+ After the SSSD domain is configured, make sure that the specified PAM files are configured.
+ In this example, the target is <command>sssdpamproxy</command>, so create a <filename>/etc/pam.d/sssdpamproxy</filename> file
+ and load the PAM/LDAP modules:
+ </para>
+
+<screen>
+auth required pam_frprint.so
+account required pam_frprint.so
+password required pam_frprint.so
+session required pam_frprint.so</screen>
+
+ </example>
+
+ <example id="sect-SSSD-proxy-proxy"><title>Proxy Identity and Authentication</title>
+ <para>
+ SSSD can have a domain with both identity and authentication proxies. The only configuration given then are the
+ proxy settings, <option>proxy_pam_target</option> for the authentication PAM module and <option>proxy_lib_name</option>
+ for the service, like NIS or LDAP.
+ </para>
+ <para>
+ <emphasis>This example illustrates a possible configuration, but this is not a realistic configuration. If LDAP is used for identity and authentication, then both the identity and authentication providers should be set to the LDAP configuration, not a proxy.</emphasis>
+ </para>
+
+<screen>
+[domain/PROXY_PROXY]
+auth_provider = proxy
+id_provider = proxy
+proxy_lib_name = ldap
+proxy_pam_target = sssdproxyldap
+enumerate = true
+cache_credentials = true
+</screen>
+ <para>
+ Once the SSSD domain is added, then update the system settings to configure the proxy service:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ Create a <filename>/etc/pam.d/sssdproxyldap</filename> file which requires the <command>pam_ldap.so</command> module:
+ </para>
+
+<screen>
+auth required pam_ldap.so
+account required pam_ldap.so
+password required pam_ldap.so
+session required pam_ldap.so</screen>
+
+ </listitem>
+ <listitem>
+ <para>
+ Make sure the <filename>nss-pam-ldap</filename> package is installed.
+ </para>
+<screen>[root at server ~]# yum install nss-pam-ldap</screen>
+ </listitem>
+ <listitem>
+ <para>
+ Edit the <filename>/etc/nslcd.conf</filename> file, the configuration file for the LDAP name service daemon, to contain the information for the LDAP directory:
+ </para>
+
+<screen>uid nslcd
+gid ldap
+uri ldaps://ldap.example.com:636
+base dc=example,dc=com
+ssl on
+tls_cacertdir /etc/openldap/cacerts</screen>
+
+ </listitem>
+
+ </orderedlist>
+
+ </example>
+
+
+ </section>
+
+
+ </section>
+
+ <section id="config-sssd-domain-access">
+ <title>Configuring Access Control for SSSD Domains</title>
+ <indexterm>
+ <primary>Access Control</primary>
+ <secondary>configuring in SSSD</secondary>
+
+ </indexterm>
+ <para>
+ SSSD provides a rudimentary access control for domain configuration, allowing either simple user allow/deny lists or using the LDAP backend itself.
+ </para>
+ <section id="simple-access">
+ <title>Using the Simple Access Provider</title>
+ <para>
+ The <firstterm>Simple Access Provider</firstterm> allows or denies access based on a list of usernames or groups.
+ </para>
+ <para>
+ The Simple Access Provider is a way to restrict access to certain, specific machines. For example, if a company uses laptops,
+ the Simple Access Provider can be used to restrict access to only a specific user or a specific group, even if a different user authenticated successfully against the same authentication provider.
+ </para>
+ <para>
+ The most common options are
+ <option>simple_allow_users</option> and <option>simple_allow_groups</option>, which grant access explicitly to specific users (either the given users or group members) and deny access to everyone else. It is also possible to create deny lists (which deny access only to explicit people and implicitly allow everyone else access).
+ </para>
+ <indexterm>
+ <primary>Access Control</primary>
+ <secondary>SSSD rules</secondary>
+
+ </indexterm>
+ <para>
+ The Simple Access Provider adheres to the following four rules to determine which users should or should not be granted access:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ If both the allow and deny lists are empty, access is granted.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ If any list is provided, allow rules are evaluated first, and then deny rules. Practically, this means that deny rules supersede allow rules.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ If an allowed list is provided, then all users are denied access unless they are in the list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If only deny lists are provided, then all users are allowed access unless they are in the list.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ This example grants access to two users and anyone who belongs to the IT group; implicitly, all other users are denied:
+ </para>
+
+<screen>[domain/example.com]
+access_provider = simple
+simple_allow_users = jsmith,bjensen
+simple_allow_groups = itgroup</screen>
+ <note>
+ <para>
+ The LOCAL domain in SSSD does not support <option>simple</option> as an access provider.
+ </para>
+
+ </note>
+ <para>
+ Other options are listed in the <filename>sssd-simple</filename> man page, but these are rarely used.
+ </para>
+ </section>
+
+ <section>
+ <title>Using the LDAP Access Filter</title>
+ <para>
+ The LDAP server itself can provide the access control rules. The associated filter option (<option>ldap_access_filter</option>)
+ specifies which users are granted access to the specified host. The user filter must be used or all users are denied access.
+ </para>
+ <para>
+ For example:
+ </para>
+
+<screen>[domain/example.com]
+access_provider = ldap
+ldap_access_filter = memberOf=cn=allowedusers,ou=Groups,dc=example,dc=com</screen>
+ <note>
+ <para>
+ Offline caching for LDAP access providers is limited to determining whether the user's last online login
+ attempt was successful. Users that were granted access during their last login will continue to be granted access while offline.
+ </para>
+
+ </note>
+ <!-- check the sssd-ldap(5) manpage for details -->
+ <para>
+ SSSD can also check results by the account expiration policy and the <parameter>authorizedService</parameter> attribute.
+ </para>
+
+ </section>
+
+
+ </section>
+
+ <section id="Configuring_Failover">
+ <title>Configuring Domain Failover</title>
+ <para>
+ SSSD attempts to connect to machines and to services separately.
+ </para>
+ <para>
+ When SSSD tries to connect to one of its domain backends, it first tries to resolve the hostname of a given machine. If
+ this resolution attempt fails, the machine is considered offline, and SSSD no longer attempts to connect to this machine for any other service.
+ </para>
+ <para>
+ If the resolution attempt succeeds, the backend tries to connect to a service on this machine. If the service connection attempt fails, then only this particular service is considered offline and the backend automatically switches over to the next service. The machine is still considered online and might still be tried for another service.
+ </para>
+ <para>
+ SSSD only tries the first IP address given in the DNS A record. To find multiple servers with a single request, SSSD relies on SRV records.
+ </para>
+ <para>
+ Connections are retried to offline machines or services every 30 seconds, until SSSD can successfully connect to the backend.
+ </para>
+
+
+ <section id="config-failover"><title>Configuring Failover</title>
+ <para>
+ Configuring failover allows SSSD to switch automatically to a different server if the primary server fails. These servers are entered as a case-insensitive, comma-separated list in the <emphasis>[domain/Name]</emphasis> sections of the <filename>/etc/sssd/sssd.conf</filename> file. The servers are listed in order of preference. This list can contain any number of servers.
+ </para>
+ <para>
+ For example, for a native LDAP domain:
+ </para>
+
+<screen>ldap_uri = ldap://ldap0.example.com, ldap://ldap1.example.com, ldap://ldap2.example.com</screen>
+ <para>
+ The first entry, <uri>ldap://ldap0.example.com</uri>, is the primary server. If this server fails, SSSD first attempts to connect to <uri>ldap1.example.com</uri> and then <uri>ldap2.example.com</uri>.
+ </para>
+ <para>
+ If the server parameter is not specified, then SSSD uses service discovery to try to find another server on the network.
+ </para>
+ <important>
+ <para>
+ The failover servers must be entered as a comma-separated list of values for a single key. If there are multiple keys, SSSD only recognizes the last entry.
+ </para>
+ </important>
+ </section>
+
+ <section id="Using_SRV_Records_with_Failover">
+ <title>Using SRV Records with Failover</title>
+ <para>
+ SSSD supports SRV records in its failover configuration. The SSSD configuration can specify a server that is later
+ resolved into a list of specific servers using SRV requests.
+ </para>
+ <para>
+ For every service with which to use service discovery, add a special DNS record to the DNS server:
+ </para>
+
+<screen>_<replaceable>service</replaceable>._<replaceable>protocol</replaceable>._<replaceable>domain TTL priority weight port hostname</replaceable></screen>
+ <para>
+ The <emphasis>priority</emphasis> and <emphasis>weight</emphasis> attributes of SRV records provide fine-grained control
+ over which servers to contact first if the primary server fails.
+ </para>
+ <para>
+ A typical configuration contains multiple such records, each with a different priority for failover and different weights for load balancing.
+ </para>
+ <para>
+ For more information on SRV records, see <ulink url="http://tools.ietf.org/html/rfc2782">RFC 2782</ulink>.
+ </para>
+
+ </section>
+
+ </section>
+
+ <section id="sssd-cache">
+ <title>Managing the SSSD Cache</title>
+ <para>
+ SSSD can define multiple domains of the same type and different types of domain.
+ SSSD maintains a separate database file for each domain, meaning each domain has its own
+ cache. These cache files are stored in the <filename>/var/lib/sss/db/</filename> directory.
+ </para>
+
+ <section id="sssd-cache-purge"><title>Purging the SSSD Cache</title>
+ <para>
+ As LDAP updates are made to the identity provider for the domains, it can be necessary to clear the cache to reload the new information quickly.
+ </para>
+ <para>
+ The cache purge utility, <command>sss_cache</command>, invalidates records in the SSSD cache for a user, a domain, or a group. Invalidating the current records forces the cache to retrieve the updated records from the identity provider, so changes can be realized quickly.
+ </para>
+ <para>
+ Most commonly, this is used to clear the cache and update the records for an entire domain:
+ </para>
+ <example id="ex.sssd-purge-domain"><title>Purging Domain Records</title>
+<programlisting language="Bash">[root at server ~]# sss_cache -d LDAP1</programlisting>
+ </example>
+ <para>
+ If the administrator knows that a specific record (user, group, or netgroup) has been updated, then <command>sss_cache</command> can purge the records for that specific account, and leave the rest of the cache intact.
+ </para>
+ <example id="ex.sssd-purge-user"><title>Purging a User Record</title>
+<programlisting language="Bash">[root at server ~]# sss_cache -u jsmith</programlisting>
+ </example>
+ <table id="tab.sss_cache-options"><title>sss_cache Options</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>
+ Short Argument
+ </entry>
+ <entry>
+ Long Argument
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ -d <emphasis>name</emphasis>
+ </entry>
+ <entry>
+ --domain <emphasis>name</emphasis>
+ </entry>
+ <entry>
+ Invalidates cache entries for users, groups, and other entries only within the specified domain.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ -G
+ </entry>
+ <entry>
+ --groups
+ </entry>
+ <entry>
+ Invalidates all group records. If <option>-g</option> is also used, <option>-G</option> takes precedence and <option>-g</option> is ignored.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ -g <emphasis>name</emphasis>
+ </entry>
+ <entry>
+ --group <emphasis>name</emphasis>
+ </entry>
+ <entry>
+ Invalidates the cache entry for the specified group.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ -N
+ </entry>
+ <entry>
+ --netgroups
+ </entry>
+ <entry>
+ Invalidates cache entries for all netgroup cache records. If <option>-n</option> is also used, <option>-N</option> takes precedence and <option>-n</option> is ignored.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ -n <emphasis>name</emphasis>
+ </entry>
+ <entry>
+ --netgroup <emphasis>name</emphasis>
+ </entry>
+ <entry>
+ Invalidates the cache entry for the specified netgroup.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ -U
+ </entry>
+ <entry>
+ --users
+ </entry>
+ <entry>
+ Invalidates cache entries for all user records. If the <option>-u</option> option is also used, <option>-U</option> takes precedence and <option>-u</option> is ignored.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ -u <emphasis>name</emphasis>
+ </entry>
+ <entry>
+ --user <emphasis>name</emphasis>
+ </entry>
+ <entry>
+ Invalidates the cache entry for the specified user.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section id="domain-sssd-delete-cache"><title>Deleting Domain Cache Files</title>
+ <para>
+ All cache files are named for the domain. For example, for a domain named <command>exampleldap</command>, the
+ cache file is named <filename>cache_exampleldap.ldb</filename>.
+ </para>
+ <indexterm>
+ <primary>deleting cache files</primary>
+ <secondary>in SSSD</secondary>
+
+ </indexterm>
+ <para>
+ <emphasis role="bold">Be careful when you delete a cache file.</emphasis> This operation has significant effects:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Deleting the cache file deletes all user data, both identification and cached credentials. Consequently, do not delete a cache file unless the system is online and can authenticate with a username against the domain's servers. Without a credentials cache, offline authentication will fail.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ If the configuration is changed to reference a different identity provider, SSSD will recognize users from both providers until the cached entries from the original provider time out.
+ </para>
+ <para>
+ It is possible to avoid this by purging the cache, but the better option is to use a different domain name for the new provider. When SSSD is restarted, it creates a new cache file with the new name and the old file is ignored.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+ </section>
+
+ <section id="openssh-sssd"><title>Configuring OpenSSH to Check SSSD for Cached Keys (TECH PREVIEW)</title>
+ <para>
+ OpenSSH creates secure, encrypted connections between two systems. One machine authenticates to another machine to allow access; the authentication can be of the machine itself for server connections or of a user on that machine. OpenSSH is described in more detail in <xref linkend="ch-OpenSSH" />.
+ </para>
+ <para>
+ This authentication is performed through <emphasis>public-private key pairs</emphasis> that identify the authenticating user or machine. The remote machine or user attempting to access the machine presents a key pair. The local machine then elects whether to trust that remote entity; if it is trusted, the public key for that remote machine is stored in the <filename>known_hosts</filename> file or for the remote user in <filename>authorized_keys</filename>. Whenever that remote machine or user attempts to authenticate again, the local system simply checks the <filename>known_hosts</filename> or <filename>authorized_keys</filename> file first to see if that remote entity is recognized and trusted. If it is, then access is granted.
+ </para>
+ <para>
+ The first problem comes in verifying those identities reliably.
+ </para>
+ <para>
+ The <filename>known_hosts</filename> file is a triplet of the machine name, its IP address, and its public key:
+ </para>
+<screen>server.example.com,255.255.255.255 ssh-rsa AbcdEfg1234ZYX098776/AbcdEfg1234ZYX098776/AbcdEfg1234ZYX098776=</screen>
+ <para>
+ The <filename>known_hosts</filename> file can quickly become outdated for a number of different reasons: systems using DHCP cycle through IP addresses, new keys can be re-issued periodically, or virtual machines or services can be brought online and removed. This changes the hostname, IP address, and key triplet.
+ </para>
+ <para>
+ Administrators have to clean and maintain a current <filename>known_hosts</filename> file to maintain security. (Or system users get in the habit of simply accepting any machine and key presented, which negates the security benefits of key-based security.)
+ </para>
+ <para>
+ Additionally, problem for both machines and users is distributing keys in a scalable way. Machines can send their keys are part of establishing an encrypted session, but users have to supply their keys in advance. Simply propagating and then updating keys consistently is a difficult administrative task.
+ </para>
+ <para>
+ Lastly, SSH key and machine information are only maintained locally. There may be machines or users on the network which are recognized and trusted by some systems and not by others because the <filename>known_hosts</filename> file has not been updated uniformly.
+ </para>
+ <para>
+ The goal of SSSD is to server as a credentials cache. This includes working as a credentials cache for SSH public keys for machines and users. OpenSSH is configured to reference SSSD to check for cached keys; SSSD uses Red Hat Linux's Identity Management (IPA) domain as an identity, and IPA actually stores the public keys and host information.
+ </para>
+ <note><title>NOTE</title>
+ <para>
+ Only Linux machines enrolled, or joined, in the IPA domain can use SSSD as a key cache for OpenSSH. Other Unix machines and Windows machines must use the regular authentication mechanisms with the <filename>known_hosts</filename> file.
+ </para>
+ </note>
+ <section id="openssh-sssd-hosts"><title>Configuring OpenSSH to Use SSSD for Host Keys</title>
+ <para>
+ OpenSSH is configured in either a user-specific configuration file (<filename>~/.ssh/config</filename>) or a system-wide configuration file (<filename>/etc/ssh/ssh_config</filename>). The user file has precedence over the system settings and the first obtained value for a paramter is used. The formatting and conventions for this file are covered in <xref linkend="ch-OpenSSH" />.
+ </para>
+ <para>
+ In order to manage host keys, SSSD has a tool, <command>sss_ssh_knownhostsproxy</command>, which performs three operations:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Retrieves the public host key from the enrolled Linux system.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Stores the host key in a custom hosts file, <filename>.ssh/sss_known_hosts</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Establishes a connection with the host machine, either a socket (the default) or a secure connection.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ This tool has the format:
+ </para>
+<screen>sss_ssh_knownhostsproxy [-d <replaceable>sssd_domain</replaceable>] [-p <replaceable>ssh_port</replaceable>] <replaceable>HOST</replaceable> [<replaceable>PROXY_COMMAND</replaceable>]</screen>
+ <table id="tab.sss_ssh_knownhostsproxy"><title>sss_ssh_knownhostsproxy Options</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>
+ Short Argument
+ </entry>
+ <entry>
+ Long Argument
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ </entry>
+ <entry>
+ <emphasis>HOSTNAME</emphasis>
+ </entry>
+ <entry>
+ Gives the hostname of the host to check and connect to. In the OpenSSH configuration file, this can be a token, <command>%h</command>.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ </entry>
+ <entry>
+ <emphasis>PROXY_COMMAND</emphasis>
+ </entry>
+ <entry>
+ Passes a proxy command to use to connect to the SSH client. This is similar to running <command>ssh -o ProxyCommand=</command><emphasis>value</emphasis>. This option is used when running <command>sss_ssh_knownhostsproxy</command> from the command line or through another script, but is not necessary in the OpenSSH configuration file.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ -d <emphasis>sssd_domain</emphasis>
+ </entry>
+ <entry>
+ --domain <emphasis>sssd_domain</emphasis>
+ </entry>
+ <entry>
+ Only searches for public keys in entries in the specified domain. If not given, SSSD searches for keys in all configured domains.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ -p <emphasis>port</emphasis>
+ </entry>
+ <entry>
+ --port <emphasis>port</emphasis>
+ </entry>
+ <entry>
+ Uses this port to connect to the SSH client. By default, this is port 22.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ To use this SSSD tool, add or edit two parameters to the <filename>ssh_config</filename> or <filename>~/.ssh/config</filename> file:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Specify the command to use to connect to the SSH client (<command>ProxyCommand</command>). This is the <command>sss_ssh_knownhostsproxy</command>, with the desired arguments and hostname.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Specify the location of the SSSD hosts file, rather than the default <filename>known_hosts</filename> file (<command>UserKnownHostsFile</command>). The SSSD hosts file is <filename>.ssh/sss_known_hosts</filename>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ For example, this looks for public keys in the <command>IPA1</command> SSSD domain and connects over whatever port and host are supplied:
+ </para>
+<screen>ProxyCommand /usr/bin/sss_ssh_knownhostsproxy -p %p -d IPA1 %h
+UserKnownHostsFile2 .ssh/sss_known_hosts</screen>
+ </section>
+ <section id="openssh-sssd-users"><title>Configuring OpenSSH to Use SSSD for User Keys</title>
+ <para>
+ User keys are stored on a local system in the <filename>authorized_keys</filename> file for OpenSSH. As with hosts, SSSD can maintain and automatically update a separate cache of user public keys for OpenSSH to refer to. This is kept in the <filename>.ssh/sss_authorized_keys</filename> file.
+ </para>
+ <para>
+ OpenSSH is configured in either a user-specific configuration file (<filename>~/.ssh/config</filename>) or a system-wide configuration file (<filename>/etc/ssh/ssh_config</filename>). The user file has precedence over the system settings and the first obtained value for a paramter is used. The formatting and conventions for this file are covered in <xref linkend="ch-OpenSSH" />.
+ </para>
+ <para>
+ In order to manage user keys, SSSD has a tool, <command>sss_ssh_authorizedkeys</command>, which performs two operations:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Retrieves the user's public key from the user entries in the Identity Management (IPA) domain.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Stores the user key in a custom file, <filename>.ssh/sss_authorized_keys</filename>, in the standard authorized keys format.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ This tool has the format:
+ </para>
+<screen>sss_ssh_authorizedkeys [-d <replaceable>sssd_domain</replaceable>] <replaceable>USER</replaceable></screen>
+ <table id="tab.sss_ssh_authorizedkeys"><title>sss_ssh_authorizedkeys Options</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>
+ Short Argument
+ </entry>
+ <entry>
+ Long Argument
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ </entry>
+ <entry>
+ <emphasis>USER</emphasis>
+ </entry>
+ <entry>
+ Gives the username or account name for which to obtain the public key. In the OpenSSH configuration file, this can be represented by a token, <command>%u</command>.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ -d <emphasis>sssd_domain</emphasis>
+ </entry>
+ <entry>
+ --domain <emphasis>sssd_domain</emphasis>
+ </entry>
+ <entry>
+ Only searches for public keys in entries in the specified domain. If not given, SSSD searches for keys in all configured domains.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ There are two possible options for how to configure OpenSSH to use SSSD for user keys, depending on the SSH deployment:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Most commonly, SSH supports the authorized key command. In that case, it is necessary only to specify the command to run to retrieve user keys. For example:
+ </para>
+<screen>AuthorizedKeysCommand /usr/bin/sss_ssh_authorizedkeys</screen>
+ </listitem>
+ <listitem>
+ <para>
+ SSH can also support a public key agent. In that case, give the command to use to retrieve agent keys, including tokens for required arguments (such as the username):
+ </para>
+<screen>PubKeyAgent /usr/bin/sss_ssh_authorizedkeys %u</screen>
+ </listitem>
+ </itemizedlist>
+
+ </section>
+ </section>
+
+ <section id="usingnscd-sssd"><title>Using NSCD with SSSD</title>
+ <indexterm>
+ <primary>NSCD</primary>
+ <secondary>and SSSD</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>SSSD</primary>
+ <secondary>and NSCD</secondary>
+ </indexterm>
+ <para>
+ SSSD is not designed to be used with the NSCD daemon. Even though SSSD does not directly conflict with NSCD, using both services can result in unexpected behavior, especially with how long entries are cached.
+ </para>
+ <para>
+ The most common evidence of a problem is conflicts with NFS. When using Network Manager to manage network connections, it may take several minutes for the network interface to come up. During this time, various services attempt to start. If these services start before the network is up and the DNS servers are available, these services fail to identify the forward or reverse DNS entries they need. These services will read an incorrect or possibly empty <filename>resolv.conf</filename> file. This file is typically only read once, and so any changes made to this file are not automatically applied.
+ This can cause NFS locking to fail on the machine where the NSCD service is running, unless that service is manually restarted.
+ </para>
+ <para>
+ To avoid this problem, enable caching for hosts and services in the <filename>/etc/nscd.conf</filename> file
+ and rely on the SSSD cache for the <systemitem>passwd</systemitem>, <systemitem>group</systemitem>, and <systemitem>netgroup</systemitem> entries.
+ </para>
+ <para>
+ Change the <filename>/etc/nscd.conf</filename> file:
+ </para>
+<screen>enable-cache hosts yes
+enable-cache passwd no
+enable-cache group no
+enable-cache netgroup no
+</screen>
+ <para>
+ With NSCD answering hosts requests, these entries will be cached by NSCD and returned by NSCD during the boot process. All other entries are handled by SSSD.
+ </para>
+ </section>
+
+ <section id="SSSD-Troubleshooting">
+ <title>Troubleshooting SSSD</title>
+ <section id="sssd-debug"><title>Setting Debug Logs for SSSD Domains</title>
+ <para>
+ Each domain sets its own debug log level. Increasing the log level can provide more information about problems with SSSD or with the domain configuration.
+ </para>
+ <para>
+ To change the log level, set the <parameter>debug_level</parameter> parameter for each section in the <filename>sssd.conf</filename> file for which to produce extra logs. For example:
+ </para>
+<screen>[domain/LDAP]
+enumerate = false
+cache_credentials = true
+<userinput>debug_level = 9</userinput></screen>
+ <table id="tab.sssd-debug-levels"><title>Debug Log Levels</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ Level
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ 0
+ </entry>
+ <entry>
+Fatal failures. Anything that would prevent SSSD from
+ starting up or causes it to cease running.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 1
+ </entry>
+ <entry>
+Critical failures. An error that doesn't kill the SSSD, but
+ one that indicates that at least one major feature is not going to
+ work properly.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 2
+ </entry>
+ <entry>
+Serious failures. An error announcing that a particular
+ request or operation has failed.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 3
+ </entry>
+ <entry>
+Minor failures. These are the errors that would percolate
+ down to cause the operation failure of 2.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 4
+ </entry>
+ <entry>
+Configuration settings.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 5
+ </entry>
+ <entry>
+Function data.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 6
+ </entry>
+ <entry>
+Trace messages for operation functions.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 7
+ </entry>
+ <entry>
+Trace messages for internal control functions.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 8
+ </entry>
+ <entry>
+Contents of function-internal variables that may be
+ interesting.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 9
+ </entry>
+ <entry>
+Extremely low-level tracing information.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <note><title>NOTE</title>
+ <para>
+ In versions of SSSD older than 1.8, debug log levels could be set globally in the <command>[sssd]</command> section. Now, each domain and service must configure its own debug log level.
+ </para>
+ <para>
+ To copy the global SSSD debug log levels into each configuration area in the SSSD configuration file, use the <filename>sssd_update_debug_levels.py</filename> script.
+ </para>
+<screen>python /usr/lib/python2.6/site-packages/sssd_update_debug_levels.py</screen>
+ </note>
+ </section>
+ <section id="Troubleshooting-Using_SSSD_Log_Files">
+ <title>Checking SSSD Log Files</title>
+ <para>
+ SSSD uses a number of log files to report information about its operation, located in the <filename>/var/log/sssd/</filename> directory.
+ SSSD produces a log file for each domain, as well as an <filename>sssd_pam.log</filename> and an <filename>sssd_nss.log</filename>
+ file.
+ </para>
+ <para>
+ Additionally, the <filename>/var/log/secure</filename> file logs authentication failures and the reason for the failure.
+ </para>
+ </section>
+
+ <section id="Troubleshooting-Problems_with_SSSD_Configuration">
+ <title>Problems with SSSD Configuration</title>
+ <formalpara><title>SSSD fails to start</title>
+ <para>
+ SSSD requires that the configuration file be properly set up, with all the required entries, before the daemon will start.
+ </para>
+ </formalpara>
+ <itemizedlist>
+ <listitem>
+
+ <para>
+ SSSD requires at least one properly configured domain before the service will start. Without a domain, attempting to start SSSD returns an error that no domains are configured:
+ </para>
+<screen># sssd -d4
+
+[sssd] [ldb] (3): server_sort:Unable to register control with rootdse!
+[sssd] [confdb_get_domains] (0): No domains configured, fatal error!
+[sssd] [get_monitor_config] (0): No domains configured.
+</screen>
+ <para>
+ Edit the <filename>/etc/sssd/sssd.conf</filename> file and create at least one domain.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ SSSD also requires at least one available service provider before it will start. If the problem is with the service provider configuration, the error message indicates that there are no services configured:
+ </para>
+<screen>[sssd] [get_monitor_config] (0): No services configured!
+</screen>
+ <para>
+ Edit the <filename>/etc/sssd/sssd.conf</filename> file and configure at least one service provider.
+ </para>
+ <important>
+ <para>
+ SSSD requires that service providers be configured as a comma-separated list in a single <parameter>services</parameter> entry in the <filename>/etc/sssd/sssd.conf</filename> file. If services are listed in multiple entries, only the last entry is recognized by SSSD.
+ </para>
+
+ </important>
+
+ </listitem>
+
+ </itemizedlist>
+ <formalpara><title>I don't see any groups with 'id' or group members with 'getent group'.</title>
+ <para>
+ This may be due to an incorrect <command>ldap_schema</command> setting in the <command>[domain/DOMAINNAME]</command> section of <filename>sssd.conf</filename>.
+ </para>
+ </formalpara>
+ <para>
+ SSSD supports RFC 2307 and RFC 2307bis schema types. By default, SSSD uses the more common RFC 2307 schema.
+ </para>
+ <para>
+ The difference between RFC 2307 and RFC 2307bis is the way which group membership is stored in the LDAP server. In an RFC 2307 server, group members are stored as the multi-valued <parameter>memberuid</parameter> attribute, which contains the name of the users that are members. In an RFC2307bis server, group members are stored as the multi-valued <parameter>member</parameter> or <parameter>uniqueMember</parameter> attribute which contains the DN of the user or group that is a member of this group. RFC2307bis allows nested groups to be maintained as well.
+ </para>
+ <para>
+ If group lookups are not returning any information:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Set <command>ldap_schema</command> to <command>rfc2307bis</command>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Delete <filename>/var/lib/sss/db/cache_DOMAINNAME.ldb</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Restarting SSSD.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ If that doesn't work, add this line to <filename>sssd.conf</filename>:
+ </para>
+<screen>ldap_group_name = uniqueMember</screen>
+ <para>
+ Then delete the cache and restart SSSD again.
+ </para>
+ <formalpara><title>Authentication fails against LDAP.</title>
+ <para>
+ To perform authentication, SSSD requires that the communication channel be encrypted. This means that if <filename>sssd.conf</filename> is configured to connect over a standard protocol (<filename>ldap://</filename>), it attempts to encrypt the communication channel with Start TLS. If <filename>sssd.conf</filename> is configured to connect over a secure protocol (<filename>ldaps://</filename>), then SSSD uses SSL.
+ </para>
+ </formalpara>
+ <para>
+ This means that the LDAP server must be configured to run in SSL or TLS. TLS must be enabled for the standard LDAP port (389) or SSL enabled on the secure LDAPS port (636). With either SSL or TLS, the LDAP server must also be configured with a valid certificate trust.
+ </para>
+ <para>
+ An invalid certificate trust is one of the most common issues with authenticating against LDAP. If the client does not have proper trust of the LDAP server certificate, it is unable to validate the connection, and SSSD refuses to send the password. The LDAP protocol requires that the password be sent in plaintext to the LDAP server. Sending the password in plaintext over an unencrypted connection is a security problem.
+ </para>
+ <para>
+ If the certificate is not trusted, a <systemitem>syslog</systemitem> message is written, indicating that TLS encryption could not be started. The certificate configuration can be tested by checking if the LDAP server is accessible apart from SSSD. For example, this tests an anonymous bind over a TLS connection to <command>test.example.com</command>:
+ </para>
+ <screen>$ ldapsearch -x -ZZ -h test.example.com -b dc=example,dc=com</screen>
+ <para>
+ If the certificate trust is not properly configured, the test fails with this error:
+ </para>
+<screen>ldap_start_tls: Connect error (-11) additional info: TLS error -8179:Unknown code ___f 13</screen>
+ <para>
+ To trust the certificate:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Obtain a copy of the public CA certificate for the certificate authority used to sign the LDAP server certificate and save it to the local system.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add a line to the <filename>sssd.conf</filename> file that points to the CA certificate on the filesystem.
+ </para>
+ <screen>ldap_tls_cacert = /path/to/cacert </screen>
+ </listitem>
+ <listitem>
+ <para>
+ If the LDAP server uses a self-signed certificate, remove the <command>ldap_tls_reqcert</command> line from the <filename>sssd.conf</filename> file.
+ </para>
+ <para>
+ This parameter directs SSSD to trust any certificate issued by the CA certificate, which is a security risk with a self-signed CA certificate.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <formalpara><title>Connecting to LDAP servers on non-standard ports fail.</title>
+ <para>
+ When running SELinux in enforcing mode, the client's SELinux policy has to be modified to connect to the LDAP server over the non-standard port. For example:
+ </para>
+ </formalpara>
+<screen># semanage port -a -t ldap_port_t -p tcp 1389</screen>
+
+ <formalpara><title>NSS fails to return user information</title>
+ <para>
+ This usually means that SSSD cannot connect to the NSS service.
+ </para>
+ </formalpara>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that NSS is running:
+ </para>
+<screen># service sssd status</screen>
+
+ </listitem>
+ <listitem>
+ <para>
+ If NSS is running, make sure that the provider is properly configured in the <literal>[nss]</literal> section of the <filename>/etc/sssd/sssd.conf</filename> file. Especially check the <parameter>filter_users</parameter> and <parameter>filter_groups</parameter> attributes.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Make sure that NSS is included in the list of services that SSSD uses.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Check the configuration in the <filename>/etc/nsswitch.conf</filename> file.
+ </para>
+
+ </listitem>
+ </itemizedlist>
+
+ <formalpara><title>NSS returns incorrect user information </title>
+ <para>
+ If searches are returning the incorrect user information, check that there are not conflicting usernames in separate domains. When there are multiple domains, set the <parameter>use_fully_qualified_domains</parameter> attribute to <literal>true</literal> in the <filename>/etc/sssd/sssd.conf</filename> file. This differentiates between different users in different domains with the same name.
+ </para>
+ </formalpara>
+
+ <formalpara><title>Setting the password for the local SSSD user prompts twice for the password</title>
+ <para>
+ When attempting to change a local SSSD user's password, it may prompt for the password twice:
+ </para>
+ </formalpara>
+
+<screen>[root at clientF11 tmp]# passwd user1000
+Changing password for user user1000.
+New password:
+Retype new password:
+New Password:
+Reenter new Password:
+passwd: all authentication tokens updated successfully.</screen>
+ <para>
+ This is the result of an incorrect PAM configuration. Ensure that the <parameter>use_authtok</parameter> option is correctly configured in your <filename>/etc/pam.d/system-auth</filename> file.
+ </para>
+
+ </section>
+
+
+ </section>
+
+
+ </section>
+
+
</chapter>
More information about the docs-commits
mailing list