Kerberos SSO to PortalGuard

This section describes how users that log into their organization-supplied workstation can receive SSO directly to the PortalGuard server which in turn can provide SSO to other web applications with which it is federated. This model is nearly identical to how most organizations deploy Microsoft ADFS for internal SSO. The users’ login to their workstation is leveraged to provide automatic SSO to PortalGuard without it prompting them for credentials a second time. This scenario only works for an organization’s users where Active Directory is fully deployed – it does not work for external end-users.


  • PG.dll version and PG.NET.dll version or later are required.
  • The server on which PortalGuard is installed is joined to your Active Directory (AD) domain.
  • Users’ workstations must be joined to your AD domain.
  • Users must login to workstations using an AD domain account.
  • Users must have network access to an AD Domain Controller in their domain for Kerberos SSO to work.
  • The server name used to access PortalGuard must be listed as a valid servicePrincipalName (SPN) in Active Directory.
  • The web browser must support SPNEGO or Integrated Windows Authentication and have this feature enabled. Microsoft Internet Explorer, Google Chrome and Mozilla Firefox all have built-in support for SPNEGO. However, only IE and Chrome have it enabled by default.
  • In Microsoft Internet Explorer, the server name (or wild-card DNS domain) used to access PortalGuard must be in the Local Intranet zone in the Internet Options -& Security tab.
  • If users are in a different AD forest from the PortalGuard server, a forest-level trust must be established between the two for Kerberos SSO to work. Please see MSDN: How Domain and Forest Trusts Work.


  • The NTLM protocol is not supported.
  • IPv6 client IP address filtering is not supported.
  • If Kerberos is attempted with an end-user browser that is not properly configured, they will see a pop-up dialog to login. Credentials entered at this prompt will typically result in NTLM authentication to the PortalGuard server which is not supported. Users must click the dialog’s ‘Cancel’ button to login.

How It Works

Kerberos is an authentication protocol originally developed at MIT before reaching the masses when Microsoft implemented it as the default authentication mechanism in Windows 2000. Since then it has solidified itself as the foundation for authentication in all Windows operating systems as well as being freely distributed by MIT for use in Windows and Unix-based operating systems.

Kerberos requires connectivity to a central Key Distribution Center (KDC). In Windows, each Active Directory Domain Controller (DC) acts as a KDC; “DC” will be used to refer to this role for the remainder of this chapter. Users authenticate themselves to services (e.g. web servers) by first authenticating to the DC, then requesting encrypted service tickets from the DC for the specific service they wish to use. Only the service (and the DC) can decrypt the service ticket to get the user’s information. Because only the DC could have created the service ticket, the service knows that the user must have also authenticated to the DC so it can trust the user credentials in that ticket. More in-depth discussions of the Kerberos protocol are beyond the scope of this guide and can easily be found online.

The diagram below shows the steps that occur for a user to get SSO to a website via Kerberos:

Simplified Kerberos

The numbered steps are as follows:

  1. The user opens a browser and requests a resource from the web server named
  2. The web server sees the user has not been authenticated yet. It inspects the browser request and makes a determination about whether to initiate Kerberos or not. Very little information about the end user is known at this point, so only things like client IP address, requested URL and browser type (the “User-Agent”) can be used to make this decision. If the web server believes the client browser can support Kerberos, then it sends a 401 HTTP response telling the browser to authenticate using the “Negotiate” protocol.
  3. The browser interfaces with the security subsystem on the workstation to request a Kerberos service ticket for from the Active Directory Domain Controller (DC).
  4. The DC validates the user’s credentials which are provided automatically as a Ticket Granting Ticket (TGT), looks up the service/computer account associated with the requested name and creates and encrypts a new service ticket using the service account’s credentials. This Kerberos service ticket is then returned to the client machine. The service ticket is specific to both the end-user -AND- the target server and it is protected cryptographically so only the target service can decrypt it to get the user information (typically just the fully qualified username).
  5. The browser requests the web resource again with an encoded copy of the service ticket as a new request header. The web server parses out the service ticket and attempts to validate it. If successful, the user’s Active Directory domain and username are extracted from the ticket (e.g. ACME\testuser).
  6. The web server validates the user’s access to the requested resource and if authorized, returns the resource.

