- 9 minutes to read

HTTP SPNs for IIS: Kerberos Windows Authentication for the Nodinite Web Client

When a user opens the Nodinite Web Client, the browser asks Active Directory for a Kerberos ticket for HTTP/<the hostname in the address bar>. IIS then has to decrypt that ticket with the right account's key. If the HTTP SPN is missing, sits on the wrong account, or IIS uses the wrong key, you see:

  • A login prompt instead of transparent sign-in
  • 401 Unauthorized responses from the Web Client or Web API
  • Slow page loads, because the browser silently fell back to NTLM

The same applies to every IIS-hosted Nodinite v7 service that uses Windows authentication with a domain account: the Web Client, Web API, Log API, Logging Service, Monitoring Service, MCP Endpoint, and Pickup Service.

This guide covers the IIS side of SPNs. Unlike SQL Server SPNs, HTTP SPNs depend on the hostname users type, and IIS has two settings that decide which account decrypts the ticket. For SQL Server and linked servers, see SQL Server SPNs. For the concepts, the shared setspn commands, and the service account rules, see the SPN hub.

Understanding Kerberos for IIS-Hosted Nodinite Services

flowchart LR Browser["fa:fa-user Browser<br/>site in Local Intranet Zone"] DNS["fa:fa-signs-post DNS<br/>nodinite.contoso.com"] DC["fa:fa-shield-halved Domain Controller<br/>finds owner of HTTP/nodinite.contoso.com"] IIS["fa:fa-globe IIS site Nodinite-PROD-WebClient<br/>Windows Authentication"] Pool["fa:fa-id-badge App pool account<br/>CONTOSO\svc-iis-nodinite"] Machine["fa:fa-server Computer account<br/>WEB01$ with HOST/web01"] Browser -->|"1. Resolve name"| DNS Browser -->|"2. Ticket for HTTP/nodinite.contoso.com"| DC Browser -->|"3. Present ticket"| IIS IIS -->|"useAppPoolCredentials = true"| Pool IIS -.->|"useAppPoolCredentials = false"| Machine style Browser fill:#2678BD style DNS fill:#2678BD style DC fill:#9E59BB style IIS fill:#2678BD style Pool fill:#93d16d style Machine fill:#3F827B

Diagram: the browser builds the SPN from the hostname it resolved, and the Domain Controller encrypts the ticket for that SPN's owner. IIS decrypts with the app pool account (green, preferred) or the computer account (teal, fallback) depending on useAppPoolCredentials. The SPN owner and the IIS setting must match.

Key Components Explained

Component Role Requirement
Hostname The name in the browser address bar; the browser builds HTTP/<hostname> from it A real DNS name, not a hosts-file entry; a CNAME resolves to the target host name
HTTP SPN Maps the hostname to the account that can decrypt tickets Always HTTP/, even for HTTPS; short name and FQDN
Application pool identity The account the Nodinite site runs as Domain account or gMSA when the SPN is on the app pool account
useKernelMode IIS performs Windows authentication in kernel mode (HTTP.sys) true for both designs below
useAppPoolCredentials Kernel mode decrypts tickets with the app pool account instead of the computer account true when the HTTP SPN is on the app pool account
Browser zone Browsers send Kerberos tickets automatically only to trusted sites Site in the Local Intranet Zone, or allowed by policy

Who Owns the HTTP SPN?

The design decision is which account owns the HTTP SPN. IIS must be configured to match it.

Web Client URL App pool identity HTTP SPN owner useKernelMode useAppPoolCredentials Recommendation
Dedicated DNS alias, for example nodinite.contoso.com Domain account or gMSA App pool account (HTTP/nodinite...) true true Preferred for production and Kerberos-only environments
Machine name, for example web01.contoso.com Domain account or gMSA Computer account (through HOST/web01) true false Fallback when a dedicated alias isn't possible
Machine name ApplicationPoolIdentity or Network Service Computer account (through HOST/web01) true false (default) Works without manual SPNs; not suited to web farms

