Setspn

 

Applies To: Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows 8

Reads, modifies, and deletes the Service Principal Names (SPN) directory property for an Active Directory service account. You use SPNs to locate a target principal name for running a service. You can use setspn to view the current SPNs, reset the account's default SPNs, and add or delete supplemental SPNs.

Setspn is a command-line tool that is built into Windows Server 2008. It is available if you have the Active Directory Domain Services (AD DS) server role installed. To use setspn, you must run the setspn command from an elevated command prompt. To open an elevated command prompt, click Start, right-click Command Prompt, and then click Run as administrator.

For examples of how to use this command, see Examples.

It is not usually necessary to modify SPNs. They are set up by a computer when it joins a domain and when services are installed on the computer. In some cases, however, this information can become stale. For instance, if the computer name is changed, the SPNs for installed services must be changed to match the new computer name. Also, some services and applications may require manual modification of a service account's SPN information to authenticate correctly.

For more information about checking SPN registrations and troubleshooting SPNs, see Service Principal Names (https://go.microsoft.com/fwlink/?LinkId=198395). For more information about how a service registers SPNs and how clients compose a service’s SPN, see Service Principal Names (https://go.microsoft.com/fwlink/?LinkId=102556).

In Active Directory, the servicePrincipalName attribute is a multivalued, nonlinked attribute that is built from the DNS host name. The SPN is used in the process of mutual authentication between the client and the server hosting a particular service. The client finds a computer account based on the SPN of the service to which it is trying to connect.

To perform the tasks that are described in the following sections, you must have membership in Domain Admins, Enterprise Admins, or you must have been delegated the appropriate authority. For information on delegating the permissions to modify SPNs, see Delegating Authority to Modify SPNs.

The following sections describe how to run basic Setspn.exe commands. For additional information about the options for Setspn.exe, see Syntax, Remarks, and Examples.

SPN format

When you manipulate SPNs with the setspn, the SPN must be entered in the correct format. The format of an SPN is serviceclass/host:port/servicename, in which each item represents a name or value. Unless the service name and port are not standard, you do not have to enter them when you use setspn. For example, the default SPNs for a server named WS2003A that is providing remote desktop (RDP) services over the default port (TCP 3389) register the following two SPNs in its own Active Directory computer object:

TERMSRV/WS2003A

TERMSRV/WS2003A.cpandl.com

The examples in the following sections assume that the default port and service name are used for SPNs, which is the typical situation. However, if you need to specify a nonstandard SPN configuration, see Name Formats for Unique SPNs

(https://go.microsoft.com/fwlink/?LinkId=102555).

Viewing SPNs

To view a list of the SPNs that a computer has registered with Active Directory from a command prompt, use the setspn –l hostname command, where hostname is the actual host name of the computer object that you want to query.

Note

To find the host name for a computer from a command prompt, type hostname, and then press ENTER.

For example, to list the SPNs of a computer named WS2003A, at the command prompt, type setspn -l S2003A, and then press ENTER. A domain controller named WS2003A in Cpandl.com, which is also functioning as a global catalog server and Domain Name System (DNS) server, registers the following SPNs:

Registered ServicePrincipalNames for CN=WS2003A,OU=Domain Controllers,DC=cpandl,DC=com:

ldap/WS2003A.cpandl.com/ForestDnsZones.cpandl.com

ldap/WS2003A.cpandl.com/DomainDnsZones.cpandl.com

NtFrs-88f5d2bd-b646-11d2-a6d3-00c04fc9b232/WS2008A.cpandl.com

DNS/WS2003A.cpandl.com

GC/WS2003A.cpandl.com/cpandl.com

HOST/WS2003A.cpandl.com/CPANDL

HOST/WS2003A

HOST/WS2003A.cpandl.com

HOST/WS2003A.cpandl.com/cpandl.com

E3514235-4B06-11D1-AB04-00C04FC2DCD2/70906edd-c8a5-4b7d-8198-4f970f7b9f52/cpandl.com

ldap/70906edd-c8a5-4b7d-8198-4f970f7b9f52._msdcs.cpandl.com

ldap/WS2003A.cpandl.com/CPANDL

ldap/WS2003A

ldap/WS2003A.cpandl.com

ldap/WS2003A.cpandl.com/cpandl.com

The globally unique identifier (GUID) 70906edd-c8a5-4b7d-8198-4f970f7b9f52 identifies the NTDS Settings object of the domain controller (NTDS-DSA), which is unique for each domain controller. The other two GUIDs, NtFrs-88f5d2bd-b646-11d2-a6d3-00c04fc9b232 and E3514235-4B06-11D1-AB04-00C04FC2DCD2, identify the File Replication Service (NTFRS) and the Directory Replication Service (DRS) remote procedure call (RPC), respectively, and they are standard SPNs for all domain controllers.

Note

If constrained delegation is in use on a Windows Server 2003 computer that requires an SPN modification, some SPNs may not appear. For more information, see article 936628 in the Microsoft Knowledge Base (https://go.microsoft.com/fwlink/?LinkID=102306).

Resetting SPNs

If the SPNs that you see for your server display what seems to be incorrect names; consider resetting the computer to use the default SPNs. To reset the default SPN values, use the setspn -r hostname command at a command prompt, where hostname is the actual host name of the computer object that you want to update.

For example, to reset the SPNs of a computer named server2, type setspn -r server2, and then press ENTER. You receive confirmation if the reset is successful. To verify that the SPNs are displayed correctly, type setspn -l server2, and then press ENTER.

Note

For information related to troubleshooting SPN issues, see Service Logons Fail Due to Incorrectly Set SPNs (https://go.microsoft.com/fwlink/?LinkId=102554).

Adding SPNs

To add an SPN, use the setspn -s service/name hostname command at a command prompt, where service/name is the SPN that you want to add and hostname is the actual host name of the computer object that you want to update. For example, if there is an Active Directory domain controller with the host name server1.contoso.com that requires an SPN for the Lightweight Directory Access Protocol (LDAP), type setspn -s ldap/server1.contoso.com server1, and then press ENTER to add the SPN.

Removing SPNs

To remove an SPN, use the setspn -d service/name hostname command at a command prompt, where service/name is the SPN that is to be removed and hostname is the actual host name of the computer object that you want to update. For example, if the SPN for the Web service on a computer named Server3.contoso.com is incorrect, you can remove it by typing setspn -d http/server3.contoso.com server3, and then pressing ENTER.

Delegating Authority to Modify SPNs

If you need to allow delegated administrators to configure service principal names (SPNs), you must ensure that their user accounts have the Validated write to service principle name permission.

Membership in Domain Admins, or equivalent, is the minimum required to complete this procedure. Review details about using the appropriate accounts and group memberships at Local and Domain Default Groups (https://go.microsoft.com/fwlink/?LinkId=83477). 

To grant permission to modify SPNs

1. Open Active Directory Users and Computers.

   To open Active Directory Users and Computers, click Start, click Run, type dsa.msc, and then press ENTER.

2. Click View, and verify that the Advanced Features check box is selected.

3. Click Advanced Features, if it is not selected.

   If the domain to which you want to allow a disjoint namespace does not appear in the console, take the following steps:

   1. In the console tree, right-click Active Directory Users and Computers, and then click Connect to Domain.

   2. In the Domain box, type the name of the Active Directory domain to which you want to allow the disjoint namespace, and then click OK.

      As an alternative, you can use the Browse button to locate the Active Directory domain.

4. In the console tree, right-click the node that represents the domain to which you want to allow a disjoint namespace, and then click Properties.

5. On Security tab, click Advanced.

6. On the Permissions tab, click Add.

7. In Enter the object name to select, type the group or user account name to which you want to delegate permission, and then click OK.

8. Configure the Apply onto box for Computer objects.

9. At the bottom of the Permissions box, select the Allow check box that corresponds to the Validated write to service principal name permissions, and then click OK on the three open dialog boxes to confirm your changes.

10. Close Active Directory Users and Computers.

Syntax

setspn <Computer> [-l] [-r] [-d <SPN>] [-s <SPN>] [-?]

Note

Setspn also has an –A that you can use to add SPNs, but 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 because it is not available for that platform. In the case where you cannot use -S, then you should manually verify that there are no duplicate SPNs by first running Setspn -L.

In Windows Server 2008 R2 and Windows Server 2008, Setspn.exe has Edit Mode switches and modifiers and Query Mode switches and modifiers. The syntax is:

setspn [modifiers switch] [accountname]

Where [accountname] can be the name or domain\name of the target computer or user account.

Parameters

Edit Mode Parameters	Description
<Computer>	Specifies the desired Active Directory account object for which to configure the Service Principal Names (SPN). Normally, this is the NetBIOS name of the computer and optionally the domain that contains the computer account. However, any desired Active Directory object name can be used.
-l	Lists the currently registered SPN for computer. Usage: setspn –l accountname
-r	Resets the default SPN registrations for the host names for Computer. Usage: setspn –r accountname For example, to register SPN "HOST/daserver1" and "HOST/{DNS of daserver1}": setspn -R daserver1
-d <SPN>	Deletes the specified SPN for the Computer. Usage: setspn –d SPN accountname For example, to delete SPN "http/daserver" for computer "daserver1": setspn -D http/daserver daserver1
-s <SPN>	Adds the specified SPN for the computer, after verifying that no duplicates exist. Usage: setspn –s SPN accountname For example, to register SPN "http/daserver" for computer "daserver1": setspn -S http/daserver daserver1
-?	Displays help at the command prompt. This parameter is the default: if you run setspn run without this parameter displays the SPN command-line usage.

Edit Mode modifiers	Description
-C	Specify that accountname is a computer account.
-U	Specify that accountname is a user account. For example, to register SPN "http/daserver" for user account "dauser": setspn -U -S http/daserver dauser

Note

-C and -U are exclusive. If neither is specified, the tool will interpret accountname as a computer name if such a computer exists, and a user name if it does not.

Note

Query Mode Parameters

Search for duplicate SPNs.

Usage: setspn -X

Query Mode modifiers	Description
-F	Perform queries at the forest, rather than domain level. For example, to register SPN "http/daserver" for computer "daserver1" if no such SPN exists in the forest: setspn -F -S http/daserver daserver1
-T	Perform query on the specified domain or forest (when -F is also used). Usage: setspn -T domain (switches and other parameters). Use "" or * to indicate the current domain or forest. For example, to report all duplicate registration of SPNs in this domain and contoso domain: setspn -T * -T contoso -X To find all SPNs of the form */daserver registered in the forest to which contoso domain belongs: setspn -T contoso -F -Q */daserver

Remarks

• Query Mode modifiers can be used with the -S switch in order to specify where the check for duplicates should be performed before adding the SPN.

• -T can be specified multiple times. -Q will execute on each target domain or forest. -X will return duplicates that exist across all targets. Service Principal Names (SPNs) are not required to be unique across forests, but duplicate SPNs can cause authentication issues during across-forest authentication.

• SPNs can only be constructed by using the account base name as the Computer parameter. The directory service enforces this by generating a constraint violation error.

  You may not have the rights to access or modify this property on some account objects. You can determine what your access rights are by viewing the security attributes of the account object using the Microsoft Management Console (MMC) in Active Directory Users and Computers. You can also delegate the permission by assigning the Validated write to service principal name permission to the desired user or group.

• The built-in SPNs that are recognized for computer accounts are:

  alerter appmgmt browser cifs cisvc clipsrv dcom dhcp dmserver dns dnscache

  eventlog eventsystem fax http ias iisadmin messenger msiserver mcsvc netdde netddedsm

  netlogon netman nmagent oakley plugplay policyagent protectedstorage rasman remoteaccess replicator

  rpc rpclocator rpcss rsvp samss scardsvr scesrv schedule scm seclogon

  snmp spooler tapisrv time trksvr trkwks ups w3svc wins www

  These SPNs are recognized for computer accounts if the computer has a host SPN. Unless they are explicitly placed on objects, a host SPN can substitute for any of the above SPNs.

• Service Principal Names (SPNs) are not case sensitive when used by Microsoft Windows-based computers. However, an SPN can be used by any type of computer system. Many of these computer systems, especially UNIX-based systems, are case-sensitive and require the proper case to function properly. Care should be taken to use the proper case particularly when an SPN can be used by a non-Windows-based computer.

Examples

Example 1: List currently registered SPNs

        setspn -l daserver1
Registered ServicePrincipalNames for CN=DASERVER1,CN=Computers,DC=reskit,DC=contoso,DC=com:
HOST/daserver1
HOST/daserver1.reskit.contoso.com

Example 2: Reset default registered SPNs

        setspn -r daserver1
Registering ServicePrincipalNames for CN=DASERVER1,CN=Computers,DC=reskit,DC=contoso,DC=com
HOST/daserver1.reskit.contoso.com
HOST/daserver1
Updated object

Example 3: Add a new SPN

        setspn -s http/daserver1.reskit.contoso.com daserver1
Registering ServicePrincipalNames for CN=DASERVER1,CN=Computers,DC=reskit,DC=contoso,DC=com
http/daserver1.reskit.contoso.com
Updated object

Example 4: Remove an SPN

        setspn -d http/daserver1.reskit.contoso.com daserver1
Unregistering ServicePrincipalNames for CN=DASERVER1,CN=Computers,DC=reskit,DC=contoso,DC=com
http/daserver1.reskit.contoso.com
Updated object

Additional references

Command-Line Syntax Key

Change History

Date	Revision
April 23, 2012	Replaced references to using the –A parameter with reference to use –S instead. The –S parameter verifies that no duplicate SPNs exist before adding a new SPN.