The benefits of Kerberos authentication with PortalGuard are:

  • True Single Sign-On – Users only need to login to their workstation and can receive SSO to any website already federated with PortalGuard. PortalGuard will not prompt the user to login again for users on the LAN.
  • No additional client-side software required – Modern browsers have built-in support for Kerberos authentication. Please note that some browser configuration may be required.
  • Mutual authentication – As part of the Kerberos exchange, the end-user proves his identity to the server, but the server also proves its identity to the end-user. This ability prevents man-in-the-middle attacks where a malicious program tries to impersonate the server and get private information from the user.
  • No passwords are sent over the network – The exchanges in Kerberos never send the user’s password over the network (neither encrypted nor in clear-text). Because the password is not used to authenticate the user on the server, there is no chance that it could be sniffed on the network or that the server could be attacked/compromised in order to obtain the user’s password.

The drawbacks to using Kerberos in PortalGuard are:

  • Both the user and the server must be authenticated to the AD domain. Kerberos authentication cannot be used for “local” user accounts defined only on the workstation.
  • An AD domain controller must be accessible on the network when the user’s browser requests the service ticket. This requires redundant DCs be available to prevent SSO failure.
  • Client and server clocks must be synchronized – Because Kerberos relies heavily on timestamps to authenticate users/servers and thwart replay attacks, the clocks on the client and server machines cannot have a skew greater than 5 minutes.The Windows Time Service utilizes the Network Time Protocol (NTP) which can be easily used to make sure all system clocks on your workstations and servers are synchronized.
  • DNS must be used – Kerberos leverages DNS to both find the DC and resolve the host names of client and server machines.
  • Browser Logout Not Possible – Since Kerberos provides SSO to PortalGuard and PortalGuard in turn provides SSO to sites federated with it, end users cannot truly logout of a browser session. If they access the website again, they will get Kerberos SSO to PortalGuard which will then automatically create a new session with the target site.Users must either lock their workstation or logout of the workstation completely to prevent SSO from recurring.


