Kerberos

Profile: spnegosecurity

SPNEGO/Negotiate with Login Form Fallback

The SPNEGO/Negotiate setup allows single sign-on from Windows computers using the web as well as the iGrafx client. If SSO fails, the user will be redirected to a login form and can still log in using their credentials. There is configuration required on the server side as well as the client side. Once both sides are correctly configured, you will be automatically authenticated as your current Windows user when opening the browser and browsing to your iGrafx platform instance. If the authentication fails, you will be forwarded to the form-based login. When SPNEGO is enabled on the server side, you can also use the iGrafx client to connect to your iGrafx platform instance by choosing "Use Single Sign-On" in the Open Repository dialog box.

Due to the SPNEGO/Negotiate protocol, you cannot log in using a browser or iGrafx client on the same machine where your iGrafx platform instance is running. You must use a second machine in the domain to test SSO.

Domain Controller Setup

In order for SPNEGO to work, an authorized application Service Principal must be created on the domain controller or Kerberos server. 

Create User

If you don't already have one, the first step is to create a user on the domain controller or Kerberos server, and give it an appropriate name such as webapp.  Make sure a policy accepted password is used.  For this example, and those that follow, let's say it's w3b@pp550().  Also make sure that the password doesn't expire, or need changing on next logon.

Create Service Principal and map to user, create keytab file

The next step is to create a service principal and map it to the user you just created. You will also need your domain controllers keytab file.  Both of these can be done with one call of the ktpass command. You will need the following parameters:

Parameter	Value
-out	ssowebapp.keytab or another appropriate file name to contain the keytab data
-princ	The principal name. In our case, we're hosting the iGrafx platform instance at http://platform.igrafxintra.net The Principal has to take the format HTTP/domain.com@KERBEROSREALM.COM, where the HTTP prefix and the Kerberos realm are all caps. The domain part needs to match the URL of your platform instance. If any of these requirements are not fulfilled SPNEGO SSO will not work.
-mapuser	The username (possibly with domain-prefix) that we created in the previous step
-crypto	ALL
-ptype	KRB_NT_PRINCIPAL
-pass	The password for the user we created in the previous step

An example call would look like this

C:\> ktpass -out ssowebapp.keytab -princ HTTP/platform.igrafxintra.net@DEV-IGRAFX.LOCAL -mapuser dev-igrafx\webapp -crypto ALL -ptype KRB5_NT_PRINCIPAL -pass w3b@pp550()

You can verify if the principal was correctly mapped by calling setspn -L webapp (substitute "webapp" with the proper user logon name, as created above in section Create User)

After mapping the Service Principal to the user, one can also see that the Kerberos username field in the Account Settings for that user change, as shown in the following screenshot:

KRB5 File

You will also need your Kerberos authentication and configuration file (KRB5.ini or KRB5.conf depending on the host operating system).

An example of one is shown below with the following example parameters based on the platform.igrafxintra.net example domain

[libdefaults]
  default_realm = DEV-IGRAFX.LOCAL
  default_tgs_enctypes = rc4-hmac des-cbc-md5 des-cbc-crc aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha1-96
  Default_tkt_enctypes = rc4-hmac des-cbc-md5 des-cbc-crc aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha1-96
[realms]
  IGRAFX.COM = {
    kdc = dc1.dev-igrafx.local
    admin_server = dc1.dev-igrafx.local
    default_domain = IGRAFX.COM
  }

Server-side Setup

After installing the iGrafx platform, edit the file ICE_BASEDIRECTORY/igrafx.properties. If it doesn't exist, create it in a simple text editor. Add the following three lines and update them with your deployments applicable information. Specifically, you need to update the Principal, the location and name of the keytab file, and the location and name of the krb5 configuration file. 

igrafx.usercentral.negotiate.principal=HTTP/platform.igrafxintra.net@DEV-IGRAFX.LOCAL
igrafx.usercentral.negotiate.keytab=file:c:/ssowebapp.keytab
igrafx.usercentral.negotiate.krb5conf=c:/krb5.ini

As stated in the parent article, to allow authentication using Kerberos/Negotiate, use the profile name spnegosecurity.

After making these changes, restart your application server.

The iGrafx platform currently ships with a JRE version that is tested with Kerberos. Not all JRE versions are guaranteed to support Kerberos authentication.

Server-side Logging

If there is any need to enable debugging, two things can be set to show more debug output.

1. In the igrafx.properties file, add the following line: 

   CODE

   igrafx.usercentral.negotiate.debug=true

   You will have to restart the server after making this change

2. Add the following class to your logging settings in Administration -> Support -> Logging Settings under Custom Classes and make sure the log level is DEBUG

   CODE

   org.springframework.security.kerberos

Client-side Setup

Failure to configure the system hosting the iGrafx Desktop Client correct may result in a 'Server Busy' message appearing over the Single Sign-On login dialog if the user tries to open or connect to a repository with the 'Use Single Sign-on' option - stating that 'This action cannot be completed because the other program is busy.'

Internet Explorer

Go to Tools > Internet Options > Security > Local Intranet > Sites > Advanced and add the host address where your iGrafx platform instance is located to the list of trusted intranet sites. If the iGrafx Platform can be reached reached at http://igrafx.yourcompany.com, specify igrafx.yourcompany.com and click Add. Followed by Close, OK, OK.  Depending on your computer settings, you may need to additionally add the host address to the Trusted sites list as well.

If SSO usage is common in your company, it is most likely already configured in your network zone.

Edge

If you use the Edge browser, you may still need to configure the trusted intranet site by way of Internet Explorer.

Firefox

Open Firefox and type _about:config_ into the address bar. If there is a warning about potentially voiding your warranty, click I'll be careful. Type negotiate-auth.trusted into the search field. Only one entry should remain, network.negotiate-auth.trusted-uris. Double-click it and type in the host name of the server where your iGrafx platform instance will be located. If the iGrafx platform can be reached at http://igrafx.yourcompany.com, specify igrafx.yourcompany.com. If you need to enter multiple URIs, separate them using commas.

If Firefox is not configured for SSO, it will not fall back to basic authentication, but will display a blank page instead.

Chrome on Windows

Chrome uses the same configuration information as Internet Explorer, so following the steps for Internet Explorer will allow this type of authentication for Chrome.

Chrome on Mac

Execute the following command(s) on your command line to allow Chrome to use SPNEGO/Kerberos on a MacOSX operating system.

1. First, check if any other servers are already whitelisted:

   CODE

   defaults read com.google.Chrome AuthServerWhitelist

   This might either list domains or return that this setting does not exist

2. If the default was empty before, simply set your server as the new value for this property. Otherwise, add your server as a comma-separated entry to the list of already existing servers that are allowed to use SPNEGO. To do that, issue the following command:

   CODE

   defaults write com.google.Chrome AuthServerWhitelist "yourserver.yourdomain.com"

   Make sure to quit and restart Chrome after making this change.

If Chrome on Mac is not configured for SSO, it will not fall back to basic authentication, but will display a blank page instead.

iGrafx Client

There is no special configuration required within the iGrafx client to allow "Negotiate." When connecting to a repository, choose "Use Single Sign-On."

Troubleshooting

Please check Encryption type not supported when using SSO for a common problem with regards to the locally available encryption algorithms.

If you have a specific error message in your log files search for its keywords on the home page of this documentation. If you don't find it there please search also the internet, most Kerberos configuration issues resolve about not using the right principal name.