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.
