...
Kerberos is a method that let you identify to other services with your windows logon. Having configured LDAP and Kerberos 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.
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.
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
Steps to configure the Kerberos System:
...
The first two steps has to be performed by an domain administrator.
Create Domain User for Apache Tomcat
This step has to be done by the domain administrator.
Create a normal domain user. This user does not have to have specific access rights - but it must be able to authenticate/login with this user to the Windows Domain.
In our example we name the user "custoKerberos", password "secretPW!" (← don't take it in real life). the only membership is "Domain User". Please make sure, that the password does not have to be changed, and will not expire.
Create keytab-File
This step has to be done by the domain administrator.
Please use the following command to create the keytab-file.
ktpass -princ HTTP/win-tc01.yourdomain@YOURDOMAIN.DE
-mapuser custoKerberos@yourdomain -crypto rc4-hmac-nt
-ptype KRB5_NT_PRINCIPAL -pass tc01pass
-out c:\tomcat.keytab
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.
...
Its worth to write down all information before you start.
E.g. In our Example we used the following names:
Example used | |
---|---|
WINS-Domain | XY-HOSPITAL |
DNS Domain | xy-hospital.xy |
Kerberos User | custoKerberos PW secretPW! |
Servername | tstsrv01-2016 |
Domain Controller | tstdc01 |
General Information
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:
...
setspn -A HTTP/win-tc01.dev.local tc01
...
Create Domain User for Apache Tomcat
This step has to be done by the domain administrator.
Create a normal domain user. This user does not have to have specific access rights - but it must be able to authenticate/login with this user to the Windows Domain.
In our example we name the user "custoKerberos", password "secretPW!" (← don't take it in real life). the only membership is "Domain User". Please make sure, that the password does not have to be changed, and will not expire.
Create keytab-File
This step has to be done by the domain administrator.
Watch out: Some entries are CASE SENSITIVE!
Please use the following command to create the keytab-file.
ktpass -princ HTTP/tst2srv01-2016.xy-hospital.xy@XY-HOSPITAL.XY
-mapuser custoKerberos@xy-hospital.xy
-crypto rc4-hmac-nt -ptype KRB5_NT_PRINCIPAL
-pass secretPW! -out "C:\Program Files\custo diagnostic server\conf\tomcat.keytab"
This command:
- links the service principal name "HTTP/tst2srv01-2016.xy-hospital.xy@XY-HOSPITAL.XY" to your custoKerberos-User (and defines the authentication/crypto way)
- stores the private key in tomcat.keytab file
This file contains the Tomcat private key for the service provider
...
. To generate the file, run the following command as a domain administrator (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
...
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:
...
[libdefaults]
default_realm = DEV.LOCAL
default_keytab_name = FILE:<custo diagnostic server installation directory>\conf\tomcat.keytab
default_tkt_enctypes = rc4-hmac,aes256-cts-hmac-sha1-96,aes128-cts-hmac-sha1-96
default_tgs_enctypes = rc4-hmac,aes256-cts-hmac-sha1-96,aes128-cts-hmac-sha1-96
forwardable=true
[realms]
DEV.LOCAL = {
kdc = win-dc01.dev.local:88
}
[domain_realm]
dev.local= DEV.LOCAL
.dev.local= DEV.LOCAL
. You can do this step on the server where tomcat runs on.
Configure Apache Tomcat
Watch out: Some entries are CASE SENSITIVE! Some Path-Names need forward-slashes!
We attached the file to download it for you. Please do not use copy/paste from the code below - use the files attached to this website.
Replace / Edit krb5.ini and jaas.conf file, located in your ...\custo diagnostic server\conf Directory
krb5.ini (Downlaod krb5.ini)
Code Block |
---|
[libdefaults]
debug = true
default_realm = XY-HOSPITAL.XY
dns_lookup_kdc = false
default_keytab_name = FILE:C:\Program Files\custo diagnostic server\conf\tomcat.keytab
krb4_config = /etc/krb.conf
krb4_realms = /etc/krb.realms
kdc_timesync = 1
ccache_type = 4
forwardable = true
proxiable = true
[realms]
XY-HOSPITAL.XY = {
kdc = tst2dc01.xy-hospital.xy
admin_server = tst2dc01.xy-hospital.xy
default_domain = xy-hospital.xy
}
[domain_realm]
.xy-hospital.xy = XY-HOSPITAL.XY
[login]
krb4_convert = true
krb4_get_tickets = false |
jaas.conf (doanload jaas.conf)
We attached the file to download it for you. Please do not use copy/paste from the code below - use the files attached to this website.
Attention !
principal Name must be IDENTICAL (case sensitive) to the principal Name used with ktpass
Be aware of forward slahes in file Name
Code Block |
---|
|
Edit the file <custo diagnostic server installation directory>/conf/jaas.conf so it looks like this:
com.sun.security.jgss.krb5.initiate |
...
{ com.sun.security.auth.module.Krb5LoginModule |
...
required doNotPrompt=true |
...
principal="HTTP/ |
...
tst2srv01- |
...
2016. |
...
xy-hospital.xy@XY-HOSPITAL.XY" useKeyTab=true keyTab="C:/Program Files/custo diagnostic server/conf/tomcat.keytab" |
...
storeKey=true; |
...
}; |
...
com.sun.security.jgss.krb5.accept |
...
{ com.sun.security.auth.module.Krb5LoginModule |
...
required doNotPrompt=true |
...
principal="HTTP/ |
...
tst2srv01- |
...
2016. |
...
xy-hospital.xy@XY-HOSPITAL.XY" useKeyTab=true keyTab="C:/Program Files/custo diagnostic server/conf/tomcat.keytab" |
...
storeKey=true; |
...
}; |
...
|
Please copy the editied files and the keytab file to a save location.
...
As the last step, please restart the custo diagnostic server now.
Please do do your test on a normal pc - NOT using an administrator/special account. Use a normal domain account.
If everything works and the logged in windows user is allowed to use custo diagnostic then this command should return "true".
Debugging & Testing
First check whether the LDAP works. Switch back to "LDAP" login-method, and check whether the test-user can login with windows password.
Switch back to Kerberos/Remote-Login-Method to go ahead.
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:
|
...
You can add the following switches to the Java command line (via Configure custo diagnostic server in Startmenu):
|
After restarting Tomcat, you will find logging information in stdout and stderr files in the <custo diagnostic server installation directory>/logs directory
and <custo diagnostic data directory>/logs
Typical Error Messages and possible cause:
- Cannot Obtain Password: Apache Tomcat looks for the password somewhere.
Meaning, that it either cannot find the tomcat.keytab file (file location?) or the service principal name used in jaas.conf, tomcat.keytab file. - Cannot Sign In (Without Cannot Obtain Password): Tomcat gets the credentials from tomcat.keytab file, but it cannot sign in to the domain/domaincontroller. May be the Service Principal Name used in the configuration files differ from the one used with ktpass?
- Cannot locate Domain Controller. The krb5.ini leads from the domain name to the domain controller.