Kerberos Impersonation

Using the BlueRange Enterprise Server in a Kerberos single-sign-on environment has two sides. The middleware may participate as client and/or server of that enviroment. As a server, BlueRange can make limited use of existing infrastructure using the LDAP connectivity. As a client, BlueRange connects to other backend servers. In the following, the configuration necessary to act as a client to other backends using BlueRange enterprise connectors is described only. For LDAP setup please refer to LDAP Login Integration.

Notice, usually in Windows environments Kerberos is used as part of Windows Integrated Authentication, LDAP is the technology behind Active Directory. Here, an Active Directory Domain is mapped synonymously to a Kerberos Realm. However, the configuration described here applies equally well for Unix-based SSO setups, where a Realm is just a Realm, or even heterogenous environments.

Rules of Configuration

The notation of BlueRange users and Kerberos users must be identical. For example, the Kerberos user `m.meyer' of realm (domain) `MYORG' can be written as MYORG\m.meyer or m.meyer@MYORG:

Realm/Domain: In BlueRange, a realm/domain is tied to an organization. For a proper setup the Organization unique name must match the Realm name exactly. Also, it is recommended to set up a default user group for that Organization, ideally using the Organization wizard.
User names: The names of users in Kerberos must match the names used in BlueRange.

For a realm, the key distribution center needs to be detectable:

Configured KDC: The KDC may be given explicitly as part of the Kerberos configuration file.
Discovered KDC: The KDC can alternatively be located using a DNS lookup.

The service provider name follows the conventions of Microsoft’s Internet Information Services (IIS):

Service: The BlueRange server acts as a web server. The service name therefore is HTTP.
Principal: BlueRange uses the name of the user account the software is running under as principal. In case this name is not applicable, the host name resulting from reverse DNS lookup is used instead. The latter is the case when BlueRange is running as a Windows service with no explicit user account configured.
SPN: For example, this results in a final service provider name like HTTP/relution when running as a user called `BlueRange', or HTTP/myorg when running as a system service hosted on the `myorg' machine.

For impersonation constrained delegation is required to be used:

Credentials: BlueRange needs the credentials of the service provider in the form of a keytab file.
Forwardable: For the SPN a service ticket is acquired via the ticket-to-self (S4U2self) Kerberos protocol extension. The ticket obtained must be forwardable.
Delegation: The forwardable ticket must allow delegation via the protocol-transition (S4U2proxy) Kerberos protocol extension.

Kerberos 5

BlueRange uses Java Runtime infrastructure to implement Kerberos low-level communication. Due to the many alternative setups possible and the distributed nature of Kerberos configuration, BlueRange does not attempt to provide an installation interface for Kerberos, but relies on Java VM standard configuration.

Configuration File (krb5.conf/krb5.ini)

Depending on the operating system and user account used to run BlueRange the location of the Kerberos configuration file differs. The exact location is displayed as `kbr5.conf' on the system information page. Usually the machine running BlueRange is part of the Kerberos environment (aka. Windows Domain) the forwardable setting must be provided, at least:

[libdefaults]
    forwardable = true

Otherwise, a default realm may be specified. The following example also gives a KDC explicitly:

[realms]
    MYORG = {
        kdc = kdc.myorg.local
    }
[libdefaults]
    forwardable = true
    default_realm = MYORG

Notice, when the [realms] section would be omitted, the KDC is looked up using DNS.

Once the configuration file is in place, restart the BlueRange Server and verify the information provided by carefully reading the settings displayed as part of system information.

Constrained Delegation (krb5.keytab)

For impersonations the credentials of the service principal need to be exported as a keytab file. By default, the file must be named krb5.keytab and be located in the user home folder. To determine the home location the system information page can be used. In rare cases the user may not have a home folder assigned, in which case the keytab file must be located next to the krb5.conf/krb5.ini file created previously.

The easiest way of creating such a keytab file is using the ktpass tool. Besides creating the file necessary, it also configures the SPN to principal mapping. Firstly, have a look at system information to find out the SPN name being either HTTP/username or HTTP/hostname (the latter when running as a service under system or network account). Then, on the domain controller machine, run the following command adjusting the parameters to your environment, case matters:

prompt> ktpass -out krb5.keytab \
    -princ HTTP/username_or_hostname@FULLY.QUALIFIED.REALM.OR.DOMAIN.NAME \
    -crypto All \
    -mapuser SIMPLE_REALM_OR_DOMAIN_NAME\username_or_hostname \
    -pass SOME_PASSWORD_AT_YOUR_DISCRETION \
    -ptype KRB5_NT_PRINCIPAL

To verify the SPN mapping, try running the following command:

prompt> setspn -l username_or_hostname

The resulting krb5.keytab file must be kept secure and copied to the machine running BlueRange Server to the home folder of the user running the software.

Troubleshooting

Here are the options for analyzing problems:

Check the output of system information. When the data displayed is incorrect it can not possibly work.
Watch out for any errors displayed in the log files of the BlueRange server.
Add a debug=true to the libdefaults section of krb5.conf/krb5.ini. Make sure to remove this for production systems!
Add the Java VM properties -Dsun.security.krb5.debug=true -Dsun.security.spnego.debug=true to the server launch configuration file.
Review the log files of the key distribution center or event viewer of the domain controller, see below.
When everything else fails please contact MWAY DIGITAL for providing technical assistence.

To activate logging in an Windows domain controller add or update the following registry value (the parameter doesn’t exist by default):

Registry path
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters
value name: LogLevel
value type: REG_DWORD
value data: 0x1