Please perform the following steps on the PortalGuard server to enable Kerberos SSO directly to the PortalGuard website:

  1. In a text editor launched as an administrator, open the PortalGuard server's root web.config file. The default folder location is C:\InetPub\PortalGuard.
  2. In the <system.webServer&, <modules& element, comment out the LeanHeadersModule module using HTML comments. Put “<!--" at the beginning of the line and “--&” at the end. The final result for these changes is shown in green highlight in the image below.
  3. In the same parent element, uncomment the MixedAuthentication module by removing the HTML comments at the beginning (“<!--") and end (“--&”) of the line. The end result is shown in yellow highlight in the image below.

Picture goes here

  1. In the <system.webServer& element, find and comment out the entire <httpErrors& element using HTML comments. The result is shown in green highlight in the image below.

  1. Find the <SSOConditions& element at the bottom of the web.config file. Change the Service Principal Name (SPN) values to match the server name(s) internal end-users will use in URLs to achieve Kerberos SSO to the PortalGuard server.

Valid SPNs are stored in computer or service accounts within Active Directory.When a server is joined to an Active Directory domain, the following default SPNs are created:



Any additional SPNs added for a machine or service account in Active Directory must also be added to this list in the PortalGuardweb.config.

If you need to add custom SPNs for the PortalGuard server, see the section below named SPN Management.

If you are load balancing multiple PortalGuard instances, use the load-balanced DNS alias here and also see the section below named Load Balanced PortalGuard Servers.

  1. Within the same element, change the <IPWhiteList& address range to match the IP address subnet(s) on your LAN. Additional network ranges can be added here as well.

  1. Save the changes to web.config.
  2. Open Global.asax in the PortalGuard server’s root folder in a text editor as an administrator.
  3. Uncomment the two lines referring to SSOConditions by removing the initial “//” characters. The image below shows the final result.

  1. Run iisreset from an administrative DOS prompt


The following options are available for controlling when Kerberos is initiated with client devices. All settings are found in the web.config file in the root of the PortalGuard server (e.g. C:\InetPub\PortalGuard).The XML element path is: <portalguard& <SSOConditions&.

Please note that all configuration elements must be present in the web.config. Whether the setting is listed as optional or required only refers to whether the respective element can be empty or not.

NOTE: Changes to all settings take effect immediately when the web.config is saved.


The following attributes are found in the top-level <SSOConditions& element itself:


  • debugging – Can be set to “true” or “false”. When “true”, details about the Kerberos runtime configuration and decisions made for each client request are written to the PortalGuard log in the Windows Event Viewer.This log can be found in the “Applications and Services Logs” grouping. This setting creates extensive logging so it should only be enabled when troubleshooting.
  • disabled – Can be set to “true” or “false”.When “true”, PortalGuard’s built-in Kerberos SSO functionality is disabled.This is a good way to temporarily disable Kerberos for the entire PortalGuard server without reversing all the steps in the Installation section above.The value must be “false” for normal Kerberos SSO functioning.
  • keepDomain – Can be set to “true” or “false”. When “true”, the user’s NetBIOS domain will be kept as part of the user’s final, authenticated name (e.g. DOMAIN\testuser).When set to “false”, the domain and backslash will be stripped off, resulting in a bare username (e.g. testuser).



A list of host/server names that clients must use for Kerberos SSO to be attempted.


<add value="host" /&

<add value="" /&

<add value="" /&


These values are not case-sensitive and they must NOT include a port designation (e.g. host:443) or service specifier (e.g. HTTP/host).

All SPNs must be present in both the appropriate machine/service account in Active Directory and DNS for Kerberos to succeed. They should be added to this list as a final step. See SPN Management section below on manipulating SPNs in AD.



A "white" list for using client IP address ranges as a check to determine whether Kerberos SSO should be attempted. On a server used by both internal and external users, if you only want to provide Kerberos SSO to internal workstations (a likely case), then simply add the LAN’s IP address range to the white list. For the example, Kerberos SSO should be attempted if the client IP address is:

  • 192.168.*.*
  • 10.*.*.*

Here is the corresponding web.config configuration:


<add value="192.168.*.*" /&

<add value="10.*.*.*" /&


Wildcards can be used to allow Kerberos for entire blocks of IPs. CIDR notation is not supported.

Additional ranges must be in their own <add /& element. Please see the Order of Evaluation section below about how black and white lists behave in conjunction.



A "black" list for using client IP address ranges as a check to determine whether Kerberos SSO should be attempted. If you want to prevent Kerberos SSO for a specific machine on your LAN, then simply add the specific IP address to the black list, e.g.:


<add value="" /&


As with the IPWhiteList element, wildcards can also be used to prevent Kerberos for entire blocks of IPs. CIDR notation is not supported.

Additional ranges must be in their own <add /& element. Please see the Order of Evaluation section below about how black and white lists behave in conjunction.



A “black” list of URLs on the PortalGuard server for which Kerberos should not be attempted.The use of wildcards is allowed through the ‘*’ character.


<add value="/_layouts/PG/*" /&




A “white” list of browsers for which Kerberos should be attempted. The values listed here are checked as a “contains”-type, case-insensitive match on the User-Agent browser header. If this list is empty, Kerberos SSO will never be initiated by PortalGuard.

Since Firefox does not support Negotiated authentication by default (it must be explicitly enabled in about:config) it is NOT in the default list when PortalGuard is installed. On the PortalGuard server, the following configuration can be used to request Kerberos from Firefox browsers (change to the default is in red):


<add value="MSIE" /&

<add value="Trident/" /&

<add value="Chrome/" /&

<add value="Firefox/" /&


Please see for a complete list of known web browsers and their User-Agent strings. Be careful what you choose as a “marker” since many browsers utilize common tags within the User-Agent header!

Order of Evaluation

With the numerous ways of preventing or ensuring Kerberos SSO is initiated by the PortalGuard server, it is helpful to understand how they are evaluated. This section describes the logic of how this determination is made. It is important to understand these steps since user experience is severely degraded when Kerberos is requested of a client device that cannot perform it.

NOTE: In this list, subsequent steps are only evaluated if the prior step has not prevented the use of Kerberos.

1) If the client browser sends a cookie named PstarNoKerberos with a value of “1” then Kerberos will NOT be attempted. This check is always performed first and no other checks are performed if this condition is satisfied.

