Merge lp:~markthomas/serverguide/serverguide-review-7.5 into lp:serverguide/trunk

[Mark Thomas]

This is a new section describing how to configure Trusty to authenticate against Active Directory with sssd. It did not fit into any previously-existing section (i.e. no section for sssd existed).

[Doug Smythies (dsmythies)]

Peter: Do you want to try to include this one in our pending point release, for which string freeze is tomorrow? It looks pretty good to me.

[Peter Matulis (petermatulis)]

A wonderful contribution! Thank you Mark. A few comments below.

1. wording

(a)
"This section covers the use of sssd to authenticate user logins against an Active Directory via sssd and PAM using sssd's "ad" provider."

Maybe:

"This section describes the use of sssd and PAM for authenticating users against Microsoft Active Directory."

(b)
"This guide assumes that a working Active Directory domain already configured."

Maybe:

"This guide assumes that a working Active Directory domain is already configured.

(c)
"The domain and kerberos realm used in this example is myubuntu.example.com ."

Maybe the realm should be in all caps. You mention both domain and realm so not sure.

(d)
"Add an alias /etc/hosts specifying the FQDN."

Maybe:

"Add an entry to /etc/hosts for specifying the FQDN."

(e)
"kerberos" should be capitalized everywhere: Kerberos.

2. format

(a) All commands should be formatted like so:

<screen>
<command>command_goes_here</command>
</screen>

(b) All filenames should be formatted like so:

<filename>file_goes_here</filename>

(c) References should be hyperlinks. See end of this page as an exemplar:

https://help.ubuntu.com/14.04/serverguide/openldap-server.html

Long ugly URLs should also not be exposed to the reader.

review: Needs Fixing

[Doug Smythies (dsmythies)]

Mark: Are you going to get to this today or tomorrow? We are wanting to do a point release of the serverguide, and had originally intended string freeze for yesterday. String freeze will be pushed at least until tomorrow now. If you cannot get to this, I will fix it.

[Doug Smythies (dsmythies)]

Mark: What is the status of this?

[Mark Thomas (markthomas)]

I never received a notification on this for some reason. I will be addressing this ASAP.

[lp:~markthomas/serverguide/serverguide-review-7.5]

238. By Mark Thomas on 2015-02-26

Changes based on feedback in LP

[Mark Thomas (markthomas)]

Content changes:

(a) I implemented a variation of that change. It is important to highlight that the “ad” provider is what is being covered—the use of the “ldap” provider in sssd for AD authentication is quite different, older, and more difficult. I did omit the name “Microsoft”, as it is also possible to use Samba4 as an AD domain controller. Do you think it is needed?

(b) Fixed

(c) Modified for clarification. I am not trying to specify formatting—that is covered soon after. I am providing the value used rather than have it just “show up” as I’ve seen in other documentation.

One thing I did here was to use a “subdomain” for the Active Directory domain. So often, I see just “example.com”. If someone wants to implement the AD domain as a subdomain, as is often done, I didn’t want it left an an exercise for the reader to figure out what the realm should be by “trial and error” as I’ve had to do.

(d) Modified for clarification.

(e) Fixed

2. format

(a) Fixed
(b) Fixed
(c) Fixed

[Peter Matulis (petermatulis)]

Looks good!

review: Approve

[Doug Smythies (dsmythies)]

Mark, Thanks very much.

Peter: O.K. we will now call 12.04 and trunk (14.04) serverguides as in string freeze until the point release is done.

=== modified file 'serverguide/C/network-auth.xml'
--- serverguide/C/network-auth.xml	2015-02-25 16:19:47 +0000
+++ serverguide/C/network-auth.xml	2015-02-26 19:58:31 +0000
@@ -3969,4 +3969,219 @@
 
     </sect2>
   </sect1>
