Service Principal Names (SPN): SetSPN Syntax
SPN Purpose
A service principal name (SPN) is the name by which a Kerberos client uniquely identifies an instance of a service for a given Kerberos target computer. If you install multiple instances of a service on computers throughout a forest, each instance must have its own SPN. A given service instance can have multiple SPNs if there are multiple names that clients might use for authentication. For example, an SPN always includes the name of the host computer on which the service instance is running, so a service instance might register an SPN for each name or alias of its host.
SPN Format
serviceclass/host:port servicename
serviceclass and host are required, but port and service name are optional. The colon between host and port is only required when a port is present.
See the following table for a description of each element in the command above:
Element |
Description |
---|---|
serviceclass | A string that identifies the general class of service; for example, "SqlServer". There are well-known service class names, such as "www" for a Web service or "ldap" for a directory service. In general, this can be any string that is unique to the service class. Be aware that the SPN syntax uses a forward slash (/) to separate elements, so this character cannot appear in a service class name. |
host | The name of the computer on which the service is running. This can be a fully-qualified DNS name or a NetBIOS name. Be aware that NetBIOS names are not guaranteed to be unique in a forest, so an SPN that contains a NetBIOS name may not be unique. |
port | An optional TCP or UDP port number to differentiate between multiple instances of the same service class on a single host computer. Omit this component if the service uses the default port for its service class. |
servicename | An optional name used in the SPNs of a replicable service to identify the data or services provided by the service or the domain served by the service. This component can have one of the following formats:
|
Examples of SPN registrations:
- HTTP/www.contoso.com – Any page on the Web site on the default TCP port 80 for www.contoso.com, that is http://www.contoso.com/.
- HTTP/www.contoso.com:8080 – Any page on the Web site on the non-standard TCP port 8080 for www.contoso.com, that is http://www.contoso.com.
- HOST/WORKSTATION5 - Any service running on the computer with NetBIOS name WORKSTATION5
- HOST/SERVER7.contoso.com - Any service running on the computer with hostname SERVER7.contoso.com
- TERMSRV/FRONTRM.contoso.com - The Remote Desktop Protocol (RDP) service running on the computer with hostname FRONTRM.contoso.com
- MSSQLSvc/SQLSERVER2.fabrikam.com:1433 – The SQL Server listening on SQLSERVER2.fabrikam.com, port 1433.
- cifs/KHWIN7.fabrikam.com – The file share on the computer with hostname KHWIN7.fabrikam.com
Notes
- You only need to specify a port when a non-default port is used for the service. See Port Numbers for a list of assigned port numbers.
- The NetLogon service registers the default SPNs for the base operating system and refreshes those every 22 minutes after operating system startup.
SetSPN
SetSPN is the application used to manage SPNs for Windows computers. With SetSPN, you can, view, edit, and delete SPN registrations. The command syntax follows:
Setspn serviceclass/host:portnumber servicename
For example, to register the FIMService on the standard port (meaning you don't have to specify the port number) on a computer named FIMSVR in a domain named contoso.com that is using a service account named FIMService, use the following command:
setspn -s FIMService/FIMSVR.contoso.com CONTOSO\FIMService
The switch -s adds the SPN after verifying that there are no duplicates. To see a list of the SetSPN switches, you can run the command setspn /?
To register the http service on the standard port on a computer named CES1 in the corp.contoso.com domain using a service account named CES, use the following command:
setspn -s http/CES1.corp.contoso.com CORP\CES
Viewing or Checking SPN Registrations
To check the SPNs that are registered for a specific computer using that computer, you can run the following commands from a command prompt:
- setspn -L hostname - Substitute the actual hostname for the computer for hostname (to see the hostname, type hostname as a command prompt). For example, if you typed hostname at the command prompt and the computer reported the name ContosoDC1, you could then type setspn -L contosoDC1 to see what SPNs are registered for that hostname.
- setspn -L localhost - This command will check registrations for the account localhost, which is a name indicative of the local computer.
SPN Registration
The SPN is registered in Active Directory under a user account as an attribute called Service-Principal-Name. The SPN is assigned to the account under which the service the SPN identifies is running. Any service can look up the SPN for another service. When a service wants to authenticate to another service, it uses that service’s SPN to differentiate it from other services running on that computer.
Errors Related to SPN Registration or Configuration
The following error event in the Directory Service log of a domain controller can appear when SPN issues are present:
Event Type | Error |
Event Source | NTDS Replication |
Event Category | Replication |
Event ID | 1645 |
Description | The Directory Service received a failure while trying to perform an authenticated RPC call to another Domain Controller. The failure is that the desired Service Principal Name (SPN) is not registered on the target server. |
Additional errors that may be seen related to SPN issues:
- 0x6 - KDC_ERR_C_PRINCIPAL_UNKNOWN: Client not found in Kerberos database
- 0x7 - KDC_ERR_S_PRINCIPAL_UNKNOWN: Server not found in Kerberos database
- 0x29 - KRB_AP_ERR_MODIFIED: Message stream modified - This error could be related to network connectivity and security equipment such as routers, firewalls, proxy servers, and antimalware gateways modifying packets. You can try to use a network packet analysis tool, such as network monitor, to track down the device that is making the modifications and attempt to configure that device appropriately so that the network packets are not modified.
- 0x1B - KDC_ERR_MUST_USE_USER2USER: Server principal valid for user2user only
- 0x8 - KDC_ERR_PRINCIPAL_NOT_UNIQUE: Multiple principal entries in database. This is likely due to duplicate SPNs and running the command dcdiag /test:checksecurityerror should help you resolve this issue.
- 0x1F - KRB_AP_ERR_BAD_INTEGRITY: Integrity check on decrypted field failed
See also Kerberos and LDAP Error messages.
Manually Registering SPNs
To add an SPN, run the following command at a command prompt:
setspn -s serviceClass/Host:Port AccountName
To delete an SPN, run the following command at a command prompt:
setspn -d ServiceClass / Host : Port AccountName
For example, to remove the SPN for service account name NdesSVC that was granted HTTP protocol access to a computer named NDES1 in the Proseware.com domain, you could run the following command:
setspn -d HTTP/Ndes1.proseware.com proseware\NdesSvc
To reset the default SPN registrations for the host names for an account, run the following command at a command prompt:
setspn -r AccountName
For example, to reset the SPN registrations for KHWIN7, run the command:
setspn -r KHWIN7
For example, to reset the SPN registrations for KHWIN7, run the command:
setspn -r KHWIN7
Caution: Although you can use Setspn -A, you should use Setspn -S instead because -S will verify that there are no duplicate SPNs. However, if you are using Windows Server 2003 or earlier, you will not be able to use the -S switch, unless you've updated to the new SetSPN version from KB 970536 (http://support.microsoft.com/kb/970536). In the case where you cannot use -S, then you should manually verify that there are no duplicate SPNs by first running Setspn -L.
If you are using the updated version of Setspn then find duplicates by using Setspn -x and Setspn -x -f to search across the entire forest.
Troubleshooting SPN Issues
Few SPN problems start with SPN registration being identified as the root cause. More commonly people see something along the lines of invalid credentials, access denied, unauthorized, authentication failure, or something that appears related to a permissions error. Why? SPNs are required by services that use Kerberos and Kerberos is about providing authentication and authorization. Kerberos authentication is not possible for services when SPNs are not correctly configured. SPNs uniquely identify services running on servers, so when an SPN is missing from a computer account, the user often sees an authentication, credential, permission, or access error message.
Resolving SPN Registration Issues
If you discover an SPN registration issue, you can use the SetSPN command to help resolve it. You can try to reregister all the SPNs for the host that is failing to register:
setspn -R hostname
For example, to reregister all the SPNs for a host named server7, you could run the command:
setspn -R Server7
However, there are cases when you need to register an SPN manually. For example, Microsoft KB article 308111 discusses a situation where domain controllers are not replicating because there is a missing SPN. That article focuses on Event ID 1645 appearing in the Event Viewer. However, you may discover missing SPNs by running the command DCDIAG /s:servername /c /v, which tests the critical services on a domain controller. For example, assume there is a domain controller named DC2 in the Fabrikam.com domain. To test the critical services on the domain controller with verbose output, you can run the command:
dcdiag /s:dc2.fabrikam.com /v /c > dcdiag.txt
That command outputs the diagnostic information to the file dcdiag.txt in the directory from which the command was run. Then, you can use notepad to open the file by running the command:
notepad dcdiag.txt
You could then search the file for issues. One issue you might find during the diagnostic is a "Missing SPN" entry during the MachineAccount test, as shown in the following figure.
You could manually register the SPN, using SETSPN or in this specific case use the "dcdiag.exe /fix" command. "dcdiag.exe /fix" will write back the computer account's AD replication SPN. You may also try restarting the domain controller or NTDS service. For example, if you are using a Windows Server 2008 or Windows Server 2008 R2 server, you could restart NTDS by running the following command
net stop ntds && net start ntds
To manually register the SPN that is shown as missing in the figure above, you would enter the command shown in the following figure.
The command from the figure is:
setspn -S E351-4B06-11D1-AB04-00C0FC2DCD2/d89500-a9dc-496d-bf40-775130ec147a/fabrikam.com DC2
SPN Lookup Errors
If a computer is unable to verify the SPN of a computer, a connection request may be denied or fail. For example, one error you might encounter is -2146893022 the target principal name is incorrect. This could be the result of a name resolution issue (DNS or hosts files), duplicate, or missing SPN. You can try running the following command on a domain controller displaying such an error:
dcdiag /test:checksecurityerror
That command will check for missing and duplicate SPNs as well as other errors. When troubleshooting these issues, you should be sure to verify DNS connectivity. See Troubleshooting DNS (Chapter 13) and Troubleshooting DNS (on TechNet) for additional details.
Delegation
Once you have SPNs in place, there's an additional tab available in the ADDS users and computers mmc where you can choose delegation settings.
See Kerberos authentication and delegation: ServicePrincipalNames for more info
External Articles
See the following articles for more information on registration and troubleshooting SPN issues
SPN formatting and registration
- Service Principal Names
- Name Formats for Unique SPNs
- Service Principal Name (SPN) Support in Client Connections
- Registering a Service Principal Name
- How a Service Registers Its SPNs
- How to: Register a Service Principal Name (SPN) for a Report Server
- How to make sure that you are using Kerberos authentication when you create a remote connection to an instance of SQL Server 2005
Specific SPN Issues and Resolutions
- Service Logons Fail Due to Incorrectly Set SPNs
- A missing service principal name may prevent domain controllers from replicating
- Service Principal Name Missing
- Getting rid of the duplicate SPN in Active Directory
- Event ID 11 in the System Log of Domain Controllers - There are multiple accounts with name
- SPNs are not registered in an Active Directory site that includes only read-only domain controllers
- The SPNs that Virtual Server requires are not registered in Active Directory when you try to install Virtual Server 2005 on a Windows-based domain controller
- You receive an "HTTP Error 401.1 - Unauthorized: Access is denied due to invalid credentials" error message when you try to access a Web site that is part of an IIS 6.0 application pool
- Troubleshooting Kerberos Errors
- Remove Duplicate SPNs
- SPN Delegation (Trusted for Delegation) - Allow a user to be trusted for delegation for specific services
- Kerberos authentication and delegation: ServicePrincipalNames
- Security Account Delegation
- Service Principal Name (SPN) checklist for Kerberos authentication with IIS 7.0/7.5
- Service Principal Names and Delegation in Presentation Server
- The 411 on the KDC 11 Events