LiveZilla Live Help

You are here

Integrating a Linux Host with a Windows AD for Kerberos SSO authentication

Updated Documentation

Are you looking for the updated documentation for the latest SafeSquid SWG?
Please access the latest documentation at http://docs.safesquid.com


Getting Started - The Preparatory Steps

To keep the discussion easy to understand and replicate, we will use an example, and set out the process in ordered sequence of steps. We will also include steps for validating to ensure if any of the steps may not have been correctly taken.

In our example we have a Microsoft Windows AD setup as follows:

  1. FQDN of Microsoft AD Domain: ESXI1.LOCAL
  2. FQDN of Domain Controller: win2k8dc.esxi1.local
  3. IP address of our Domain Controller: 192.168.250.100

We will use additionally use a Windows Desktop, just for the purpose of validating our efforts.

  1. FQDN of our Windows Test Desktop: wintest.esxi1.local
  2. IP address of our Windows Test Desktop: 192.168.250.20

We are using a Linux based host for deploying our Kerberos based SafeSquid

  1. FQDN of our Linux host: safesquid1.esxi1.local
  2. IP address of our Linux host: 192.168.250.110

** VERY IMPORTANT **

Obviously your setup would have different names for the above, so you must replace the above information appropriately. You can copy this whole article into some editor and perform a smart search and replace, to produce a documented instruction for your enterprise. But do ensure that your search and replace is case sensitive, and does not consider "esxi1.local" as "ESXI1.LOCAL" or "http" as "HTTP". Any mistake with that and you will be consuming tens of cups of coffee, and re-filling them with tears!


Test Network Connectivity

*Validate our IP addresses are correct and the systems are reachable on the network.

On EACH of the 3 above computers do the following

  1. ping the Domain Controller IP address
  2. ping the Windows Test Desktop IP address
  3. ping the Linux host IP address

ping 192.168.250.100
ping 192.168.250.20
ping 192.168.250.110

If any of the above seems to be unsatisfactory, fix the TCP/IP network configurations, before proceeding.

Validate that all our systems are using the same DNS provider

In a Microsoft AD based network, it is highly recommended to use the DNS provider that eusually defaults to the Domain Controller itself.

On the Windows Systems these are specified in the TCP/IP configuration

On the Linux host view and modify /etc/resolv.conf
confirm that it reads as follows:

# search <name of our domain>
search esxi1.local
# nameserver <DNS server specified in our AD, usually domain controller in AD>
nameserver 192.168.250.100

Validate that IP of all our systems are resolvable by our DNS provider

Add the Linux host safesquid1 as a New Host in the DNS server's configuration such that it's FQDN  automatically defaults to safesquid1.esxi1.local.


On EACH of 3 systems use nslookup as follows to confirm that DNS is effectively serving our requirements.

nslookup safesquid1.esxi1.local
nslookup wintest.esxi1.local
nslookup win2k8dc.esxi1.local

If any of the above seems to be unsatisfactory, fix the DNS server configuration, by restarting the service or re-booting the Domain Controller host, before proceeding.

Validate each of the systems has same time and preferably timezone

Rest assured this is a very important step, and many technicians have learnt about it's importance the hard-way. Before you disagree, do lookup the problems reported with clock skew when technicians have attempted kerberos authentication setup.

Usually on a Windows 2003 / 2008 Domain controller, the tab for Internet time, in the Date / time configuration is greyed out. The Default AD group policy requires all the Domain computer to use the time set on the Domain Controller as the reference for time. This also effectively means that the Domain Controller must be used as the reference NTP server.

Validate the Domain Computer wintest is conforming to this policy.

In any case should you prefer to have a different reference NTP server for your network, it is possible.

w32tm /config /update remote.ntp.server

Suppose we would like to use a remote NTP server remote.ntp.server as the time reference across our network, execute the following 2 commands on ALL the Windows based systems including the Domain controller.

w32tm /config /syncfromflags:MANUAL /manualpeerlist:

On the Linux host, defining the reference NTP server can be done by executing

/usr/sbin/ntpdate -b -s remote.ntp.server

To ensure that the time synchronization remains permanent across reboot you can appropriately append the following lines into /etc/rc.local

# synchronize the local system time from a remote NTP service
/usr/sbin/ntpdate -b -s remote.ntp.server
# Update the host’s hardware clock with the updated system time
/sbin/hwclock --systohc

