LDAP Active Directory Kerberos Single Sign On

Introduction

This tutorial will guide you through the configuration of custo diagnostic for using LDAP / Active Directory for user synchronization and Kerberos for Single Sign On.

Active Directory is the LDAP implementation and Kerberos is a protocol that let you identify to other services with your windows logon. Having configured both you can achieve Single Sign On which means, that custo diagnostic will automatically use the user that is logged on to Windows for authentication and the user does not need to enter any passwords.

Prerequisites

• custo diagnostic 5.1 or up
• Windows Domain with Windows Server 2008 R2 or up
• You must be Windows Domain Administrator
• Basic understanding of LDAP
• Basic understanding on Kerberos configuration

Configuring custo diagnostic for LDAP

Open custo service center and navigate to Login→LDAP. This will open up a page that contains all configuration entries regarding the connection and mapping to the LDAP server.

Fill out the fields on the top of the page to have a basic setup. The page is more or less self-explanatory. Here is an example for a Windows Server Domain:

Note that filter filter for valid users can be appended if you activate "Import only users with valid profile mapping". The corresponding filter will be provided below for your information.

If you have trouble figuring out the correct filter settings, we recommend using a tool like LDAP Admin (http://www.ldapadmin.org/). This will let you figure out the correct configuration for your system more easily.

After you have finished, click on "Save Settings And Test". This will enforce the LDAP settings on the server. In order to check for errors, look at the log output at the end of the page:

Also check the imported users on the Administration → User page.

Mapping of users

As users are automatically imported into custo diagnostic from LDAP, mapping provides you a way to configure the users automatically with the correct settings, correct tenant and correct doctor information.
The first and most important mapping is the profile mapping. This will let you provide map profiles to LDAP user groups. In custo diagnostic, this includes user permissions that are configured for the profiles.

To add a mapping, click "Add Entry" (1) and some dialogs will open that will let you choouse the LDAP Group, Profile and mapping behaviour. Note that you cannot edit such a configured mapping but you can delete it (2) and add it again.
After you finished the mapping click on 3 to save the mapping.

The same workflow can be used to map users to doctors. This is normally used to give users different address print-outs on prints and PDFs.

Last step is to do the same with tenants, if you use a tenant system:

After this your configuration is nearly complete. Hit the button "Synchronize Users" and check in Administration → User if the users are correctly imported and have the correct profile, doctor and tenant mapping.

Login Options

The last step in this process is to activate LDAP login. Go to the Login page (1) and change Login Method to LDAP (2):

If you use Kerberos we will later change the Login Method to "Remote User". Now please check if the LDAP users can authenticate with the custo manager.

Kerberos

Kerberos lets you automatically login to the custo manager with you windows user if your user has a valid LDAP mapping. To do this you need to configure LDAP first.

Configuring Kerberos is somewhat complicated and for at least one step you need to be the Windows Domain Administrator. It involves configuring Tomcat (the application server that hosts the custo diagnostic server), so we use Tomcat as a synonym for custo diagnostic server at this place. Most of this manual is copied from https://tomcat.apache.org/tomcat-8.0-doc/windows-auth-howto.html

Kerberos (the basis for integrated Windows authentication) requires careful configuration. If the steps in this guide are followed exactly, then a working configuration will result. It is important that the steps below are followed exactly. There is very little scope for flexibility in the configuration. From the testing to date it is known that:

• The host name used to access the Tomcat server must match the host name in the SPN exactly else authentication will fail. A checksum error may be reported in the debug logs in this case.
• The SPN must be HTTP/<hostname> and it must be exactly the same in all the places it is used.
• The port number must not be included in the SPN.
• No more than one SPN may be mapped to a domain user.
• Tomcat must run as the domain account with which the SPN has been associated or as domain admin. It is NOT recommended to run Tomcat under a domain admin user.
• The domain name (DEV.LOCAL) is not case sensitive when used in the ktpass command, nor when used in jaas.conf
• The domain must be specified when using the ktpass command

There are three components to the configuration of the built-in Tomcat support for Windows authentication. The domain controller, the server hosting Tomcat, the web application wishing to use Windows authentication. The following sections describe the configuration required for each component.

The names of the three machines used in the configuration examples below are win-dc01.dev.local (the domain controller), win-tc01.dev.local (the Tomcat instance) and win-pc01.dev.local (client). All are members of the DEV.LOCAL domain.

Note: In order to use the passwords in the steps below, the domain password policy had to be relaxed. This is not recommended for production environments.

Domain Controller

These steps assume that the server has already been configured to act as a domain controller. Configuration of a Windows server as a domain controller is outside the scope of this how-to. The steps to configure the domain controller to enable Tomcat to support Windows authentication are as follows:

• Create a domain user that will be mapped to the service name used by the Tomcat server. In this how-to, this user is called tc01 and has a password of tc01pass.
• Map the service principal name (SPN) to the user account. SPNs take the form <service class>/<host>:<port>/<service name>. The SPN used in this how-to is HTTP/win-tc01.dev.local. To map the user to the SPN, run the following:

  setspn -A HTTP/win-tc01.dev.local tc01

• Generate the keytab file that the Tomcat server will use to authenticate itself to the domain controller. This file contains the Tomcat private key for the service provider account and should be protected accordingly. To generate the file, run the following command (all on a single line):

  ktpass /out c:\tomcat.keytab /mapuser tc01@DEV.LOCAL
            /princ HTTP/win-tc01.dev.local@DEV.LOCAL
            /pass tc01pass /kvno 0 /crypto ALL

• Create a domain user to be used on the client. In this how-to the domain user is test with a password of testpass.

The above steps have been tested on a domain controller running Windows Server 2008 R2 64-bit Standard using the Windows Server 2003 functional level for both the forest and the domain.

Configure Tomcat (the custo diagnostic server)

Copy the tomcat.keytab file created on the domain controller to <custo diagnostic server installation directory>/conf/tomcat.keytab.

Edit the file <custo diagnostic server installation directory>/conf/krb5.ini so it looks like this:

Edit the file <custo diagnostic server installation directory>/conf/jaas.conf so it looks like this:

Note the correct usage of forward and backward slashes when editing the files.

Please copy the editied files and the keytab file to a save location. 

Now you can change Login Method to Remote User:

As the last step, please restart the custo diagnostic server now.

For testing Kerberos authentication without using the custo manager, you can use the curl utility that is installed in the same folder as the custo diagnostic client:

If everything works and the logged in windows user is allowed to use custo diagnostic then this command should return "true".