KerberosAuthentication

Kerberos Authentication

RunaWFE Free Workflow System (BPMS) Version 4.5.0

© 2003 - 2015, Consulting Group Runa

© 2015 - 2024, "Process Technologies" Ltd, this document is available under GNU FDL license. RunaWFE Free is an open source system distributed under a LGPL license (http://www.gnu.org/licenses/lgpl.html).

# Terms and definitions

term	description	example
DOMAIN_NAME	domain name	test.com
REALM	for Active Directory it is always DOMAIN_NAME in uppercase	TEST.COM
SERVER_NAME	name of the computer RunaWFE Server is installed on	runaserver
SERVER_USER	the username, RunaWFE Server is working under	runauser
SERVER_SPN	SPN (Service principal name), which corresponds to SERVER_USER FQDN format for Windows2008: HTTP/{SERVER_NAME}.{DOMAIN_NAME} FQDN format for Windows2003: HTTP/{SERVER_NAME}.{DOMAIN_NAME}@{REALM} NetBIOS format for Windows2008: HTTP/{SERVER_NAME} NetBIOS format for Windows2003: HTTP/{SERVER_NAME}@{REALM}	HTTP/runaserver.test.com HTTP/runaserver.test.com@TEST.COM HTTP/runaserver HTTP/runaserver@TEST.COM
KEYTAB_PATH	The path to keytab-a key file, where user password hashes are stored	C:/runawfe/krb5.keytab

# Tools

name	description	location	comments
kinit	Receiving TGT ticket from the domain controller	JDK bin, also alternative implementations	a user can be set as {SERVER_USER} or {SERVER_USER}@{REALM}
klist	Received tickets look-up and option of deleting them from the local cash	JDK bin, also alternative implementations
setspn	Creates an SPN and assigns it to the user	included in Windows Server 2008+, formerly available in Windows Server support tools pack
ktpass	Changes username into an SPN or forms a keytab file	included in Windows Server 2008+, formerly available in Windows Server support tools pack
ktab	Forms a keytab file	JDK bin
ADSIEdit	User properties look-up in the domain controller	Windows Server
WireShark	Network traffic sniffer	https://www.wireshark.org/

# Description

You can find a more rigorous description in the internet, for instance: https://blogs.technet.microsoft.com/askds/2008/03/06/kerberos-for-the-busy-admin/.

stage	protocol	description	query data	response data	notes
0	KRB	user client authentication	username	TGT ticket	when entering the system
1	HTTP	sign-in	without Authorization HTTP title	HTTP 401	http://{SERVER_SPN}:8080/wfe/krblogin.do
2	KRB	receiving service ticket for the server	{SERVER_SPN}	service ticket	the step is executed if there is no ticket in the client's cash yet
3	HTTP	sign-in continuation	Authorization HTTP title = YIIV...	HTTP 200	http://{SERVER_SPN}:8080/wfe/krblogin.do
4	KRB	server user authentication	{SERVER_SPN}	TGT ticket	executed if TGT is lacking during the interaction with the client, happens before returning response 3 to client

# Encryption types

The selected encryption type depends on participants of interaction - domain software version (Windows Server), domain configurations, user configurations, client software configurations.

In early versions (Windows 2000, 2003) DES was configured, in later ones (Windows 2008, 2012) AES is recommended.

User configurations, working on Kerberos behaviour:

• This account supports Kerberos AES 128/256 bit encryption- permission for the user to use the corresponding encryption type (TODO - with checkboxes not turned on AES128 was still used)
• Use Kerberos DES encryption for this acount - turns DES encryption on for the user, after checkbox installation change of password is required

# krb5.ini

The file is not mandatory, but may have effect on authentication process behaviour.

Detailed description of Kerberos configuration file

On Windows server and client machines it may be located in ${windir}/krb5.ini.

krb5.ini file example:

[domain_realm]
 .test.com = TEST.COM
 test.com = TEST.COM
[libdefaults]
 default_realm = TEST.COM
 kdc_timesync = 1
 ccache_type = 4
 ticket_lifetime = 600
 default_tkt_enctypes = des-cbc-md5 des-cbc-crc des3-cbc-sha1
 default_tgs_enctypes = des-cbc-md5 des-cbc-crc des3-cbc-sha1
 permitted_enctypes = des-cbc-md5 des-cbc-crc des3-cbc-sha1
[logging]
 kdc = CONSOLE
[realms]
 TEST.COM = {
  kdc = 192.168.0.1
  kdc = 192.168.1.1
  default_domain = test.com
 }
[appdefaults]
 autologin = true
 forward = true
 forwardable = true
 encrypt = true

# Server configuration

This instruction was executed in Windows Server2008R2 environment (domain controller), Windows Server2012R2 (RunaWFE Server), Windows7 (RunaWFE client).

In this section case may be of importance, but experience has shown that username, server computer name and SPN are not case sensitive..

# Creation of server user

On domain controller you should create a user {SERVER_USER} with default configurations.

Check: kinit {SERVER_USER} should successfully receive a ticket.

# Creation of SPN

On domain controller you should run the following commands:

setspn -A {SERVER_SPN} {SERVER_USER}

Check: by means of ADSIEdit you can see that user property servicePrincipalName is enabled or look up servicePrincipalName property by means of Get-ADUser {SERVER_USER} -Properties *.

If you plan to work with SPN using a NetBIOS name - you should also register it (https://msdn.microsoft.com/en-us/library/ms677949.aspx)

setspn -A HTTP/{SERVER_NAME} {SERVER_USER}

# Binding SPN to server user

On domain controller you should run the following command:

ktpass /princ {SERVER_SPN} /mapuser {SERVER_USER} +setupn /pass *

You may ignore the notice «WARNING: pType and account type do not match. This might cause problems».

To avoid the bug with password reset https://support.microsoft.com/en-us/kb/939980 recommend to enter password instead of a gear. And if you run this command without password - error 24 with incorrect salt occurs because of unknown reasons.

Check: in user properties User logon name became equal to SPN or look-up UserPrincipalName property by means of Get-ADUser {SERVER_USER} -Properties *.

Check: kinit {SERVER_SPN} should successfully receive a ticket.

# Creation keytab of SPN

Run command from {JAVA_HOME}/bin:

ktab -a {SERVER_SPN} -n 0 -k {KEYTAB_PATH}

Check: kinit -k -t {KEYTAB_PATH} {SERVER_SPN} should successfully receive a ticket without password request.

You can also obtain this file by calling ktpass command on domain controller.

# kerberos.properties configuration

Create a file kerberos.properties in {RUNAWFE_JBOSS}/standalone/wfe.custom directory. Change the names in the file into real ones.

# enable authentication using RunaWFE API
api.auth.enabled=true
appName=com.sun.security.jgss.krb5.accept
moduleClassName=com.sun.security.auth.module.Krb5LoginModule
principal={SERVER_SPN}
storeKey=true
useKeyTab=true
keyTab={KEYTAB_PATH}
doNotPrompt=true
# authentication debug mode
debug=true
# enable HTTP authentication (from web-interface)
http.auth.enabled=true
jcifs.http.enableNegotiate=true
# authentication debug mode
sun.security.krb5.debug=true
jcifs.spnego.servicePrincipal={SERVER_SPN}
http.auth.preference=Kerberos

# Commands for execution for the abovementioned steps

On the domain controller:

setspn -A HTTP/runaserver.test.com runauser

ktpass -princ HTTP/runaserver.test.com -pass * -mapuser runauser

On the server:

ktab -a HTTP/runaserver.test.com -n 0 -k C:/runawfe/krb5.keytab

# Browser configuration

For the browser to try using Kerberos for authentication:

• the option Enable Integrated Windows Authentication should be enabled (in some IE versions ther is no such option)
• safety zone configurations should allow using it, by default it is configured for LocalIntranet
• the {SERVER_SPN} configuration must be carried out correctly

During the request in the Request Authorization log:

• Negotiate YIIV... is formed - correct
• Negotiate TlRMT... - incorrect (attempt to use NTLM)

If by clicking Pass-through authentication (kerberos) link a window with login/password entry will be displayed - it means that the browser did not receive a service ticket or did not even try to do that. If such a situation occurs, the most efficient thing is to use WireShark for traffic interception on port 88 with domain controller.

# Task notifier configuration

Authentication must be configured correctly on the server.

# Configuration for receiving tasks

Configure kerberos.properties if authentication.type is installed in kerberos (it is not required for sspiKerberos):

appName=com.sun.security.jgss.initiate
moduleClassName=com.sun.security.auth.module.Krb5LoginModule
useTicketCache=true
doNotPrompt=true
debug=true
serverPrincipal=HTTP/runaserver.test.com

# Configuration for browser

Install login.relative.url configuration into /krblogin.do.

# Troubleshooting

https://technet.microsoft.com/en-us/library/bb463167.aspx

Legacy Kerberos authentication configuration guide is more suitable for Windows2003

error	description	what to do
Client not found in Kerberos database (6)	SPN is not registered as a user (UserPrincipalName) or duplicated (setspn -x)	Register the SPN or delete the double
Pre-authentication information was invalid (24)	Wrong password or login information mismatching (UserPrincipalName changed?). Pay attention to the salt attribute in KRB Error pack: KRB5KDC_ERR_PREAUTH_FAILED, it should match principal, for which you are receiving the ticket; if it does not - something is wrong in kerberos DB, try to use ktpass command again	Change password (of the user and when keytab is formed)
Message stream modified (41)	The name is set incorrectly	Set the name correctly - as it is set on domain controller, match case
Clients credentials have been revoked (18)	The user is blocked	In the user configurations uncheck Account is disabled
HTTP 400 when trying to process YIIV... ticket	The title overdraws Jboss's maximum allowed, by default = 8Кб (https://access.redhat.com/solutions/1173073, http://www.novell.com/support/kb/doc.php?id=7005181)	Increase Jboss's maximum allowed by means of org.apache.coyote.http11.Http11Protocol.MAX_HEADER_SIZE configuration in standalone.xml
No valid credentials provided (Mechanism level: Attempt to obtain new ACCEPT credentials failed!)	The configuration appName=com.sun.security.jgss.accept is out-of-date - for old JDK versions	Change it into com.sun.security.jgss.krb5.accept in kerberos.properties
Encryption type AES256 CTS mode with HMAC SHA1-96 is not supported/enabled	AES-256 encryption type is not supported in JDK	Change encryption type (https://blogs.msdn.microsoft.com/openspecification/2011/05/30/windows-configurations-for-kerberos-supported-encryption-type/) or install "Unlimited Strength Java(TM) Cryptography Extension Policy Files".

Turning on audit on domain controller sometimes helps to understand the problem (it is logged in event logs, Security category.