ADAddUbuntu < CF

CF Web>Infrastructure>CSCFActiveDirectory>ADAddUbuntu (2024-10-30, MariHassanzada) (raw view)
---+ Authenticating an Ubuntu machine using the CS Active Directory (THIS PAGE NEEDS UPDATING)

%TABLE{tableborder="0" cellpadding="10" databg="#EDDBCB" }%
|  Note that when setting up LDAP access for a host which happens to be running as a [[LxcStart][LXC container]], the ntp package should not be installed, although ntp must be installed and configured on the bare metal machine.  |

See also: ADAddUbuntuScripts.

---++ Introduction

This document outlines how to configure an Ubuntu Linux box to authenticate users using accounts managed by Microsoft Active Directory. You will need to have =root= (superuser) access to the local Ubuntu system and you will need to be authorized to create and configure user accounts within the Active Directory domain for which you are preparing your Ubuntu computer to authenticate. For step-by-step instructions, based on these notes, see SettingUpADGradPCs for setting up a standard PC.

%TOC%

For the non-indoctrinated, this exercise involves configuring client-server communications for two separate and differing protocols.

   * LDAP: Used for user account lookup within the Active Directory
   * Kerberos: For authentication of user credentials
The Ubuntu host or workstation must be able to talk to the Active Directory properly in both protocols, otherwise authentication of users will not work.

CSCF uses RFC 2307 attributes for all user and computer objects within our Active Directory. We *do not* use the Unix 3.5 characteristics which Microsoft Active Directory has provided in the past. In particular, we *do not* modify the _Unix Attributes_ when creating a Linux system's "user" account in the Windows GUI tool *Active Directory Users and Computers*. The document ADAddSolaris10 outlines the required modifications (including schema additions) to the a Windows 2003 Active Directory necessary for such attributes to be present. This document assumes that these modifications to the Active Directory have been performed.

This document also assumes that the Active directory is already configured to permit anonymous LDAP connections to its member domain controllers. This modification is also outlined in the document ADAddSolaris10.

---+++ RFC 2307 User Attributes Of Interest In Active Directory

We are interested in the following user attributes which can be viewed (amongst others) by issuing the following command on your Linux system command prompt.

=ldapsearch -x -H ldap://ldap.cs -b dc=cs,dc=uwaterloo,dc=ca cn= _username_=

This command yields the details of a typical user account. We have excluded most of the output in order to focus on the following Unix attributes for POSIX account management.

<pre>       uidNumber: 1126
       gidNumber: 1126
       unixHomeDirectory: /u/<em>username</em>
       loginShell: /xhbin/tcsh
</pre>

These POSIX attributes can be modified manually using the =ADSI Edit= snapin which is part of the =mmc.exe= console tool on any Active Directory domain controller.

*IMPORTANT*: For any user attempting to login to the Ubuntu system, the user's login shell specified by the user's =loginShell= account attribute must be present on the local Ubuntu system otherwise permission to login will be denied by the Ubuntu system.

*IMPORTANT*: For later versions of Ubuntu (Ubuntu 8.04 in particular) all Active Directory group objects, for which any login user is a member, must have their =gidNumber= attribute populated. This is the case even if the AD group has no relevance to any Linux activity conducted by the user. Ubuntu 8 apparently attempts to enumerate the membership of all groups for which the login user is a member. If one of these groups has no assigned =gidNumber= and has a large population, the login process may hang for the user.

---++ Requisite Software

CSCF's standard Ubuntu workstation and server images may have the following packages pre-installed. However, older versions of our Ubuntu and other Linux OS images do not and the default Ubuntu OS definitely does not. Since it does no harm to perform a reinstall, a system manager may wish to require the following packages.

   * ldap-utils =$sudo apt-get -y install ldap-utils=
   * krb5-user =$sudo apt-get -y install krb5-user=
   * libnss-ldap =$sudo apt-get -y install libnss-ldap=
   * libpam-krb5 =$sudo apt-get -y install libpam-krb5=
   * ntp =$sudo apt-get install ntp=
   * nscd =$sudo apt-get install nscd=
%TABLE{tableborder="0" cellpadding="10" databg="#EDDBCB" }%
|  The =uwcs-auth= metapackage is intended to bring in most of this for you. That is, ="sudo apt-get -y install uwcs-auth"=. Add ="sudo apt-get -y install uwcs-auth"= if you are working on a bare metal machine.  |

During the installation of LDAP and Kerberos clients and tools you may be automatically prompted for configuration details. Just enter the default information. We will be configuring both clients manually later.

---+++ Package =libnss_ldap= installed on Ubuntu client

The package =libnss-ldap= (as coded by www.padl.com) possesses the dynamic library =/lib/x86_64-linux-gnu/libnss_ldap-2.26.so= and is configured by =/etc/ldap.conf= (which is different from =/etc/ldap/ldap.conf= which is used by LDAP utility programs like =ldapsearch= as provided by www.openldap.org). Even though the files share similar syntax there is *no guarantee that will always be the case*, which explains why these files in different locations.

