Kerberos Authentication

Information

• Kerberos is a standardized authentication mechanism that must be configured both on the server and on the client.

Notes

• The following requirements must be fulfilled for the Kerberos authentication:

  • Keytab file available

  • Hostname of the Key Distribution Center (KDC) known

  • ServicePrincipalName (SPN) of the service known

    • Information on the structure of the SPN: https://msdn.microsoft.com/en-us/library/ms677601.aspx

Caution

• To carry out the administration tasks described below, profound IT knowledge is required.

Server Configuration

For information

• You have to set the auth.methods configuration variable in the Server Configuration accordingly, i.e. in this case to the kerberos option.

Details

• The config__kerberos and config__auth environment variables each define a path to specific configuration files.

  • config__kerberos is a Kerberos configuration, determining realms, domains, KDCs as well as encrypting algorithms.

  • If a system-wide JAAS compatible configuration file already exists, it can be used as well. Otherwise, the template can also be adjusted to the customer installation.

  • config__auth determines how the PLANTA Server logs on using its own service account. An area named PLANTAServer is required in order for the code to be able to find the settings. Here, the principal path as well as the keyTab / ticketCache path can be adjusted according to your needs. All further settings, especially doNotPrompt, should remain unchanged.

• Keytab files are usually created by the system administrator in order to adjust the corresponding principals and service accounts. The system administrator should know best how to create them correctly and how the corresponding principals in config/auth.conf are to be specified.

• The dissolution of Kerberos Principal based on the PLANTA user name/code is solved in Python in order for the customer to be able to map any user@REALM combination to a random PLANTA user.

• In the ppms.krb5_login Python module, a krb5_login_resolve_username(Principal) method is defined, providing a customer specific option to map a Kerberos Principal to its corresponding PLANTA user name. This Python method is documented with respect to the parameters and the expected return value. The actual implementation has to be defined separately for each installation.

• To get debug information for kerberos, you can make the following settings for JVM: -Djava.security.debug=all. YOu can do this in the .\PlantaServer\yajsw\conf\common.conf file in one of the wrapper.java.additional.x parameters. After restart, you will find the output in the wrapper.log file.

Client Configuration

Information

• The client configuration parameters can be specified in the command line or the ini file.

  • authentication=kerberos

    • Activates Kerberos ticket editing (required)

  • spn=<service>/<service_account>@<REALM>

    • Here, the canonic SPN must be entered, e.g. PLANTA/planta_server@EXAMPLE.COM (required).

  • mutual=on

    • Activates the mutual authentication (optional)

Note

• When a configuration parameter is specified in the ini file, no additional quotation marks (e.g. in the SPN) or additional blank spaces (e.g. at the end of a line) must be used.

Configure the Encryption Settings for User Accounts in Active Directory

• To configure strong encryption, the user settings must be adjusted as described in the Network Security: Configure Encryption Type Admissible for Kerberos article.

• Notes on problem solution can be found under Kerberos and LDAP Troubleshooting Tips.

Exemplary Set-Up of a Service Account for Kerberos Authentication in the Active Directory

1) Creation of a user in the AD tree

• Open Active Directory Users and Computers on the domain controller

• Create a new user with the required name (e.g. service name) via Create a new user in the current container

  • Example: planta_service

2) Setting of a service principal name (SPN) via the setspn command

• Execute setspn -A <SPN> <account>

• Name schema: <service name>/<identificator, e.g. host name>

  • Example: setspn -A PLANTA/srv_planta.mydomain.com planta_service

• An SPN may only be allocated once.

  • Otherwise the client aborts the ticket request with the SEC_E_TARGET_UNKNOWN error message.

  • The check can be carried out via setspn -Q <SPN>: Here, only an account must be returned.

3) Creation of a keytab file via ktpass

• Syntax: ktpass /princ <SPN> /mapuser <Domain\User@DOMAIN> /pass <password> /out <keytab filename>

  • Example with the previous values: ktpass /princ PLANTA/srv_planta@MYDOMAIN.COM -setupn /mapuser XYZ\planta_service /pass gehe1m /out planta_service.keytab

• Note

  • The domain must necessarily be specified in capital letters.

  • The -setupn parameter used here prevents the user account from being overwritten.

    • This may be required for SPNs which cannot be used as user names.

  • Copy the keytab file to the configuration directory of the server

  • Protect the file against unauthorized reading

See also: Server Parameters, Client Parameters