KerberosAuthentication

From RunaWFE
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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/.

KerberosAuthentication en1.png

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 *.

KerberosAuthentication en2.png

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.

KerberosAuthentication en3.png