2) Client IP address is the biggest factor when determining a client device’s ability to perform Kerberos. End-user devices must be able to reach an Active Directory domain controller on the network and DCs are almost exclusively available only on a LAN.

a. If neither a white nor a black list is specified, then the client IP does not help determine if Kerberos SSO should be attempted. In this case, Kerberos is implicitly ALLOWED.

b. If only a white list is specified, Kerberos SSO for all client IPs is implicitly DENIED and only those in the white list may receive it.

c. If only a black list is specified, Kerberos SSO for all client IPs is implicitly ALLOWED and only those in the black list are denied it.

d. If both a whitelist and blacklist are specified, the white list is always checked first. The blacklist is only checked if the white list was satisfied. This ordering is in place because Kerberos is implicitly DENIED when any IP list is defined.

NOTE: IPv6 address filtering is not currently supported. Since IPv6 addresses are typically only used within a LAN environment, IPv6 access is implicitly allowed when at least one IP white list is defined.

3) SPNs are evaluated next. The server name value is parsed directly from the request URL. This value must be listed as an SPN to satisfy this requirement and ALLOW Kerberos. The comparison is case-insensitive and substring checking is NOT performed. If no match is found, Kerberos is DENIED.

4) Any URL black list is checked next.

a. If no URL black list is present, Kerberos is implicitly ALLOWED.

b. If a URL black list is present, the path and query string from the requested URL is evaluated against each entry in this list as a regular expression. Below, the path is shown in bold red and the query string is shown in green highlight:

Since this is a blacklist, Kerberos is only DENIED if a match is found.

5) The final step is checking the user’s browser type. This is done by reading the User-Agent header directly from the request. If the header value contains any of the white list values (case-insensitive) then Kerberos is ALLOWED. Otherwise, Kerberos is DENIED.


The first step is determining if Kerberos SSO is being initiated by the PortalGuard web server. Set debugging="true" in the <SSOCondition& element of the web.config. This will log verbose information to the PortalGuard log in the Event Viewer on the PortalGuard server. It shows the request details and you should be able to use the logging to determine why Kerberos SSO is not being initiated by PortalGuard.

Use of a HTTP proxy like Fiddler on the client workstation is also very helpful for determining exactly what the browser is sending to the PortalGuard server and seeing what the PortalGuard server is returning. If the PG server is initiating Kerberos, you should see a 401 response from it back to the client’s initial request.

If Kerberos SSO is being initiated by the PortalGuard server, the next step is to determine if the client machine is at fault. Do the following on the client workstation:

1) Install Wireshark (link)

2) Download and extract Microsoft's "klist.exe" utility from it

3) Run the following DOS commands as an administrator:

ipconfig /FlushDNS

NBTStat -R

klist.exe purge

4) Run Wireshark and start a trace on the LAN adapter

5) Reproduce the problem

6) Stop the Wireshark trace and use the following filter to hide extraneous packets:

http || kerberos || dns

7) Look for any KRB5 protocol packets. Drilling down into them should show at the top level if there’s an error and what it may be. For example, the KDC_ERR_S_PRINCIPAL_UNKNOWN error occurs when a SPN is either not defined in AD or is defined in multiple accounts.

At this point, use Fiddler to determine if the workstation is actually sending a Kerberos service ticket to the PortalGuard server. Look for a request header named Authorization that is at least 1000 bytes. If this header is only a few hundred bytes or if the encoded value starts with TlRMTVNT, then it is an NTLM token and the problem is related to either AD or browser configuration.

When a valid Kerberos ticket is sent to PortalGuard, the decryption details appear in the PG_Log_{DATE}.txt file in the Program Files\PistolStar\PortalGuard\Logs folder. Be sure to enable “Trace” logging in the Bootstrap Configuration to see all the details.

A successful Kerberos initialization when the PG server first starts will look like this in the PG_Log:

InitSSPI(): HTTP process running under user: 'IIS APPPOOL\DefaultAppPool'