Tip

Use a dedicated DNS alias. It avoids conflicts with the computer account, works for web farms, and lets the TLS certificate and the SPNs follow the service instead of the server. Add the alias to the certificate SAN, see How to perform hardening on your Nodinite installation.

What You Need Before Starting

  • The IIS site name. Nodinite Web Client sites follow the naming standard Nodinite-<ENVIRONMENTNAME>-WebClient, for example Nodinite-PROD-WebClient or Nodinite-DEMO-WebClient. The examples on this page use Nodinite-PROD-WebClient; replace PROD with your environment name.
  • The application pool identity: in IIS Manager, select Application Pools, select the Nodinite pool, select Advanced Settings, and note Identity.
  • Every hostname users and clients use to reach the site, short name and FQDN.
  • Domain Admin rights, or an Active Directory administrator who can run setspn.

Register HTTP SPNs

The setspn flags (-S, -L, -Q, -X, -D) are described once in the SPN hub. This section shows only the HTTP SPN values. Skip it if you use the machine-name fallback; the computer account already covers the machine name.

Register SPNs for Every Client Hostname

Register an SPN for every name a client may use to reach the Web Client:

  • DNS alias or CNAME - the name users type, for example nodinite. Register the FQDN (nodinite.contoso.com) and the short name (nodinite).
  • Physical machine name - only when clients may also browse to the server directly and the app pool account owns the HTTP SPNs. If the machine name conflicts with the computer account, see HTTP SPN Ownership Conflicts below.

Kerberos builds the ticket request from the exact name the client resolved, so a missing short name or FQDN makes authentication fail for that name only, which looks like an intermittent problem.

Note

Always use HTTP in the SPN, even when the site uses HTTPS. There is no HTTPS/ service class.

Single Server with a DNS Alias 

setspn -S HTTP/nodinite.contoso.com CONTOSO\svc-iis-nodinite
setspn -S HTTP/nodinite CONTOSO\svc-iis-nodinite

Load-Balanced Web Farm

In a web farm, every node must run the application pool as the same domain account, because the alias SPN can have only one owner.

:: DNS alias or load-balancer name, used by all clients
setspn -S HTTP/nodinite.contoso.com CONTOSO\svc-iis-nodinite
setspn -S HTTP/nodinite CONTOSO\svc-iis-nodinite

Only add node names (HTTP/web01, HTTP/web02, and their FQDNs) when clients reach individual nodes directly, and check them for computer-account conflicts first.

Non-Default Ports and Multiple Bindings

On the default ports 80 and 443, browsers don't include the port in the SPN, so HTTP/nodinite.contoso.com is enough. Ports matter only when one server hosts several sites under different identities on the same hostname, for example PROD and TEST on one box with different ports.

The clean design is a separate DNS name per site, so each SPN stays unambiguous. If that isn't possible, force the port into the SPN lookup on the IIS server, then register HTTP/<host>:<port> SPNs:

# Run as Administrator on the IIS server
Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Services\HTTP\Parameters" `
    -Name "FEATURE_INCLUDE_PORT_IN_SPN_KB908209" -Value 1 -Type DWord
iisreset

Warning

This registry value is server-wide and affects every IIS site on the machine. Use it only for multi-site, multi-identity servers that can't use separate hostnames.

Configure IIS Windows Authentication

Set useKernelMode and useAppPoolCredentials on the Nodinite site to match the SPN owner from the table above. Use either the command line or IIS Manager.

Option 1: Command Line (appcmd) 

:: Preferred: dedicated alias, HTTP SPN on the app pool account
%windir%\system32\inetsrv\appcmd.exe set config "Nodinite-PROD-WebClient" -section:system.webServer/security/authentication/windowsAuthentication /useKernelMode:"True" /useAppPoolCredentials:"True" /commit:apphost