---++ Configuration Of The Ubuntu NSS (Network Services Switch)

Simply put, NSS, is a way of accessing _system databases_ with no authentication or authorization functionality (a functionality provided by PAM). Examples of system databases include user data, name service data (presumably this is where the name came from). We would like to be able to consult and LDAP database via NSS. Installing the =libnss-ldap= package enables this and also pulls in the =libpam-ldap= package (it's not entirely clear what the exact dependency on pam is).

---+++ Edit =/etc/nsswitch.conf=
---++++ passwd, group and shadow database configuration

At this point we are in position to edit =/etc/nsswitch.conf= and enable =ldap=, that is, ensure that the following lines
<verbatim>
passwd:       files ldap files ldap [TRYAGAIN=5]
group:         files ldap files ldap [TRYAGAIN=5]
netgroup:     files ldap files ldap [TRYAGAIN=5]
shadow:       files ldap files ldap [TRYAGAIN=5]

hosts:          dns files
networks:     files

protocols:    db files
services:     db files
ethers:        db files
rpc:             db files
</verbatim>

appear.

---++++ DNS configuration

Let us preface this section by saying that our DNS setup is not entirely standard in ways that will not be discussed further here so some of the problems encountered may be a non-issue for others.

To avoid peculiar errors with the PAM module (we discuss some of these below) it is important that =hostname --fqdn= really does give a *fully qualified domain name* albeit the exact reasons for the errors observed are obscure pending some source code analysis. For now we specify the DNS configuration that worked.

Either make sure that
<verbatim>
hosts: dns files
</verbatim>

appears or, if one relies on the contents of =/etc/hosts= or
<verbatim>
129.97.15.162   fedfan.cs.uwaterloo.ca fedfan.cs fedfan
</verbatim>

In the past there was some speculation that our local DNS setup required the presence of entries of the various Windows domain controllers but that was found to be unnecessary albeit it would not hurt to have them in there. We have chosen to not put them in because we wanted to find out the minimal requirements for success.

---++ Configuration of Ubuntu =nscd= Cache

When the =nscd= package is installed, it comes with a configuration file named =/etc/nscd.conf=. Though its default settings are fine for a single user environment they are not adequate for systems that serve numerous users at once. Such systems are common place in large institutions such as universities. Therefore the following lines in =/etc/nscd.conf= are edited and/or enabled from their default settings. All other entries in the default =/etc/nscd.conf= are not changed.

<pre># We do wish to keep a log of nscd activity.
#
        logfile                 /var/log/nscd.log

# Increase the number of active threads running on the server to manage cache requests.
#
        threads                 6
        max-threads             132
#       server-user             nobody
#       stat-user               somebody

# Log file will have a debug level increased from 0 to 1
#
        debug-level             0

# We wish to retain entries up until their TTL expires
#
        reload-count            unlimited

# Setting nscd to restat itself once every 3 hours. Cached databases are marked as
# persistent so data in cache will survive restart and reboot.
#
        paranoia                yes
        restart-interval        10800

#
# For the passwd database:
#
        enable-cache            passwd          yes

# A positive user lookup is to be retained by the cache for 15 minutes.
# This is particularly important for reducing LDAP calls to the domain
# controllers. However, attributes like loginShell must be updated in
# a timely manner so 15 minutes is considered a reasonable wait time.
#
        positive-time-to-live   passwd          900

# If however there is a lookup failure for a user, a much shorter time
# of 2 seconds is needed.
#
        negative-time-to-live   passwd          2
        suggested-size          passwd          211
        check-files             passwd          yes
        persistent              passwd          yes
        shared                  passwd          yes
        max-db-size             passwd          16777216
        auto-propagate          passwd          yes

# For the group database:
# TTL are to be much longer than those of the passwd database.
# This is done to decrease the average time for user login as
# group membership is always enumerated for any user login.
#
        enable-cache            group           yes
        positive-time-to-live   group           11000
        negative-time-to-live   group           900
        suggested-size          group           211
        check-files             group           yes
        persistent              group           yes
        shared                  group           yes
        max-db-size             group           16777216
        auto-propagate          group           yes

# hosts caching is broken with gethostby* calls, hence is now disabled
# per default.  See /usr/share/doc/nscd/NEWS.Debian.
        enable-cache            hosts           yes
        positive-time-to-live   hosts           5400
        negative-time-to-live   hosts           300
        suggested-size          hosts           211
        check-files             hosts           yes
        persistent              hosts           yes
        shared                  hosts           yes
        max-db-size             hosts           16777216

        enable-cache            services        yes
        positive-time-to-live   services        28800
        negative-time-to-live   services        900
        suggested-size          services        211
        check-files             services        yes
        persistent              services        yes
        shared                  services        yes
        max-db-size             services        16777216

# For the netgroup database:
#
        enable-cache            netgroup           yes
        positive-time-to-live   netgroup           11000
        negative-time-to-live   netgroup           900
        suggested-size          netgroup           211
        check-files             netgroup           yes
        persistent              netgroup           yes
        shared                  netgroup           yes
        max-db-size             netgroup           16777216
        auto-propagate          netgroup           yes
</pre>

Whenever the =/etc/nscd.conf= is edited, the changes do not take effect until the =nscd= service is restarted either by reboot or by the following command.

=service nscd restart=

---++ Configuration Of Ubuntu LDAP Client

Preparation of the Ubuntu LDAP client is fairly straight forward and less cumbersome than in the case of a Solaris system. Typically only one file ( =/etc/ldap.conf=) needs be edited. Changes to this file take effect immediately.

---+++ Edit/Install The =/etc/ldap.conf= File

For this example we are configuring the Ubuntu LDAP client to consult our =CS-GENERAL= domain (DNS name: =cs.uwaterloo.ca=) in our Active Directory. Which is also the =CS.UWATERLOO.CA= Kerberos realm. The following lines should be present in the =/etc/ldap.conf= file, all other lines should be blank or commented out.

<pre>base dc=cs,dc=uwaterloo,dc=ca
nss_srv_domain cs.uwaterloo.ca
ldap_version 3
referrals off
bind_policy soft
nss_reconnect_tries 3
nss_reconnect_sleeptime 1
nss_reconnect_maxsleeptime 1
nss_reconnect_maxcomtries 1
nss_map_objectclass posixAccount user
nss_map_objectclass shadowAccount user
nss_map_attribute uid sAMAccountName
nss_map_attribute cn displayName
nss_map_attribute homeDirectory unixHomeDirectory
nss_map_attribute shadowLastChange pwdLastSet
nss_map_objectclass posixGroup group
nss_map_attribute uniqueMember memberUid
pam_login_attribute sAMAccountName
pam_filter objectclass=User
pam_password ad

</pre>

This should also be the read out from the following command issued at an Ubuntu command prompt. <br /> =#> egrep -v '(^$|^#)' /etc/ldap.conf=

Also, if there is an =/etc/ldap= directory, you should ensure that any =ldap.conf= file in this directory is a symbolic link back to =/etc/ldap.conf=.

The line <tt>nss_srv_domain cs.uwaterloo.ca</tt> means that the local LDAP client derives the addresses of its LDAP servers (domain controllers) by querying the following SRV record in DNS.<BR>
<tt>_ldap._tcp.cs.uwaterloo.ca</tt>

If you have configured the LDAP client correctly then issuing the following command for a known domain <tt> _username_ </tt> at an Ubuntu command prompt...<br /> <tt>#> getent passwd <em>username</em></tt><br /> ...will produce output similar to the following...<br /> =_username_:*:8324:8324:<em>User's Description</em>:/u/<em>username</em>:/bin/bash=

---++++ No LDAP Binding Credentials Required

CSCF's Directory Services is configured to allow anonymous LDAP <span style="text-decoration: underline;">connections</span> to our forest domain controllers. Anonymous reads of attributes for certain non-sensitive objects like common user accounts is also permitted. Therefore, LDAP binding credentials are not required and do not need to be specified in =/etc/ldap.conf=.

---++++ objectClasses in Active Directory are named differently from !OpenLDAP server settings

The above =nss_map= directives allow the Linux LDAP utilities to find the account attributes as they are named differently in Microsoft Active Directory than they would be in !OpenLDAP, that is, the left most value is the corresponding name as defined in Windows AD. In particular, when looking for *posixAccount* and *shadowAccount* object classes we must instead look in Windows 2003 objectclass *user*. Furthermore, the *uid* is stored in the parameter *sAMAccountName* within the AD.

---++++ User group name on Ubuntu client

We make a special convention for the user's group name, which should be the same as *uid* but because AD does not allow creation of two objects with the same *cn* it was decided that the user's group entry in AD would be called =uid_group=. In particular, for the user =wtautz=, the command
<verbatim>
#> getent group |grep wtautz
</verbatim>

should output
<verbatim>
wtautz:*:1126:
</verbatim>

rather than
<verbatim>
wtautz_group:*:1126:
</verbatim>

The solution is provided by setting the the attribute =displayName= of the objectClass group to =wtautz=, which, when combined with the line,
<verbatim>
nss_map_attribute cn displayName
</verbatim>

in =/etc/ldap.conf= results in the desired output.

---++ Configuration Of The Ubuntu Kerberos Client

---+++ Setup Time Server (NTP)

Kerberos is reliant on accurate time settings and so install =ntp=, so run =apt-get -y install ntp= and then add the following lines near the beginning of =/etc/ntp.conf=
<verbatim>
     server ntp.student.cs.uwaterloo.ca
     server ntp.cs.uwaterloo.ca
</verbatim>

then run
<verbatim>
     /etc/init.d/ntp stop
     ntpdate ntp.student.cs.uwaterloo.ca
     /etc/init.d/ntp start
</verbatim>

---+++ Creation Of Active Directory Kerberos Credentials For The Ubuntu Computer

THIS SECTION IS BEING EDITED

As stated in the above <tt> _Introduction_ </tt> section, in order to perform this part of the setup you will require =root= account access on the local Ubuntu system as well as authorization to create and configure user accounts within CSCF Directory Service domain for which you are setting up your Ubuntu computer to authenticate.

This is a three step process.
   1. Create a "User" object to represent the Ubuntu system in the domain where it will authenticate.
   1. Edit/Install the CSCF standard kerberos client configuration file (=/etc/krb5.conf=) on the Ubuntu system. 
   1. Create an <tt>/etc/krb5.keytab</tt> file on the Ubuntu system which will retain the system's domain credentials.

---++++ Create Domain "User" Object For The Ubuntu System

   1 Create a generic User object in the domain.<BR>Standard procedure is to name this account after the =hostname= of the Ubuntu system with a =_host= suffix.<BR> For example: An Ubuntu station named =nettop167.cs.uwaterloo.ca= would have a =CS-GENERAL= domain account named =nettop167_host=.
   1 Set the password for this object.<BR> This should be a lengthy and complex password. Keep note of it because it will be required for building the Ubuntu system's <tt>keytab</tt> file later.
   1 Set or ensure that they are set the following attributes for the Ubuntu system's User object.
      * objectClass: =user=
      * sAMAccountName: =&lt;hostname&gt;_host=
      * displayName: =&lt;hostname&gt;_host=
      * userPrincipalName: =host/&lt;FQDN_Of_Ubuntu_System&gt;@&lt;Kerberos_Realm_Of_Directiory_Service_Domain&gt;=
         * In any other kerberos documentation the above expression would actually be called the 'service principle name' or SPN and will referenced as such in other parts of this document.
      * servicePrincipalName: =host/&lt;FQDN_Of_Ubuntu_System&gt;=
         * In any other kerberos documentation the above expression would actually be called the 'service name'.
      * userAccountControl: =4260352=
   1 Record the value of the following attribute 
      * msDS-KeyVersionNumber
         * In any other kerberos documentation this value would be called the User object's =KVNO= number.<BR>It is advanced by one (1) each time the object's password is changed. It is also be required for building the Ubuntu system's <tt>keytab</tt> file later.

---++++ Edit/Install The =/etc/krb5.conf= File

CSCF has a standard kerberos client configuration for all production domains within our Directory Services. For this example we are configuring the Ubuntu kerberos client to consult our =CS-GENERAL= domain (DNS name: =cs.uwaterloo.ca=) in our Directory Services. Which is also the =CS.UWATERLOO.CA= Kerberos realm. Other realms (domains) in our forest are also defined in =/etc/krb5.conf= but =CS.UWATERLOO.CA= is the default.

   * The option =dns_lookup_kdc = yes= means that the kerberos client will find its realm key distribution centres (KDC, aka. domain controller) by requesting the =_krb._tcp.cs.uwaterloo.ca= SRV records in DNS.
   * The option =forwardable = yes= is part of CSCF standards. All kerberos tickets are forardable to support single sign on (SSO) between systems in the same domain.
   * The option =udp_preference_limit = 1= is meant to prevent the use of the UDP protocol for requesting and sending of kerberos tickets. Kerberos tickets generated by Microsoft Active Directory domain controllers are too large to be reliably transmitted with UDP packets. 
   * The option =allow_weak_crypto = 1= is commented out. In the past some older Ubuntu clients required this option to be enabled.

<verbatim>
[libdefaults]
 default_realm = CS.UWATERLOO.CA
 dns_lookup_realm = false
 dns_lookup_kdc = yes
 ticket_lifetime = 24h
 forwardable = yes
 renewable = yes
 max_renewable_life = 7d
 verify_ap_req_nofail = false
 udp_preference_limit = 1
# allow_weak_crypto = 1

[realms]
 CSCF.UWATERLOO.CA = {
   kpasswd_protocol = SET_CHANGE
 }

 CS.UWATERLOO.CA = {
   kpasswd_protocol = SET_CHANGE
  }

 STUDENT.CS.UWATERLOO.CA = {
   kpasswd_protocol = SET_CHANGE
  }

[domain_realm]
 .cscf.uwaterloo.ca = CSCF.UWATERLOO.CA
 cscf.uwaterloo.ca = CSCF.UWATERLOO.CA
 .cs.uwaterloo.ca = CS.UWATERLOO.CA
 cs.uwaterloo.ca = CS.UWATERLOO.CA
 .student.cs.uwaterloo.ca = STUDENT.CS.UWATERLOO.CA
 student.cs.uwaterloo.ca = STUDENT.CS.UWATERLOO.CA

[kdc]
 profile = /etc/krb5/kdc.conf

[logging]
        default = FILE:/var/log/krb5/kdc.log
        kdc = FILE:/var/log/krb5/kdc.log
        admin_server = FILE:/var/log/krb5/kadmind.log

[appdefaults]
        pam = {
         debug = true
         ticket_lifetime = 24h
         renew_lifetime = 7d
         forwardable = true
         krb4_convert = false
        }
        kinit = {
                renewable = true
                forwardable= true
        }
</verbatim>

---++++ Create An <tt>/etc/krb5.keytab</tt> For The Ubuntu System

To begin with If there is a pre-exisitng <tt>/etc/krb5.keytab</tt> file on the Ubuntu system, then set it aside using the <tt>mv</tt> command.

Then, on the Ubuntu system as =root= at a command prompt, use the =ktutil= command to build a new =keytab= file for the system. You will require the following three (3) details from the previous section.

   * The complex password set for the Ubuntu system's domain User object.<BR> This will be prompted for by =ktutil= each time you enter a =addent= subcommand.
   * The value of the User object's =KVNO= number (the <tt>msDS-KeyVersionNumber</tt> attribute) after the object's last password is set or reset.
   * The value of the <tt>userPrincipalName</tt> attribute for the Ubuntu system's domain User object.

Then the following commands below will build the =keytab= file. The first two commands ensure that the =keytab= file will be secured to =root= only read/write access before the encoded account passwords are written to it.

<verbatim>
#> touch /etc/krb5.keytab
#> chmod 600 /etc/krb5.keytab
#> ktutil
addent -password -p <host_SPN_name> -k <KVNO_number> -e des-cbc-md5
> <Password_For_Computer_User_Object>
addent -password -p <host_SPN_name> -k <KVNO_number> -e rc4-hmac
> <Password_For_Computer_User_Object>
addent -password -p <host_SPN_name> -k <KVNO_number> -e des-cbc-crc
> <Password_For_Computer_User_Object>
addent -password -p <host_SPN_name> -k <KVNO_number> -e des3-cbc-sha1
> <Password_For_Computer_User_Object>
addent -password -p <host_SPN_name> -k <KVNO_number> -e aes256-cts
> <Password_For_Computer_User_Object>
addent -password -p <host_SPN_name> -k <KVNO_number> -e aes128-cts
> <Password_For_Computer_User_Object>
wkt /etc/krb5.keytab
#>
</verbatim>

Once the <tt>/etc/krb5.keytab</tt> file is created and the <tt>/etc/krb5.conf</tt> file is in place, try to initialize a ticket granting ticket for the system with the following command..

<verbatim>
#> kinit -k <host_SPN_name>
</verbatim>

---++++ Troubleshooting =kinit= Errors

=Password Incorrect While Getting Initial Credentials=

This is the most difficult =kinit= error to resolve. Most documentation is vague and talks of the =keytab= file being corrupted or having the wrong key. The recommended course of action is to reset the Ubuntu system's User object password and recreate the =keytab= file. Make certain that the =KVNO= number to be used in the new =keytab= file matches the value of the msDS-KeyVersionNumber attribute for the systems domain account. Rerun the =kinit= process. It's worth trying at least once.

<tt>Key Table Entry Not Found While Getting Initial Credentials</tt><br /> =Client Not Found In Kerberos Database While Getting Initial Credentials=

Both these errors can point to a mistake in the SPN naming either in the =keytab= file, the executed =kinit= command or perhaps the SPN for the Ubuntu host was not correctly mapped to the <tt><em>computername</em>_host</tt> account in the Active Directory. You should check each item for a mistake.

You can check the SPN entered in the =keytab= file by entering the command =klist -k -t /etc/krb5/krb5.keytab=. Should there be an error then you will have to create a new =keytab= file. 

You can check the SPN name mapping for the <tt><em>computername</em>_host</tt> account using the =Active Directory Users and Computers= tool. Open the account properties, the proper SPN name should be substituted for the =User logon name= on the =Account= tab. If it is incorrect then you should re-run the =ktpass= command on the domain controller using the correct SPN. This will remap the account. This will generate another =keytab= file but you will probably not require it.

Then attempt the =kinit= process again.

---++ Configuration Of The Ubuntu PAM Stack

Configuration of files in the PAM stack (found in the =/etc/pam.d= directory) will instruct the Ubuntu login process to consult the now configured LDAP and Kerberos clients during user login. The configurations outlined below will also permit the login process to fall back to the local =/etc/passwd= and =/etc/shadow= for authentication should LDAP lookup or Kerberos authentication fail.

Note: For all of the files below, you will comment out *all other lines* and leave only these uncommented.

---+++ /etc/pam.d/common-auth

This is the most important file to edit for authentication purposes, namely we set it so that
<verbatim>
auth  sufficient      pam_krb5.so forwardable ignore_root debug
auth  required        pam_unix.so try_first_pass nullok_secure
</verbatim>

---+++ /etc/pam.d/common-account
<verbatim>
# account     sufficient    pam_ldap.so debug
account     required      pam_unix.so
</verbatim>

The =pam_ldap.so= is now commented out because we use the =nscd= cache and because the =/etc/nsswitch.conf= will direct database lookups to the LDAP server (the domain controllers) through the use of the =pam_unix.so= module. Using the =pam_ldap.so= module merely creates unnecessary LDAP lookups (network traffic) as it bypasses the =nscd= cache. However, we leave the module reference in place for the purpose of debugging if LDAP lookups are not working through the =nsswitch=.

---+++ /etc/pam.d/common-session
<verbatim>
session optional pam_krb5.so debug
session required  pam_unix.so
</verbatim>

This file has been revised as of Ubuntu 18.04. The =pam_krb5.so= module is now =optional= in the =session= stack. It had been =sufficent= in the past which meant that the stack stopped executing once a kerberos user session was confirmed. This prevented the stack from testing with the =pam_unix.so= module. Testing =pam_unix.so= is now a required event in Ubuntu 18.04, otherwise anyone who logged in with a non-local username and password (kerberos logins) through the GUI was immediately logged out again. Permission to create a new 'virtual terminal' (a new personal X windows session) is denied.

---+++ /etc/pam.d/common-password

It's probably a good idea to prepend this stack with password policy enforcement.
<verbatim>
password   sufficient pam_krb5.so ignore_root debug
password   required   pam_unix.so nullok obscure min=4 max=8 md5
</verbatim>

---++ Debugging Failed Authentication

---+++ Check Your Password

Check your username and password is correct. Make sure you are using the correct account from the correct domain. A test login to a remote Windows Terminal server like =barbarus= (for =CS-GENERAL=) or =elegans= (for =CS-TEACHING=) will help establish if the problem is just bad credentials.

---+++ Check LDAP Lookup Is Still Working

If you have configured the LDAP client correctly then issuing the following command for a known domain <tt> _username_ </tt> at an Ubuntu command prompt...<br /> <tt>getent passwd <em>username</em></tt><br /> ...will produce output similar to the following...<br /> =_username_:*:8324:8324:<em>User's Description</em>:/u/<em>username</em>:/xhbin/sh=

If nothing comes back then something is wrong with the LDAP configuration.

NOTE: The command =getent passwd | grep _username_= is not rigorous enough to test LDAP client configuration. It may execute successfully when the =getent passwd _username_= command may not.

---+++ Monitor Security Event Logs On First KDC System

Check to ensure your Ubuntu system is talking to one of the KDC servers (Domain Controllers) in your realm (domain). If the Ubuntu client makes a request for a Kerberos ticket for a login user, there will be a record of the attempt in the =Security= event logs on the KDC in question. Even if the attempt is a failure.

If no records appear then the Ubuntu client is not attempting to request a Kerberos ticket or cannot find a KDC server.

---+++ Ensure Login Shell Is Available

If the user's login shell is not found on the local Ubuntu system, then the user is given an =Access Denied= error during login. Make certain the login shell is present for your test user otherwise the login will fail.

---+++ The =/var/log/auth.log= Log File

I useful tool for debugging a bad authentication setup is the log file =/var/log/auth.log=. Using the =tail -f= command to follow log updates as logins are attempted can help to quickly isolate the source of login failure. This will provide very detailed information as to what part of the login process was being used when a login fails. In the example below, user =wtautz= who is a member of the =CS-GENERAL= domain ( =CS.UWATERLOO.CA= Kerberos realm) fails to login.

<verbatim>
Feb  8 19:44:34 fedfan sshd[14398]: (pam_krb5): wtautz: attempting authentication as wtautz@CS.UWATERLOO.CA
Feb  8 19:44:34 fedfan sshd[14398]: (pam_krb5): wtautz: credential verification failed: Key table entry not found
Feb  8 19:44:34 fedfan sshd[14398]: (pam_krb5): wtautz: krb5_get_init_creds_password: Key table entry not found
Feb  8 19:44:34 fedfan sshd[14398]: (pam_krb5): wtautz: pam_sm_authenticate: exit (failure)
Feb  8 19:44:34 fedfan sshd[14398]: pam_unix(ssh:auth): authentication failure; logname= uid=0 euid=0 tty=ssh ruser= rhost=fedfan.cs.uwaterloo.ca  user=wtautz 
</verbatim>

which can be corrected by making sure the DNS setup is _correct_ where by correct we mean it works (stay tuned for a more thorough analysis).

Of course, the log file will also record successful logins. In the example below, user =wtautz= who is a member of the =CS-GENERAL= domain ( =CS.UWATERLOO.CA= Kerberos realm) has successfully logged into a system called =fedfan= which has been configured to authenticate in the =CS-GENERAL= domain.

<verbatim>
Feb 11 15:37:13 fedfan sshd[7121]: (pam_krb5): wtautz: attempting authentication as wtautz@CS.UWATERLOO.CA
Feb 11 15:37:13 fedfan sshd[7121]: (pam_krb5): wtautz: pam_sm_authenticate: exit (success)
Feb 11 15:37:13 fedfan sshd[7121]: Accepted password for wtautz from 129.97.15.162 port 45103 ssh2
Feb 11 15:37:13 fedfan sshd[7123]: (pam_krb5): wtautz: pam_sm_setcred: entry (0x2)
Feb 11 15:37:13 fedfan sshd[7123]: (pam_krb5): wtautz: initializing ticket cache FILE:/tmp/krb5cc_1126_vDenff
</verbatim>

---+++ Unsuccessful Authentication in =/var/log/auth.log=

---++ Converting systems that use Kerberos and setpw to Active Directory

The topic of this section refers to systems as installed as of September 2008 in the Trash.TrashCFGraphicsLab, Trash.NortelLab and the Student and Core Frontends (except for fe102-linux.cs which still run Dapper). Specifically these hosts use the xhier *setpw* manage the =passwd=, =shadow= and =group= files (to be precise setpw manages part of these files and it ignores those mentioned in =/.software/local/setpw/data/config/exempt-{users,groups}= which were deliberately made to coincide with vendor entries. *NOTE*. These do not include entries that certain xhier package needs like =accounts=, =none= which are were assumed to be handled by *setpw* so, ideally, these entries should be put into the Active Directory database!). The goal of this section is to indicate how these systems can be made *setpw* free (this *assumes* that Kerberos authentication is working flawlessly :-)):

   1 Edit =/root/.rhosts= and remove mention of student.cs (or core.cs) (you may want to also look at =/etc/hosts.allow=)
   1 Look in =/.software/local/setpw/data/config/= and copy (make sure no command in the *setpw* xhier package is running) the passwd, shadow and group into /etc/ (these files represent the state before setpw was activated) If these files are missing from a particular host, they should exist on one of the other hosts of the group (by group, we mean, lab machine, or one of the frontends or cpu servers).
   1 Edit =/etc/nsswitch.conf= and enable ldap entries as described above (run =getent passwd= to check it's working)
   1 remove the =setpw= xhier package
   1 remove pertinent files in the directory =/software/setpw/data/config/hosts/= on *student.cs* or *core.cs*.

---++ Additional Configurations For Enabling Single Sign On (SSO)

Single sign on is the ability to log into any system within a particular Kerberos realm and then utilize the acquired Kerberos ticket to access further systems within the same realm without the need for further logons (offering of =username= and =password=). This is done by making the acquired Kerberos ticket _forwardable_ and instructing all logon servers (like =sshd=) to accept Kerberos tickets forwarded from other systems of the same realm. In our current setup there are three files that require the =forwardable= specification or its equivalent included.

   * =/etc/hosts=
   * =/etc/krb5.conf=
   * =/etc/pam.d/common-auth=
   * =/etc/ssh/sshd_config=
   * =/etc/ssh/ssh_config=
If you review the standard CSCF =/etc/krb5.conf= file (found in the ADAddSolaris10 document) and =/etc/pam.d/common-auth= (found in this document) you will see that the =forwardable= option has already been included for these files. However, by default, Kerberos forwardable tickets are not accepted by the native =sshd= server for Ubuntu.

---+++ Inspect =/etc/hosts=

Kerberos is very sensitive to hostname values. The output of the command =hostname -f= on the local Ubuntu system must produce the fully qualified domain name (FQDN) of the system in order for SSO to function. For a system with hostname =computer01.cs= in the DNS domain =uwaterloo.ca=, the FQDN would be =computer01.cs.uwaterloo.ca=. If it does not then examine the top of the local =/etc/hosts= file. There should be line beginning =127.0.1.1=, if not place in into the file beneath =127.0.0.1=. The top of the =/etc/hosts= file should read as follows.

<pre>127.0.0.1    localhost
127.0.1.1    _FQDN_of_local_system_ 
</pre>

After the FQDN you may have other accepted names for the local system on the =127.0.1.1= but the FQDN must be the first one.

---+++ Edit =/etc/ssh/sshd_config=

In this file the following lines must be enabled for the =sshd= server to accept a forwarded Kerberos ticket.

<pre>GSSAPIAuthentication yes
GSSAPICleanupCredentials yes
UsePAM yes
</pre>

The =UsePAM= option is usually set to yes by default as is the =GSSAPICleanupCredentials= option but it is best to check them in any case. =GSSAPIAuthentication= is by default disabled and so must definitely be changed.

---+++ Edit =/etc/ssh/ssh_config=

In this file the following line must be enabled (it is disabled by default) for the local =ssh= client programme to forward user Kerberos tickets.

<pre>GSSAPIDelegateCredentials yes
</pre>

---++ Additional Configurations For CSCF Ubuntu Workstations

This section introduces additional system modifications required for standard CSCF Ubuntu workstations.

---+++ User Login Access Control

To control user login access to a workstation (or even a centralized cpu server) one needs to utilize the =pam_access.so= module in the =common-auth= PAM stack as follows.

<pre>/etc/pam.d/common-auth:

auth     sufficient      pam_krb5.so forwardable ignore_root debug
auth     required        pam_unix.so try_first_pass nullok_secure
account  required        pam_access.so
</pre>

By default, adding in the =pam_access.so= module to the authentication PAM will have no effect on login rights unless those rights are specified in the =/etc/security/access.conf= file. The vendor supplied =access.conf= file is documented with several different examples of how to control user access through security groups, usernames and client addresses. The example =access.conf= file below outlines the default CSCF login restrictions when such restrictions are to be applied.

<pre>/etc/security/access.conf:
#
# Allow root or cscf-adm accounts to login locally through a device's console.
# This line is normally commented out. 
# It is only applied to CSCF admin master servers. All other managed systems
# rely upon members of the cscf-admin netgroup using sudo locally.
#
# + : root cscf-adm : cron crond :0 tty1 tty2 tty3 tty4 tty5 tty6 pts/0 pts/1 pts/2 pts/3 pts/4 pts/5 pts/6
#
# Allow root or cscf-adm accounts to login from a set of CSCF sactioned hosts or networks.
# asgard.cscf, linux.cscf, windows.cscf (maculata), xhier.cs, ubuntu1404-amd64.private.uwaterloo.ca
# And any device on CSCF's secure public VLAN (129.97.15.0/24).
#
+ : cscf-adm root : 10.15.152.4 172.19.152.4 172.19.15.200 172.19.15.11 172.16.58.8 129.97.15.0/24 
#
# Members of the cscf-admin netgroup may login as themselves locally or from any network address.
#
+ : @cscf-admin : ALL
#
# All other users are denied access.
#
- : ALL : ALL
</pre>

Note there is no =pam_access.so= module in Solaris, only Linux.

---+++ Creation Of Local Disk Space For Login Users

If you want a valid login user to have local disk space available to him on a standard CSCF Ubuntu workstation then one needs to apply the =pam_mkhomedir.so= module in the =common-session= PAM stack as follows.

<pre>/etc/pam.d/common-session:

session required      pam_mkhomedir.so nmask=0022 skel=/etc/skel/ silent
session optional      pam_krb5.so debug
session required      pam_unix.so
</pre>

If the home directory does not already exist on the local workstation, this modification will create a personal home directory for the user during login. It will be located in the local files system using the path specified for the user entry in the local =/etc/passwd= file or from the user's =unixHomeDirectory= attribute in the LDAP (Active Directory) database.

---++ Additional Topics

We would to have single sign-on capability for all hosts in a single Kerberos Realm. Moreover, having authenticated NFS mounts (something that is achieved on a per user login above if their home directories reside on a remote server).

---++ Querying DNS from Unix side for Windows domain servers

Clayton points out that one can do:

<verbatim>
   For CS-GENERAL (cs.uwaterloo.ca):
   % host -t SRV _ldap._tcp.cs.uwaterloo.ca 129.97.152.10                               Using domain server:
   Name: 129.97.152.10
   Address: 129.97.152.10#53
   Aliases:
   
   _ldap._tcp.cs.uwaterloo.ca has SRV record 0 100 389 serverus.cs.uwaterloo.ca.
   _ldap._tcp.cs.uwaterloo.ca has SRV record 0 100 389 intacta.cs.uwaterloo.ca.
   _ldap._tcp.cs.uwaterloo.ca has SRV record 0 100 389 viridis.cs.uwaterloo.ca.
   
   
   For CS-TEACHING (student.cs.uwaterloo.ca):
   % host -t SRV _ldap._tcp.student.cs.uwaterloo.ca 129.97.152.10
   Using domain server:
   Name: 129.97.152.10
   Address: 129.97.152.10#53
   Aliases:
   
   _ldap._tcp.student.cs.uwaterloo.ca has SRV record 0 100 389 canadenis.student.cs.uwaterloo.ca.
   _ldap._tcp.student.cs.uwaterloo.ca has SRV record 0 100 389 cyanea.student.cs.uwaterloo.ca.
   _ldap._tcp.student.cs.uwaterloo.ca has SRV record 0 100 389 eponina.student.cs.uwaterloo.ca. 
</verbatim>

---++ Specific examples within CS
   * SettingUpADGradPCs - Lawrence's notes for taking a standard grad PC and setting it up to use our AD

---++ External Links

Some of the following provide *possible* additional insights albeit they are largely unused for the creation of this document.

   * [[http://developer.novell.com/wiki/index.php/HOWTO:_Configure_Ubuntu_for_Active_Directory_Authentication]]
   * [[http://www.debuntu.org/ldap-server-and-linux-ldap-clients]]
   * [[http://technet.microsoft.com/en-us/library/bb496504.aspx Windows Security and Directory Services for UNIX Guide v1.0]], in particular, a [[http://technet.microsoft.com/en-us/library/bb463167.aspx][Appendix D: Kerberos and LDAP Troubleshooting Tips]].
Topic revision: r72 - 2024-10-30 - MariHassanzada
Information in this area is meant for use by CSCF staff and is not official documentation, but anybody who is interested is welcome to use it if they find it useful.
Other Webs
My links
- People
- CERAS
- WatForm
- Tetherless lab
- Ubuntu Main.HowTo
- eDocs
- RGG NE notes
- RGG
- CS infrastructure
- Grad images
Edit