In ALL the time synchronization steps above command you may use the IP address or the FQDN of remote.ntp.server, but must verify things are working as desired by reviewing the Windows Event Logs, and the Linux system logs.

If you have achieved all the steps discussed above, you can smile and relax a bit because your stage is now set to accomplish the rest very comfortably.

Note - if the above steps had taken more than 30 minutes, it is highly recommended to take a coffee break!


Activities to be performed the Domain Controller for Generating Kerberos Keytabs

We are now ready to generate our Kerberos keytabs, that will complete the integration of our Linux Host and safesquid proxy service running on it.

This essentially requires us to create a user account, with the same name as that of our Linux host, associate it with one or more ServicePrincipalName and then create keytab files that map the encrypted credentials of the user (linux host), such that the credentials may be used in Kerberos environments.

Note that everything here onwards is case-sensitive so "http" is not same as "HTTP" and you must be careful, about these.

Create a new user on the Windows Domain Controller

Create a new user account in AD using Active Directory Users and Computers Snap-in and set the password.

The account does NOT need to be xxxx.<domain_fqdn> — just the hostname will do.
In our case hostname of our our linux host is safesquid1 whereas its fqdn is safesquid1.esxi1.local

  1. We will therefore create a new user with user logon name as safesquid1 and NOT as safesquid1.esxi1.local
  2. Do NOT select "User must change password at next logon" (remember the password).
  3. Select "Password never expires"

Create the SPNs associated with this account on the Active Directory KDC

Reference: http://technet.microsoft.com/en-us/library/cc773257%28v=ws.10%29.aspx