:: Fallback: machine-name URL, computer account owns the HTTP SPN
%windir%\system32\inetsrv\appcmd.exe set config "Nodinite-PROD-WebClient" -section:system.webServer/security/authentication/windowsAuthentication /useKernelMode:"True" /useAppPoolCredentials:"False" /commit:apphost

Option 2: IIS Configuration Editor

  1. Open IIS Manager and, under Sites, select the Nodinite site, for example Nodinite-PROD-WebClient.
  2. In Features View, open Configuration Editor in the Management section.
  3. In Section, select system.webServer/security/authentication/windowsAuthentication.
  4. Set useKernelMode to True.
  5. Set useAppPoolCredentials to True for the dedicated-alias design, or False for the machine-name fallback.
  6. Select Apply in the Actions pane.

IIS Manager Configuration Editor showing the windowsAuthentication section with useAppPoolCredentials set to True for the Nodinite-DEMO-WebClient site
The windowsAuthentication section of the Nodinite-DEMO-WebClient site, with useAppPoolCredentials being changed from the drop-down.

Tip

If Configuration Editor isn't available in IIS Manager, install the IIS management features listed in IIS Windows Features.

Apply the Change

Run iisreset on the IIS server, then clear cached tickets on the client with klist purge before you retest.

HTTP SPN Ownership Conflicts

If the Web Client URL is the machine name (for example https://web01.contoso.com on server web01), Active Directory maps the HTTP service class to the computer account's built-in HOST SPN (HOST/web01). Registering HTTP/web01 on the app pool account then fails with 0x21c7/8647 (not unique forest-wide), even when setspn -Q HTTP/web01 shows no HTTP/ row.

To resolve it:

  1. Run setspn -Q HTTP/web01, setspn -Q HTTP/web01.contoso.com, and setspn -X to find explicit owners and duplicates.
  2. If a stale account owns the HTTP/ SPN, remove it from that account with setspn -D, as described in the SPN hub.
  3. If the conflict is the computer account's HOST/ SPN, choose a design:
    • Preferred: move users to a dedicated DNS alias, register HTTP/ SPNs for the alias on the app pool account, and set useAppPoolCredentials to true.
    • Fallback: keep the machine-name URL, leave the SPN with the computer account, and set useAppPoolCredentials to false.

Warning

Never move or remove HOST/<machine> SPNs from a computer account to make room for an app pool account. Other services on the server depend on them.

Verify Kerberos

  1. On the client, run klist purge, then open a new browser window and browse to the Web Client.
  2. Confirm no login prompt appears.
  3. Run klist and look for a ticket for the hostname you used:
Server: HTTP/nodinite.contoso.com @ CONTOSO.COM
KerbTicket Encryption Type: AES-256-CTS-HMAC-SHA1-96

If there's no HTTP/ ticket, the browser used NTLM. Check that the site is in the Local Intranet Zone, see Kerberos Transparent Login After v7 Upgrade, and use the diagnostic script in NTLM vs Kerberos Authentication.

Common IIS SPN Issues

Issue Cause Solution
Login prompt in the Web Client HTTP SPN missing for the hostname used, or useAppPoolCredentials doesn't match the SPN owner Register short-name and FQDN SPNs; align IIS settings with the owner table
Login prompt after upgrading from v6 to v7 v7 runs as its own site under a domain account Follow Kerberos Transparent Login After v7 Upgrade
401 Unauthorized from the Web Client or Web API HTTP SPN missing on the app pool account Register HTTP SPNs for every client hostname
Works with the FQDN, fails with the short name (or the reverse) Only one of the two SPNs registered Register both
Works on one web farm node, fails on another Nodes run the app pool as different accounts Run every node as the same account
Web Client slow, no login prompt Browser fell back to NTLM See NTLM vs Kerberos Authentication
setspn -S HTTP/... returns 0x21c7/8647 SPN owned by another account, or conflicts with HOST/ See HTTP SPN Ownership Conflicts above
Web Client fails with NTLM disabled Missing HTTP SPN, with no fallback Register SPNs for every hostname before go-live

Next Steps