This article discusses the Setspn utility and provides some examples.
.gif) Tip |
|
For a more information about Service Principal Names (SPNs), including SetSPN examples, see the TechNet Wiki topic titled Service Principal Names (SPNs) http://social.technet.microsoft.com/wiki/contents/articles/717.aspx |
Tool Location
Setspn.exe: Manipulate Service Principal Names for Accounts
This command-line tool allows you to read, modify, and delete the Service Principal Names (SPN) directory property for an Active Directory service account. SPNs are used 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.
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.
Corresponding UI
There is no corresponding user interface (UI) for this tool.
Concepts
In Active Directory, the servicePrincipalName (SPN) 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.
System Requirements
The following are the system requirements for Setspn:
-
Available starting in Windows XP Professional and Windows Server 2003
File Required
Permission Requirements
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.
Using Setspn.exe
When you install the Setspn.exe tool from Windows Server 2003 Support Tools, you should be able to access the tool at a command prompt (cmd.exe).
To start using Setspn.exe
-
Open a command prompt. To open a command prompt, click Start, click Run, type cmd, and then press ENTER.
-
At the command prompt, type setspn, and then press ENTER.
You should see the setspn command syntax with usage and switches. If you see a message indicating that setspn is not recognized as an internal or external command, use the following steps to change to the Support Tools folder and run the setspn command.
-
To change to the default Support Tools directory, at the command prompt, type cd "c:\Program Files\Support Tools", and then press ENTER.
-
At the command prompt, type setspn, and then press ENTER.
SPN Format
When you manipulate SPNs with the Setspn tool, 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, if you have a service with the following characteristics:
-
Name: MyService
-
Running on a computer named DCA
-
Uses the TCP or UDP port 8088
-
Service name: MyS
-
Location: in the directory under an organizational unit (OU) named CS, in a domain named cpandl.com
the SPN looks like the following:
MyService/DCA.cpandl.com:8088/CN=MyS,OU=CS,DC=cpandl,DC=com
The remaining examples in this topic assume that the default port and service name are used for SPNs, which is typical. Unless the service name and port are not standard, you do not have to enter them when you use Setspn. If you need more information about specifying a nonstandard SPN configuration, see Name Formats for Unique SPNs (http://go.microsoft.com/fwlink/?LinkId=102555).
Assume that there is a server named WS2003A that is providing remote desktop (RDP) services over the default port (TCP 3389). This server registers the following two SPNs in its own Active Directory computer object:
TERMSRV/WS2003A
TERMSRV/WS2003A.cpandl.com
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.
.gif) 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 (http://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.
Adding SPNs
To add an SPN, use the setspn -a service/namehostname 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 -a ldap/server1.contoso.com server1, and then press ENTER to add the SPN.
Removing SPNs
To remove an SPN, use the setspn -d service/namehostname 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.
Setspn Remarks
Troubleshooting Setspn
Service Principal Names (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 Active Directory Users and Computers Microsoft Management Console (MMC) snap-in. The permission can also be delegated by assigning the Validated write to service principal name permission to the desired user or group.
Reporting Bugs
When reporting Setspn bugs or making requests (such as feature requests), please include the following information:
-
A detailed description of the problem or request.
-
The Setspn.exe version number.
-
The account name and current contents of the servicePrincipalName property.
-
The security descriptor of the servicePrincipalName property.
Built-in SPNs
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.
SPN Case Sensitivity
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.
Setspn Examples
List currently registered SPNs
setspn -l daserver1
Registered ServicePrincipalNames for CN=DASERVER1,CN=Computers,DC=reskit,DC=microsoft,DC=com:
HOST/daserver1
HOST/daserver1.reskit.microsoft.com
Reset default registered SPNs
setspn -r daserver1
Registering ServicePrincipalNames for CN=DASERVER1,CN=Computers,DC=reskit,DC=microsoft,DC=com
HOST/daserver1.reskit.microsoft.com
HOST/daserver1
Updated object
Add a new SPN
setspn -a http/daserver1.reskit.microsoft.com daserver1
Registering ServicePrincipalNames for CN=DASERVER1,CN=Computers,DC=reskit,DC=microsoft,DC=com
http/daserver1.reskit.microsoft.com
Updated object
Remove an SPN
setspn -d http/daserver1.reskit.microsoft.com daserver1
Unregistering ServicePrincipalNames for CN=DASERVER1,CN=Computers,DC=reskit,DC=microsoft,DC=com
http/daserver1.reskit.microsoft.com
Updated object
Setspn Syntax
Setspn uses the following syntax:
Setspn Computer [-l] [-r] [-a SPN] [-d SPN] [-?]
Parameters
-
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.
-
-r
-
Resets the default SPN registrations for the host names for Computer.
-
-a SPN
-
Adds the specified SPN for the Computer.
-
-d SPN
-
Deletes the specified SPN for the Computer.
-
-?
-
Displays command-line usage. This parameter is the default: setspn run without this parameter displays the SPN command-line usage.
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.
To grant permission to modify SPNs
-
Open Active Directory Users and Computers. To open Active Directory Users and Computers, click Start, click Run, type dsa.msc, and then press ENTER.
-
Click View, and ensure that the Advanced Features check box is selected. If it is not selected, click Advanced Features. If the domain to which you want to allow a disjoint namespace does not appear in the console, do the following:
-
In the console tree, right-click Active Directory Users and Computers, and then click Connect to Domain.
-
In the Domain box, type the name of the Active Directory domain to which you want to allow the disjoint namespace (or use the Browse button to locate it), and then click OK.
-
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.
-
On Security tab, click Advanced.
-
On the Permissions tab, click Add.
-
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.
-
Configure the Apply onto box for Computer objects.
-
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.
-
Close Active Directory Users and Computers.
See Also