The Setspn command-line tool is included when you install Windows Server 2003 Support Tools from the product CD or from the Microsoft Download Center (http://go.microsoft.com/fwlink/?LinkId=100114). For more information about how to install Windows Support Tools from the product CD, see Install Windows Support Tools (http://go.microsoft.com/fwlink/?LinkId=62270).

In Active Directory, the servicePrincipalName (SPN) attribute is a multivalued, non linked attribute that is built from the DNS host name. The SPN is used in the process of mutual authentication between the client and the server hosting a particular service. The client finds a computer account based on the SPN of the service to which it is trying to connect.

The setspn.exe command-line tool allows you to read, modify, and delete the Service Principal Names (SPN) directory property for an Active Directory service account. SPNs are used to locate a target principal name for running a service. You can use Setspn to view the current SPNs, reset the account's default SPNs, and add or delete supplemental SPNs.

When you manipulate SPNs with the Setspn tool, the SPN must be entered in the correct format. The format of an SPN is serviceclass/host:port/servicename, in which each item represents a name or value. Unless the service name and port are not standard, you do not have to enter them when you use Setspn.

For the purpose of Windows Integrated Authentication, a user's system would require our SafeSquid proxy server to be available for host and HTTP based authentication, so the following should be necessary:

 

setspn -A hosts/safesquid1.esxi1.local safesquid1

The inclusion of  hosts principle is optional.

before it invokes the safesquid executable with the rest of the command-line parameters.

 

setspn -A HTTP/safesquid1.esxi1.local safesquid1

 

To validate the successful execution of the above 2 setspn executions, do:

setspn -U -l safesquid1

If everything that you did before the coffee break went nicely, these 3 executions of setspn are expected to go smoothly, else it would be interesting and important to share the results of these commands, with the SafeSquid Tech Support.

You however need not close the Windows Command Prompt window, yet if everything's going nicely. There's a couple of more commands that you need to execute for the next immediate step.

Use Ktpass to generate exportable keytabs

We are now ready to create the Kerberos Keytabs on the Windows Domain Controller, we can reuse the command prompt that we used to do the SPN setup, but we can open a new window too if you prefer.

We will now use Ktpass.exe Kerberos Keytab Setup command-line tool.

Ktpass enables an administrator to configure a non-Windows Server 2003 Kerberos service as a security principal in the Windows Server 2003 Active Directory.
KtPass configures the server principal name for the host or service in Active Directory and generates an MIT-style Kerberos "keytab" file containing the shared secret key of the service.
The tool thus allows UNIX-based services that support Kerberos authentication to use the interoperability features provided by the Windows Server 2003 / 2008 Kerberos KDC service.

Unlike Kerberos principal names, Windows Server 2003 account names do not have multiple parts.
For this reason, it is not possible to directly create an account of the name Sample/Unix1.microsoft.com.
Such a principal instance is created by using the service principal name mappings.
The keytab output file is generally used to replace or merge with the MIT Kerberos /etc/krb5.keytab file.

We will use this command-line tool to create 2 keytab files, that we will copy to the Linux host and  merge them into a single keytab file in Linux Host, for use by our SafeSquid proxy service.
However for security, we will not use the default keytab path /etc/krb5.keytab, instead we will produce one at /opt/safesquid/bin/security/HTTP.keytab

Like any other Kerberos-aware application, the keytab to be used can be specified as an environment variable KRB5_KTNAME, in which the application is used. SafeSquid’s init script simply sets this to /opt/safesquid/bin/security/HTTP.keytab by calling

export KRB5_KTNAME=/opt/safesquid/bin/security/HTTP.keytab

before it invokes the safesquid executable with the rest of the command-line parameters.

<password> in the following two executions is the same password that you set for the new user safesquid1 that you created in the AD using Active Directory Users and Computers Snap-in just after the coffee break.

 

ktpass -princ hosts/safesquid1.esxi1.local@ESXI1.LOCAL -pass <password> -mapuser safesquid1 -pType KRB5_NT_PRINCIPAL -out c:\temp\safesquid1.host.keytab

ktpass -princ HTTP/safesquid1.esxi1.local@ESXI1.LOCAL -pass <password> -mapuser safesquid1 -pType KRB5_NT_PRINCIPAL -out c:\temp\safesquid1.HTTP.keytab

In the above screenshot we can see that the encryption type is (RC4-HMAC), by default, if no encryption type is mentioned

You can also specify the encryption type

ktpass -princ host/safesquid1.esxi1.local@ESXI1.LOCAL -pass <password> -mapuser safesquid1 -mapOp set -crypto DES-CBC-MD5 -pType KRB5_NT_PRINCIPAL +DesOnly -out c:\temp\safesquid1.host.keytab

 

If encryption type is changed then you should

Verify now that files c:\temp\safesquid1.host.keytab and c:\temp\safesquid1.HTTP.keytab exist.

If they do, log into your Linux host as root user and copy keytabs into /opt/safesquid/bin/security/

confirm that /opt/safesquid/bin/security/safesquid1.host.keytab and /opt/safesquid/bin/security/safesquid1.HTTP.keytab are now available on your Linux Host

If all's well you are now ready to merge the two keytabs into one, initialize the resulting keytab, and set it for use by your SafeSquid proxy service.

Just in case you are a bit overwhelmed, this might be a good time to freshen up with your second coffee break! The next steps are the trickiest ones, and slightest mistake can send you into hours of painful troubleshooting.


Activities to be performed the Linux Host for using the Kerberos Keytabs

Modifying the default krb5.conf

Confirm that kerberos krb5 client and utility software is already installed in your system.
You should then be able to locate the default krb5.conf as /etc/krb5.conf

The required package can be installed by following command:-

aptitude install krb5-user

Reference: http://www.crypt.gen.nz/kerberos/admin.html

The krb5.conf file contains Kerberos configuration information, including the locations of KDCs and admin servers for the Kerberos realms of interest, defaults for the current realm and for Kerberos applications, and mappings of host names onto Kerberos realms. Normally, you should install your krb5.conf file in the directory /etc. You can override the default location by setting the environment variable `KRB5_CONFIG'.

The krb5.conf file is set up in the style of a Windows INI file. Sections are headed by the section name, in square brackets. Each section may contain zero or more relations, of the form:

foo = bar

 

fubar = {
       foo = bar
       baz = quux
}

The krb5.conf file may contain any or all of the following seven sections:

libdefaults
Contains default values used by the Kerberos V5 library.

appdefaults
Contains default values used by Kerberos V5 applications.

realms
Contains subsections keyed by Kerberos realm names. Each subsection describes realm-specific information, including where to find the Kerberos servers for that realm.

domain_realm
Contains relations which map domain names and subdomains onto Kerberos realm names. This is used by programs to determine what realm a host should be in, given its fully qualified domain name.

logging
Contains relations which determine how Kerberos programs are to perform logging.

capaths
Contains the authentication paths used with direct (nonhierarchical) cross-realm authentication. Entries in this section are used by the client to determine the intermediate realms which may be used in cross-realm authentication. It is also used by the end-service when checking the transited field for trusted intermediate realms.

kdc
For a KDC, may contain the location of the kdc.conf file.

However for our purpose libdefaults, realms and domain_realm sections are the only sections that should normally need any change.

In case your krb5 had prompted you for information and you had supplied them correctly, your /etc/krb5.conf should look quite as below.

** NOTE ** Remember things are case sensitive here, so whatever appears here in upper case, MUST remain in upper case.

[logging]

default = FILE:/var/log/krb5libs.log
kdc = FILE:/var/log/krb5kdc.log
admin_server = FILE:/var/log/kadmind.log

[libdefaults]

ticket_lifetime = 24000
default_realm = ESXI1.LOCAL

; for Windows 2003

;          default_tgs_enctypes = rc4-hmac des-cbc-crc des-cbc-md5
;          default_tkt_enctypes = rc4-hmac des-cbc-crc des-cbc-md5
;          permitted_enctypes = rc4-hmac des-cbc-crc des-cbc-md5

; for Windows 2008 with AES

;        default_tgs_enctypes = aes256-cts-hmac-sha1-96 rc4-hmac des-cbc-crc des-cbc-md5
;        default_tkt_enctypes = aes256-cts-hmac-sha1-96 rc4-hmac des-cbc-crc des-cbc-md5
;        permitted_enctypes = aes256-cts-hmac-sha1-96 rc4-hmac des-cbc-crc des-cbc-md5

; for MIT/Heimdal kdc no need to restrict encryption type

[realms]

ESXI1.LOCAL = {
kdc = win2k8dc.esxi1.local:88
admin_server = win2k8dc.esxi1.local:749
default_domain = esxi1.local

 }

[domain_realm]

.esxi1.local = ESXI1.LOCAL
esxi1.local = ESXI1.LOCAL

[pam]

debug = false
ticket_lifetime = 36000
renew_lifetime = 36000
forwardable = true
krb4_convert = false

 

The above should be enough, though it is advisable to copy the values for  default_tgs_enctypes , default_tkt_enctypes and permitted_enctypes in the [libdefaults] section of your krb5.conf. Depending upon your kerberos distribution ( MIT or Heimdal) these may or may not be there. Note: ";" is used here to comment a line and deleting the ";" will uncomment it, and make it effectively in use.

These lines may not be necessarily required, but you can safely copy them as they appear here. Just in case it's not your day, you might need to put in some more efforts in trouble shooting later, and these will then come in handy.

Merge the two keytabs produced earlier with ktpass

Remember we copied the 2 keytab files into /opt/safesquid/bin/security now is the time to merge them into HTTP.keytab

Change to the directory /opt/safesquid/bin/security and we will now use the ktutil command to accomplish the merging.

Invoke the ktutil prompt as:

ktutil

Now within the ktutil command prompt invoke these 4 commands

rkt /opt/safesquid/bin/security/safesquid1.host.keytab

rkt /opt/safesquid/bin/security/safesquid1.HTTP.keytab

wkt /opt/safesquid/bin/security/HTTP.keytab

q

The first rkt invocation above loads the data in safesquid1.host.keytab, similarly the second rkt invocation loads up from safesquid1.HTTP.keytab and appends to the previously loaded data in memory. The wkt invocation systematically dumps the previously loaded data into HTTP.keytab. The q command simply exits from the ktutil prompt.

If you did things correctly you should be able to find /opt/safesquid/bin/security/HTTP.keytab
However before proceeding to use it, you may want to validate that the newly produced keytab, exists and contains usable data. We can use klist command here to inspect the keytab. Since most times the problem reported is about encryption method mismatch, it makes sense to check the encryption type used in the HTTP.keytab with the following command:

klist -e -k -t /opt/safesquid/bin/security/HTTP.keytab

klist is used to check the generation of keytab file and the encryption type in which it is generated.

In the next step we are going to initialize the HTTP.keytab so that it can be used by SafeSquid proxy service.

kinit the HTTP.keytab

The keytab file HTTP.keytab that we produced with ktutil by merging the two keytab files, must be initialized now before use. The initialization process involves connecting to the Windows Domain Controller, as specified in the krb5.conf file, and getting a ticket from the Domain Controller's Ticket Granting Service.

kinit -k –t /opt/safesquid/bin/security/HTTP.keytab HTTP/safesquid1.esxi1.local

If prompted for password, enter the <password> we used for the safesquid1 user we created just after the first recommended coffee break.

And you can invoke klist to verify that it contains the SPNs by calling klist on the command prompt.

klist

If you are successful, the prompt will be returned after service principal is defined; if unsuccessful, an error will be returned to the console.

You can verify that authentication worked by using klist to see the TGT for the principal.

If all's well until this point, you are almost done, and SafeSquid is just a step away from using the initialized keytab.

Setting up SafeSquid service to use the initialized Kerberos keytab

Configuring SafeSquid Startup parameters

SafeSquid's executable binary uses command-line parameter -K  <kerberos_service_principal_name>

This can be set as safesquid's startup parameter by setting KRB_SERVICE_PRINC to HTTP/safesquid1.esxi1.local@ESXI1.LOCAL in init.d/startup.conf

Change access rights of two files

chmod 440 /opt/safesquid/bin/security/HTTP.keytab

chown ssquid:root /opt/safesquid/bin/security/HTTP.keytab

And that is almost you that you should normally need to do.

A Kerberos-aware application by default uses /etc/krb5.keytab, however for security reasons we had created a different keytab as /opt/safesquid/bin/security/HTTP.keytab. The changed location can be notified to an application by modifying the environment parameter KRB5_KTNAME. Typically under bash you could do this by invoking:

export KRB5_KTNAME=/opt/safesquid/bin/security/HTTP.keytab 

SafeSquid's init script /etc/init.d/safesquid when invoked to start the safesquid service, automatically exports KRB5_KTNAME to /opt/safesquid/bin/security/HTTP.keytab to the environment under which the actual executable binary is executed. However if you have to invoke safesquid manually by executing the safesquid executable on the command prompt, remember to do so in the console, in which you are operating, you must invoke the above export command manually. And remember any other kerberos related activities that you undertake on this console will use HTTP.keytab and NOT /etc/krb5.keytab

Now you can restart the safesquid proxy service with the usual command:

 /etc/init.d/safesquid start

and on the console leave this tail command running

tail -f /opt/safesquid/safesquid/logs/extended/extended.log

In our next steps we will be validating the Windows Integrated authentication, and the log lines here will reveal the success of our undertaken steps.


Testing your Kerberos SSO authentication setup

Configure Authentication in SafeSquid’s Access Restrictions.

SafeSquid’s policy configurations are managed by it’s WebGUI. We can access the WebGUI from any system authorized, as per it’s Access Restrictions configuration section (by default ALL are allowed). To ensure that we do not get locked out, we will in the following steps configure the Access Restrictions section of SafeSquid to enable the SSO authentication, and then to  enable authentication for only our Test Client wintest.esxi1.local

  1. Configure your Internet browser to use safesquid1.esxi1.local:<port_usually_8080> as your proxy server.

Note you should NOT be using the <IP address>:<port> format now.

Go to http://safesquid.cfg/config select Access Restrictions in the drop down menu.

  1. In the Global sub-section, set NTLM Authentication to true.

  1. Add a new entry:
  1.  In the IP address put 192.168.250.20 (IP address of wintest.esxi1.local, remember we had designated that system to be our first test client in very initial preparatory steps).
  2.  Enable PAM Authentication.
  3.  Click submit.

  1.  From the wintest.esxi1.local system. Configure the Internet browser to use safesquid1.esxi1.local:<port_usually_8080> as proxy server.
  2.  And in the Internet Explorer->tools->advanced make sure that the option for "Use Windows Integrated Authentication" has been selected.

  1. Access the internet, confirm that you can access the web the way should be.
  2. Take a look at the output of the tail command that you had earlier left running on the Linux console.

You should be able to see request from the user that had logged into the wintest.esxi1.local system and the user should be getting identified as <username>@<ESXI1.LOCAL>@192.168.250.20

If you can confirm that, Hurrah you are done!

To enable Windows Integrated authentication for the rest of your enterprise, modify the entry you created in the Access Restrictions for IP 192.168.250.20 and simply leave the IP address field blank.