Kerberos

Introduction

Using the Relution Enterprise Server in a Kerberos single sign-on environment has two sides. The middleware can participate as a client and/or server in this environment. As a server, Relution can use limited functions of the existing infrastructure with the help of LDAP connectivity. As a client, Relution connects to other backend server. The following describes the configuration that is required to act as a client to other backends using the Relution Enterprise Connectors. For the LDAP setup please refer to LDAP login integration →.

Note that in Windows environments Kerberos is normally used as part of the of Windows Integrated Authentication is used. LDAP is the technology behind an Active Directory. Here an Active Directory domain is mapped to a Kerberos realm. The configuration described here applies just as well to Unix-based SSO setups, where a realm is just a realm, or even for heterogeneous heterogeneous environments.

Rules for the configuration

The name of the Relution user and the Kerberos user must be identical. The Kerberos user m.meyer on the realm (domain) can be written for example as MYORG\m.meyer or as m.meyer@MYORG.

  • realm/domain: In Relution, a realm, or domain, is bound to an organization. For correct setup, the unique name of the organization and must match the realm name exactly. It is also recommended to set up a default user group for this organization.
  • User names: The names of users in Kerberos must match the names used in Relution.
  • For the realm, the Key Distribution Center must be discoverable:
    • Configured KDC: The KDC must be explicitly specified in the configuration file.
    • Discovered KDC: The KDC can alternatively be found via a DNS lookup.

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

  • Service: The Relution Server acts as a web server. The service name is therefore HTTP.
  • Principal: Relution uses the name of the user under which the software is run as principal. If this name is not applicable, the host name resulting from the reverse DNS search is used instead. The latter is the case if Relution is running as a Windows service for which no explicit user account is configured.
  • SPN: This will for example result in a final service provider name such as HTTP/relution when running as a user named Relution, or HTTP/myorg if running as a system service, which is hosted on the machine named myorg.

When specifying a user, the use of this information is necessary:

  • Access data: Relution needs the access data of the Service provider in the form of a keytab file.
  • Relution: A service ticket is required for the SPN via the Ticket-to-Self (S4U2self) Kerberos protocol extension is acquired. The acquired ticket must be forwardable.
  • Delegation: The forwardable ticket must support delegation via the protocol transition (S4U2proxy) Kerberos protocol extension.

Kerberos 5

Relution uses the Java runtime infrastructure to implement Kerberos low level communication. Due to the many alternative setups and the extensive possibility of Kerberos configuration, Relution does not attempt to provide an installation interface for Kerberos, but instead relies on the Java VM default configuration.

Configuration file (krb5.conf/krb5.ini)

Depending on the operating system and user account used to run Relution, the location of the Kerberos configuration file differs. The exact location is displayed as “kbr5.conf” on the the system information page. Normally, the machine running Relution is part of the Kerberos environment (also known as the Windows domain) and the “Forwardable” setting must at least be present:

[libdefaults]
    forwardable = true

Otherwise, a default domain can be specified. Also the following example explicitly specifies a KDC:

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

Note that if you omit the [Realms] section, the KDC will perform a DNS lookup.

Once the configuration file is available, restart the Relution server and verify the information provided by carefully reading the settings that are displayed as part of the System Information screen.

Restricted Delegation (krb5.keytab)

For impersonations, the credentials of the service must be exported as a keytab file. By default the file must be named krb5.keytab and be located in the user’s home folder. To the home directory, the system information page can be used. In some cases, the user may not have assigned a home folder. In this case, the keytab file must be placed next to the previously created krb5.conf/krb5.ini file.

The easiest way to create such a keytab file is to use the ktpass tool. It not only creates the required file, but also configures the SPN to principal mapping. First take a look at the system information to find out if the SPN name is either HTTP/username or HTTP/Hostname (the latter is possible if it runs as a service under the System or Network account). On the domain controller you must then execute the following command. Adjust the parameters to your environment, case sensitive:

    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, run the following command:

    prompt> setspn -l username_or_hostname

The resulting krb5.keytab file must be kept securely and stored in the home folder of the user running Relution Server.

Troubleshooting

Here are some points to approach in case of error:

  1. check the system information output. If the displayed data is wrong, it is not possible to function.
  2. look for errors in the log files of the Relution Server.
  3. add a debug=true in the libdefaults section of the file krb5.conf/krb5.ini file. Make sure you remove this for systems used in production!
  4. add the following Java VM properties to the configuration file for the server startup file
    -Dsun.security.krb5.debug=true
    -Dsun.security.spnego.debug=true
  5. check the log files of the Key Distribution Center or the event viewer of the domain controller, see below.
  6. if it fails, please contact Relution Helpdesk→.

To enable logging in a Windows domain controller, add the following registry key or update the following registry key. (the parameter is not present by default):

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