PAM configuration for Windows Active Directory

If you want to configure OS4X to authentificate users with the configured username via a centralized Windows Active Directory service, you have to configure the PAM security system of the underlying Unix environment.

This documentation is based on the OS4Xvirtual VMware image, which uses the latest Debian Linux distribution. If you have any other distribution, you may re-use these information in order to configure your environment accordingly.

Configuring the connectivity consists of several steps, which are described here:

Declarations

In this documentation, several values will be used for hostnames, domain name, usernames and password. These are only examples and must be changed according to your environment.

AD server:

Hostname and aliases: 192.168.1.65
     name alias: w2k8
     local hostname seen from Windows side: dc.w2k8.c-works.net
Active directory domain name: w2k8.c-works.net
Kerberos realm: W2K8.C-WORKS.NET

(The kerberos realm is the domain name in upper case characters!)

User for connecting to domain (with administrative rights, but without permission to login interactively on AD server):

Username: pamauth
Password: Test1234

User to be authentificated (as an example) and configured in OS4X:

Username: adUsername1
Password: OS4Xpwd

Username: os4x
Password: Test1234

All commands on the Linux side are executed in the context of the user "root".

Network availability

The AD server must be reachable via network on the Linux side:

os4xvirtual:~# ping -c 3 dc.w2k8.c-works.net
PING dc.w2k8.c-works.net (192.168.1.65) 56(84) bytes of data.
64 bytes from 192.168.1.65: icmp_req=1 ttl=128 time=0.762 ms
64 bytes from 192.168.1.65: icmp_req=2 ttl=128 time=0.737 ms
64 bytes from 192.168.1.65: icmp_req=3 ttl=128 time=0.659 ms

--- dc.w2k8.c-works.net ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2013ms
rtt min/avg/max/mdev = 0.659/0.719/0.762/0.049 ms

Synchronize time

The underlying security model relies on synchronized time between (Active Directory) server and (Linux OS4X) client). Windows Active Directory servers offer a NTP server which can be used for time synchronization.

ntpdate dc.w2k8.c-works.net

If the domain controller server doesn't run as time server, be sure to use the same time source for local and remote time synchronization.

Install required software

The PAM user authentification relies on two packages:

• Winbind
• Samba
• Kerberos

If not installed already, install these packages through the local Linux packaging system:

apt-get install winbind samba krb5-kdc

During installation of Kerberos, you will be asked for a default realm: leave this entry empty, we will configure it afterwards.

Configure Samba

You have to configure the Samba component. Edit the file "/etc/samba/smb.conf" with your favorite text editor and make the following changes in the configuration section 'global':

[global]
       security = ads
       realm = W2K8.C-WORKS.NET
       password server = 192.168.1.65
       workgroup = W2K8
       client ntlmv2 auth = yes
       encrypt passwords = yes
       winbind use default domain = yes
       winbind refresh tickets = yes
       restrict anonymous = 2

Restart services

In order to activate the changes, restart the needed services:

os4xvirtual:/etc/samba# /etc/init.d/winbind stop
Stopping the Winbind daemon: winbind.
os4xvirtual:/etc/samba# /etc/init.d/samba restart
Stopping Samba daemons: nmbd smbd.
Starting Samba daemons: nmbd smbd.
os4xvirtual:/etc/samba# /etc/init.d/winbind start
Starting the Winbind daemon: winbind.

Configure Kerberos

Run the following command in order to configure Kerberos interactively:

 dpkg-reconfigure krb5-config

Answer the following question according to our default values as described above:

Default Kerberos version 5 realm: W2K8.C-WORKS.NET
Add locations of default Kerberos servers to /etc/krb5.conf? - Yes
Kerberos servers for your realm: dc.w2k8.c-works.net (the IP address 192.168.1.65 would be valid, too)
Administrative server for your Kerberos realm: dc.w2k8.c-works.net (the IP address 192.168.1.65 would be valid, too)

Initialize Kerberos

Setting up Kerberos with the Active Directory server will be finished via authentificating as administrative user of the domain:

kinit pamauth@W2K8.C-WORKS.NET

Be sure to give the Kerberos realm name in uppercase characters completely!

Join domain

In order to join the domain, execute the following command, passing the username of a valid administrative user of the domain:

net ads join -U pamauth

After giving the correct password, an informational output must state that the domain join succeeded (warnings about DNS updates may appear, they can be ignored):

os4xvirtual:~# net ads join -U pamauth
Enter pamauth's password:
Using short domain name -- W2K8
Joined 'OS4XVIRTUAL' to realm 'w2k8.c-works.net'
No DNS domain configured for localhost. Unable to perform DNS Update.
DNS update failed!

Configure PAM to use Winbind

Create or edit the file "/etc/pam.d/os4x" to contain the following line in order to allow OS4X PAM authentification to use Winbind (which now uses Active Directory via Kerberos):

auth required pam_winbind.so

Restart Winbind a last time

Restart Winbind for a last time in order to refresh its ressources:

os4xvirtual:/etc/samba# /etc/init.d/winbind start
Starting the Winbind daemon: winbind.

Configure user to authentificate via PAM

You can now configure your OS4X Webaccess users to use PAM as authentification method:

You can also use the username declaration including the domain name:

Troubleshooting

If authentification fails without any reason, a good starting point to react is to restart Winbind (before raising loglevels in Winbind, Samba and/or Kerberos):

os4xvirtual:/etc/samba# /etc/init.d/winbind restart

Any logging in Samba, Winbind, Kerberos and the kernel logs contain reasons why authentification may have failed.

Login not possible

If users cannot login into OS4X Webaccess anymore, it may be possible that a specific Samba version is causing trouble (especially when using an actual version of Debian, used in OS4Xvirtual). When re-joining the domain, you will get the following error message:

Failed to join domain: failed to lookup DC info for domain '<Domain Name>' over rpc: Access denied
return code = -1

You can downgrade to the latest known working version:

apt-get install samba=2:3.6.6-6+deb7u7 \
 samba-common=2:3.6.6-6+deb7u7 libwbclient0=2:3.6.6-6+deb7u7 \
 libnss-winbind=2:3.6.6-6+deb7u7 libpam-winbind=2:3.6.6-6+deb7u7\
 winbind=2:3.6.6-6+deb7u7

External links:

https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=821811

https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=820982