+  <sect1 id="sssd-ad" status="review">
+    <title>SSSD and Active Directory</title>
+    <para>
+    	This section describes the use of sssd to authenticate user logins against an Active Directory via using sssd's "ad" provider.  In previous versions of sssd, it was possible to authenticate using the "ldap" provider.  However, when authenticating against a Microsoft Windows AD Domain Controller, it was generally necessary to install the POSIX AD extensions on the Domain Controller.  The "ad" provider simplifies the configuration and requires no modifications to the AD structure.
+    </para>
+    <sect2 id="sssd-ad-requirements" status="review">
+    	<title>Prerequisites, Assumptions, and Requirements</title>
+      	<itemizedlist>
+        	<listitem>
+        		<para>This guide does not explain Active Directory, how it works, how to set one up, or how to maintain it.  It may not provide “best practices” for your environment.</para></listitem>
+    		<listitem>
+				<para>This guide assumes that a working Active Directory domain is already configured.</para></listitem>
+    		<listitem>
+				<para>The domain controller is acting as an authoritative DNS server for the domain.</para></listitem>
+    		<listitem>
+				<para>The domain controller is the primary DNS resolver as specified in  <filename>/etc/resolv.conf</filename>.</para>
+			</listitem>
+    		<listitem>
+				<para>The appropriate <emphasis>_kerberos</emphasis>, <emphasis>_ldap</emphasis>, <emphasis>_kpasswd</emphasis>, etc. entries are configured in the DNS zone (see Resources section for external links).</para></listitem> 
+    		<listitem>
+				<para>System time is synchronized on the domain controller (necessary for Kerberos).</para></listitem>
+    		<listitem>
+				<para>The domain used in this example is <emphasis>myubuntu.example.com</emphasis> .</para></listitem>
+		</itemizedlist>
+	</sect2>
+	<sect2 id="sssd-ad-installation" status="review">
+		<title>Software Installation</title>
+		<para>The following packages are needed: <emphasis>krb5-user</emphasis>, <emphasis>samba</emphasis>, <emphasis>sssd</emphasis>, and <emphasis>ntp</emphasis>.  Samba needs to be installed, even if the system is not exporting shares. The Kerberos realm and FQDN or IP of the domain controllers are needed for this step.</para>
+		<para>Install these packages now.
+		</para>
+		<screen><command>sudo apt-get install krb5-user samba sssd ntp</command></screen>
+		<para>See the next section for the answers to the questions asked by the <emphasis>krb5-user</emphasis> postinstall script.</para>
+	</sect2>
+	<sect2 id="sssd-ad-kerberos" status="review">
+		<title>Kerberos Configuration</title>
+		<para>The installation of <emphasis>krb5-user</emphasis> will prompt for the realm name (in ALL UPPERCASE), the kdc server (i.e. domain controller) and admin server (also the domain controller in this example.)  This will write the [realm] and [domain_realm] sections in <filename>/etc/krb5.conf</filename>.  These sections may not be necessary if domain autodiscovery is working.  If not, then both are needed.</para>
+		<para>If the domain is <emphasis>myubuntu.example.com</emphasis>, enter the realm as <emphasis>MYUBUNTU.EXAMPLE.COM</emphasis>
+		</para>
+
+		<para>Optionally, edit <emphasis>/etc/krb5.conf</emphasis> with a few additional settings to specify Kerberos ticket lifetime (these values are safe to use as defaults):</para>
+		<programlisting>
+[libdefaults]
+
+default_realm = MYUBUNTU.EXAMPLE.COM
+ticket_lifetime = 24h #
+renew_lifetime = 7d
+		</programlisting>
+
+		<para>If default_realm is not specified, it may be necessary to log in with “username@domain” instead of “username”.</para>
+
+		<para>The system time on the Active Directory member needs to be consistent with that of the domain controller, or Kerberos authentication may fail.  Ideally, the domain controller server itself will provide the NTP service. Edit <filename>/etc/ntp.conf</filename>:</para>
+
+<programlisting>
+server dc.myubuntu.example.com
+</programlisting>
+
+	</sect2>
+	<sect2 id="sssd-ad-samba" status="review">
+	<title>Samba Configuration</title>
+<para>Samba will be used to perform netbios/nmbd services related to Active Directory authentication, even if no file shares are exported.  Edit the file /etc/samba/smb.conf and add the following to the <emphasis>[global]</emphasis> section:</para>
+
+<programlisting>
+[global]
+
+workgroup = MYUBUNTU
+client signing = yes
+client use spnego = yes
+kerberos method = secrets and keytab
+realm = MYUBUNTU.EXAMPLE.COM
+security = ads
+</programlisting>
+
+<note><para>Some guides specify that "password server" should be specified and pointed to the domain controller.  This is only necessary if DNS is not properly set up to find the DC.  By default, Samba will display a warning if "password server" is specified with "security = ads".</para></note>
+
+</sect2>
+
+<sect2 id="sssd-ad-sssdconfig" status="review">
+	<title>SSSD Configuration</title>
+
+<para>There is no default/example config file for <filename>/etc/sssd/sssd.conf</filename> included in the sssd package.  It is necessary to create one.  This is a minimal working config file:</para>
+
+<programlisting>
+[sssd]
+services = nss, pam
+config_file_version = 2
+domains = MYUBUNTU.EXAMPLE.COM
+
+[domain/MYUBUNTU.EXAMPLE.COM]
+id_provider = ad
+access_provider = ad
+
+# Use this if users are being logged in at /.
+# This example specifies /home/DOMAIN-FQDN/user as $HOME.  Use with pam_mkhomedir.so
+override_homedir = /home/%d/%u
+
+# Uncomment if the client machine hostname doesn't match the computer object on the DC.
+# ad_hostname = mymachine.myubuntu.example.com
+
+# Uncomment if DNS SRV resolution is not working
+# ad_server = dc.mydomain.example.com
+
+# Uncomment if the AD domain is named differently than the Samba domain
+# ad_domain = MYUBUNTU.EXAMPLE.COM
+
+# Enumeration is discouraged for performance reasons.
+# enumerate = true
+</programlisting>
+
+<para>After saving this file, set the ownership to root and the file permissions to 600:</para>
+<screen><command>sudo chown root:root /etc/sssd/sssd.conf</command></screen>
+<screen><command>sudo chmod 600 /etc/sssd/sssd.conf</command></screen>
+
+<para>If the ownership or permissions are not correct, sssd will refuse to start.</para>
+</sect2>
+
+<sect2 id="sssd-ad-nsswitch" status="review">
+	<title>Verify nsswitch.conf Configuration</title>
+	<para>The post-install script for the sssd package makes some modifications to /etc/nsswitch.conf automatically.  It should look something like this:</para>
+
+<programlisting>
+passwd:         compat sss
+group:          compat sss
+...
+netgroup:       nis sss
+sudoers:        files sss
+</programlisting>
+</sect2>
+
+<sect2 id="sssd-ad-hosts" status="review">
+	<title>Modify /etc/hosts</title>
+<para>Add an alias to the localhost entry in /etc/hosts specifying the FQDN.  For example:</para>
+<programlisting>192.168.1.10 myserver myserver.myubuntu.example.com</programlisting>
+
+<para>This is useful in conjunction with dynamic DNS updates.</para>
+</sect2>
+
+<sect2 id="sssd-ad-join" status="review">
+	<title>Join the Active Directory</title>
+<para>Now, restart ntp and samba and start sssd.</para>
+<screen><command>sudo service ntp restart</command>
+<command>sudo restart smbd</command> 
+<command>sudo restart nmbd</command> 
+<command>sudo start sssd</command></screen>
+
+<para>Test the configuration by obtaining a Kerberos ticket:</para>
+
+<screen><command>sudo kinit Administrator</command></screen>
+
+<para>Verify the ticket with:</para>
+<screen><command>sudo klist</command></screen>
+
+<para>If there is a ticket with an expiration date listed, then it is time to join the domain:</para>
+
+<screen><command>sudo net ads join -k</command></screen>
+
+<para>A warning about "No DNS domain configured. Unable to perform DNS Update." probably means that there is no (correct) alias in <filename>/etc/hosts</filename>, and the system could not provide its own FQDN as part of the Active Directory update.  This is needed for dynamic DNS updates.  Verify the alias in <filename>/etc/hosts</filename> described in "Modify /etc/hosts" above.</para>
+
+<para>(The message "NT_STATUS_UNSUCCESSFUL" indicates the domain join failed and something is incorrect.  Review the prior steps before proceeding).</para>
+
+<para>Here are a couple of (optional) checks to verify that the domain join was successful. Note that if the domain was successfully joined but one or both of these steps fail, it may be necessary to wait 1-2 minutes and try again.  Some of the changes appear to be asynchronous.</para>
+
+<para>Verification option #1:</para>
+<para>Check the default Organizational Unit for computer accounts in the Active Directory to verify that the computer account was created.  (Organizational Units in Active Directory is a topic outside the scope of this guide).</para>
+
+<para>Verification option #2</para>
+<para>Execute this command for a specific AD user (e.g. administrator)</para>
+<screen><command>getent passwd username</command></screen>
+
+<note><para>If <emphasis>enumerate = true</emphasis> is set in <filename>sssd.conf</filename>, <emphasis>getent passwd</emphasis> with no username argument will list all domain users.  This may be useful for testing, but is slow and not recommended for production.</para></note>
+</sect2>
+
+<sect2 id="sssd-ad-test" status="review">
+	<title>Test Authentication</title>
+	<para>It should now be possible to authenticate using an Active Directory User's credentials:</para>
+
+<screen><command>su - username</command></screen>
+
+<para>If this works, then other login methods (getty, ssh) should also work.</para>
+
+<para>If the computer account was created, indicating that the system was "joined" to the domain, but authentication is unsuccessful, it may be helpful to review <filename>/etc/pam.d</filename> and <filename>nssswitch.conf</filename> as well as the file changes described earlier in this guide.</para>
+</sect2>
+
+<sect2 id="sssd-ad-mkhomedir" status="review">
+	<title>Home directories with pam_mkhomedir (optional)</title>
+	<para>When logging in using an Active Directory user account, it is likely that user has no home directory.  This can be fixed with pam_mkdhomedir.so, which will create the user’s home directory on login.  Edit <filename>/etc/pam.d/common-session</filename>, and add this line directly after <emphasis>session required pam_unix.so:</emphasis></para>
+<programlisting>
+session    required    pam_mkhomedir.so skel=/etc/skel/ umask=0022
+</programlisting>
+
+<note><para>This may also need <emphasis>override_homedir</emphasis> in <filename>sssd.conf</filename> to function correctly, so make sure that’s set.</para></note>
+</sect2>
+
+<sect2 id="sssd-ad-desktop" status="review">
+	<title>Desktop Ubuntu Authentication</title>
+	<para>It is possible to also authenticate logins to Ubuntu Desktop using Active Directory accounts.  The AD accounts will not show up in the pick list with local users, so lightdm will need to be modified.  Edit the file <filename>/etc/lightdm/lightdm.conf.d/50-unity-greeter.conf</filename> and append the following two lines:</para>
+
+<programlisting>
+greeter-show-manual-login=true
+greeter-hide-users=true
+</programlisting>
+
+<para>Reboot to restart lightdm.  It should now be possible to log in using a domain account using either <emphasis>username</emphasis> or <emphasis>username/username@domain</emphasis> format.</para>
+</sect2>
+
+<sect2 id="sssd-ad-resources" status="review">
+	<title>Resources</title>
+	     <itemizedlist>
+        <listitem><para><ulink url="https://fedorahosted.org/sssd">SSSD Project</ulink></para></listitem>
+<listitem><para><ulink url="http://www.ucs.cam.ac.uk/support/windows-support/winsuptech/activedir/dnsconfig">DNS Server Configuration guidelines</ulink></para></listitem>
+<listitem><para><ulink url="https://technet.microsoft.com/en-us/library/cc759550%28v=ws.10%29.aspx">Active Directory DNS Zone Entries</ulink></para></listitem>
+<listitem><para><ulink url="http://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html">Kerberos config options</ulink></para></listitem>
+	     </itemizedlist>
+
+</sect2>
+</sect1>
 </chapter>