Set SPN to use Kerberos authentication

Last update: 11 January 2021 (cf)

Summary

If you connect to the URL of your Fabasoft Folio webserver from a remote client, you might get login prompts and "401.2 Access denied" messages. This is usually caused by a missing SPN for the webservice user.

This article describes how to set a SPN for your webservice user.

Signs that indicate a possible Kerberos problem

• Local call of http://localhost/fsc works
• Access from another client shows an authentication dialog for 3 times, but denies access with http 401.2 Access denied
• Accessing from another client works, if the IP of the server is used instead of the hostname ( http://192.168.0.10/fsc)

Solution

To fix this behaviour, you have to set SPNs for your webservice user.

Creating Service Principal Names (SPN) under Windows

Prerequiries:

• You need to have Domain Administrative permissions to set SPNs.
• You need the Windows tool setspn.exe. This is usually installed on Windows domain controllers and newer versions of Windows. For Windows Server 2003 the "Microsoft Support Tools" can be installed to get setspn.exe. It's not necessary to have the tool installed on the Fabasoft servers, but on any desired server or workstation.

Syntax

List current SPNs for a given user:

       setspn.exe -l domain\user

This will display all SPN for the given user. In a Fabasoft Folio environment the user is that user that runs the Fabasoft Folio webservice. A user can have multiple SPNs set to host multiple webservers or hostnames.

Add a new SPN for a webserver:

       setspn.exe -a http/hostname.domain.com domain\user

setspn.exe -a http/hostname domain\user

and are the hostname and the full qualified hostname of the server. is the user that runs your Fabasoft Folio webservice.

We recommend to always set the SPN for the (short) hostname and the (long) full qualified domain name. To access the web interface of the conversion servers, SPNs need to be set too.

Note: If you use a load balancer in your environment, it is nesessary to also set a SPN for the URL of your load balancer.

Workaround

If you are not able/allowed to set the SPNs in Active Directory, there are two workarounds:

• Use the IP address to access the server instead of the hostname. Kerberos is only used with hostnames, not with IP addresses.
• Disable Kerberos authentication at your webserver(s). A detailed description can be found in Microsoft's Knowledge Base http://support.microsoft.com/kb/215383/en-us .

Note: Fabasoft recommends not to use these workarounds, if the SPNs can be set. Use these workarounds only temporarily.

Information

In a Microsoft Windows environment, the Fabasoft Folio Web services run with a specified domain user (webservice user). In Active Directory, the web service user needs to have permissions to run a service (in this case http) in the domain. This permission is set by the SPN. Also, other applications need to have set SPN, for example Microsoft SQL Server.

If the SPN is not set and the webserver requests the clearence of the user login at the AD controller, the AD controller deny the clearence request because the webservice user is not allowed to run a webservice (SPN missing). Hence the failed clearence, the user gets an access denied error message.

A very detailed article about SPN's can be found in the Microsoft Knowledge Base http://support.microsoft.com/kb/929650/en-us .

Applies to

• Microsoft IIS
• Fabasoft Folio (all versions)
• Fabasoft eGov-Suite (all versions)
• Fabasoft eCRM-Suite (all versions)