InitSSPI(): DNS name of this machine: ''

InitSSPI(): NETBIOS name of this machine: 'STBART'

GetCreds(): Successfully acquired Kerberos credentials handle for service

InitSSPI(): Successfully initialized Kerberos

A successful Kerberos service ticket decryption will look like this in the PG_Log:

doKerberosAuth(): Found 'Authorization' header, length: 4134

doKerberosAuth(): Base64 decoding successful, return length: 3092

ps_sspi::HandleSpnegoToken(): spnegoInitFromBinary() succeeded

ps_sspi::HandleSpnegoToken(): spnegoGetTokenType() succeeded, return type: SPNEGO_TOKEN_INIT

ps_sspi::HandleSpnegoToken(): Found mech type: spnego_mech_oid_Kerberos_V5_Legacy

ps_sspi::HandleSpnegoToken(): Attempting to parse out mech token

ps_sspi::HandleSpnegoToken(): Successfully extracted mech token

ps_sspi::HandleSpnegoToken(): Calling into security package with token...

ps_sspi::HandleSpnegoToken(): AcceptSecurityContext() returned status: 0x00000000

ps_sspi::HandleSpnegoToken(): AcceptSecurityContext() succeeded

ps_sspi::GetCtxtInfo(): Flags: 0x00020803

ps_sspi::GetCtxtInfo(): Package state: SECPKG_NEGOTIATION_COMPLETE

ps_sspi::GetCtxtInfo(): Package name: 'Kerberos'

ps_sspi::GetCtxtInfo(): Package comment: 'Microsoft Kerberos V1.0'

ps_sspi::GetCtxtInfo(): User: 'PGUS\ssouser1'

ps_sspi::GetCtxtInfo(): Key Info: Signature Alg:"HMAC-SHA1-96" (0x00000010)

ps_sspi::GetCtxtInfo(): Key Info: Encryption Alg: "Kerberos AES256-CTS-HMAC-SHA1-96" (0x00000012)

ps_sspi::GetCtxtInfo(): Key Info: Key size: 256

ps_sspi::GetCtxtInfo(): Lifespan, Start time: 03/19/2015 04:09:23 AM

ps_sspi::GetCtxtInfo(): Lifespan, Expire time: 03/19/2015 02:09:23 PM

ps_sspi::GetCtxtInfo(): Native client: 'ssouser1@PORTALGUARD.US'

ps_sspi::GetCtxtInfo(): Native server: 'HTTP/'

ps_sspi::GetCtxtInfo(): Session key length: 32

doKerberosAuth(): NetBIOSName: 'PGUS\ssouser1', UPN: 'ssouser1@PORTALGUARD.US'

doKerberosAuth(): Response Authhdr: 'oYG2MIGzoAMKAQGhCwYJKoZIg…

If you are still unable to determine the problem, zip and email the following files to

  • Wireshark trace
  • PG_Log_{DATE}.txt
  • Fiddler trace

SPN Management

Any aliases or servicePrincipalNames (SPNs) which the end-users use to refer to the PortalGuard server must be defined within Active Directory. Kerberos will only work if Active Directory is aware of all the different names through which the server is accessible. These names should already also be in DNS as HOST (A) records, not Alias (CNAME) records. Set any additional SPNs with the -A (add) parameter of setspn.exe, e.g.:

setspn -A HTTP/<spn&<ad_account&

Here are some example commands with output. They are assigning the “portal” and “” aliases to the AD account named “loadbalance”:

setspn -A HTTP/portal loadbalance

setspn -A HTTP/ loadbalance


NOTE: You can standardize on using either the HOST/ or the HTTP/ service specifiers. They both satisfy Kerberos SSO so you do not need to specify the same alias with both types - this would be redundant.

You can use Microsoft’s queryspn VBScript to list all accounts for a given SPN.Use this from a DOS prompt with the syntax:

cscript queryspn.vbs <SPN-to-Check&

The output for an example run is shown in the image below:

cscript queryspn.vbs HTTP/

You also can confirm the SPNs are in the target account using an LDAP browser.The values for the “servicePrincipalName” field are shown here in Microsoft’s free LDP.exe utility:


NOTE: You must ensure SPNs are only set within a single account in Active Directory. Kerberos SSO will fail both if an SPN does not exist -AND- if it exists in more than one Active Directory account.

Load Balanced PortalGuard Servers

PortalGuard supports Kerberos SSO functionality in a load-balanced environment. Because a request could be routed to any of the PortalGuard servers, they must all run with the same identity to ensure a Kerberos service ticket can be decrypted by any of them. This is accomplished using an Active Directory service account that will have all load-balanced SPNs listed under it. Since an IIS application pool can only run under a single identity, none of the machine names of the PortalGuard servers involved can be used to perform Kerberos.

NOTE: Moving the hostname SPN from a machine account (e.g. HOST/server1) to the load-balanced service account will prevent Remote Desktop and console access to the server using domain accounts.

The following additional steps must be completed in order to ensure correct Kerberos SSO functioning in a load-balanced configuration:

  1. Create a new user in Active Directory, e.g. This account can remain in the “Domain Users” group, but for ease of maintenance the password should never expire.
  1. Convert the new user account to a service account using the ktpass command.The command must be run on an AD domain controller after the user account above is created:

ktpass -princ HOST/<server_alias&@DOMAIN -mapuser <username&

For example, if users will access PortalGuard with the server name, the AD domain is PGUS and the user created in step 1 is PGUS\loadbalance, the command to execute would be:

ktpass -princ HOST/ -mapuser PGUS\loadbalance

  1. Using IIS Manager, expand the server in the left hand navigator and click the Application Pools entry. Identify the Application Pool associated with the PortalGuard website (typically DefaultAppPool), right click it and choose Advanced Settings…

  1. In the “Process Model” settings group, click the button at the right hand side of the Identity setting:

  1. Choose the “Custom account” radio button and click the “Set…” button

  1. Enter the service account username in the form DOMAIN\user (e.g. PGUS\loadbalance) and the correct password twice then click OK.
  1. The account should now show as below:

  1. OK your way out of the remaining dialogs and restart IIS for the changes to take effect.

Basic Authentication Pop-up Dialog

If Kerberos is initiated with a client device that cannot perform it, the user will see a dialog box that asks for their username and password:

Because PortalGuard does not support NTLM authentication, any credentials entered in this dialog will typically not work and the dialog will simply re-display.Users must click 'Cancel' on this dialog to continue and will be shown the following screen by default:

To show the PortalGuard login form instead when Cancel is clicked, perform the following steps:

NOTE: These steps will replace the standard 401 response HTML for all websites on the IIS server where PortalGuard is running.

  1. In Windows Explorer, open the C:\inetpub\custerr\en-US folder.
  2. Make a back-up copy of 401.htm and name it 401-default.htm.
  3. Edit 401.htm in a text editor launched as an Administrator.
  4. Delete the entire contents of the file and paste in the following:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" ""&

<html xmlns=""&


<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/&

<title& </title&


<body onload="setTimeout('doRedirect()', 200)"&

<script language="JavaScript"&


function doRedirect() {

//document.cookie = "PstarNoKerberos=1; path=/";

window.location = "/_layouts/PG/login.aspx?ReturnUrl=" + encodeURIComponent(location.pathname + + location.hash);






  1. Save and close the 401.htm file

The HTML above will now be sent with 401 responses from the PortalGuard webserver so clicking Cancel on the pop-up authentication dialog will automatically execute JavaScript that redirects the browser to the PortalGuard HTML-based login form.

To prevent Kerberos from being initiated with this device in the first place, you will need to either:

1) Modify the SSO configuration on the PortalGuard server,

2) Have the client use a different server alias to access the PortalGuard server that is not listed as a valid Kerberos SPN

3) Black list the client IP address or address block

4) Set a permanent “PstarNoKerberos=1” cookie for the PortalGuard website on the device’s browser. This type of cookie will persist across browser restarts, but will not work if the user uses Incognito/InPrivate browsing. If the user clears their browser cookies, the cookie will need to be set again.

Please see the Order of Evaluation section above to understand the checks that are performed before Kerberos is initiated by PortalGuard.