Deployment

Configuring service principal names (SPNs)

Published: 6/11/2009

A service principal name, also known as an SPN, is a name that uniquely identifies an instance of a service. For proper Kerberos authentication to take place, the SPN must be set properly. SPNs are Active Directory attributes, but are not exposed in the standard Active Directory snap-ins.

Ensuring that the correct SPNs are set becomes important when applications such as Microsoft Dynamics CRM, Microsoft SQL Server Reporting Services, and Microsoft SQL Server are split onto multiple servers. When these applications are split across servers, the users' credentials must be passed from one server to another. This process, known as Kerberos delegation, allows a service to impersonate your credentials to another server. For example, when a user runs a Microsoft SQL Server Reporting Services report in Microsoft Dynamics CRM 3.0, or in Microsoft Dynamics CRM 4.0 without the Microsoft Dynamics CRM Connector for Microsoft SQL Server Reporting Services, the authentication occurs in Microsoft Dynamics CRM and then the request is sent to the Microsoft SQL Server Reporting Services server. The Microsoft Dynamics CRM server impersonates the user and the request to Microsoft SQL Server Reporting Services will look as if it came directly from the user.

If SPNs are not set correctly, authentication will be dropped at the Microsoft Dynamics CRM server and the request to Microsoft SQL Server Reporting Services will come from NT Authority\Anonymous Logon. This will result in a 401 authentication error.

On This Page

Working with SPNs

Scenarios specific to Microsoft Dynamics CRM

Additional information

Working with SPNs

SPN format

The format of an SPN is service_class/host:port/service name. Port number and service name are optional elements of the SPN. It is most common to see a port or service name used with SQL Server SPNs. You typically define either the SQL Server port used, the service name of the database instance, or the SQL Server named instance name. In some scenarios, port and service name are also needed for Internet Information Services (IIS) applications. You only need to define the port for IIS when the Web application or service is not listening on the standard HTTP ports of 80 (http) or 443 (https). So when using default ports you will not need to use the service name element for IIS.

Default SPNs

By default, SPNs with the HOST service class are set under all computer accounts. There will be an SPN present for both the NetBIOS and Fully Qualified Domain Name (FQDN). Format of the HOST SPN will be HOST/ComputerName and HOST/ComputerName.FQDN.

When SQL Server is installed it asks for the account that will run the SQL Service. An SPN will automatically get registered under this account with the format MSSQLSvc\ComputerName:port. If you change the service account used by SQL Server after the installation, you may end up with duplicate unless the account being used has permissions on the SQL Server computer account to remove the original MSSQLSvc that was created on the computer account during installation.

When SQL Server is installed it asks for the account that will run the SQL Service. An SPN will automatically get registered under this account with the format MSSQLSvc\ComputerName:port. If you change the service account used by SQL Server after the installation, you may end up with duplicate SPNs unless the account being used has permissions on the SQL Server computer account to remove the original MSSQLSvc SPN that was created on the computer account during installation.

Additional SPNs

Additional SPNs will need to be set in different scenarios. Any time an IIS application pool is running as a service account, additional SPNs are needed. For example, you run an application pool as a domain user instead of Network Service. When running an application pool as a domain account you will add an SPN under that account using the HTTP service class. Note that if the site is an SSL Web site you still only use the HTTP service class, for example, HTTP/ComputerName and HTTP/ComputerName.FQDN.

The other scenario that requires additional SPNs is when an alias/host header is created for a Web site. This will need an SPN with the HTTP service class created under the account running the application pool except that the host header will be used instead of the computer name, for example, HTTP/HostHeader and HTTP/HostHeader.FQDN.

If the account running the SQL Service is changed after the installation, the MSSQLSvc SPN needs to be moved to the new account that is running the service. It is common for users to install SQL Server and use Local System for the Service. This causes the MSSQLSvc/ComputerName:Port to be registered under the computer where SQL Server was installed. At a later time, if a user wants to run the SQL Service as a domain user, the MSSQLSvc SPN must be removed from the computer account and registered under the user account.

Setting an SPN

SPNs can be set from any domain server that has Windows Support Tools installed.

Note

If you are running Windows Server 2003, you will need to install Windows Support Tools. If you are running a Windows Server 2008 domain controller,Windows Support Tools are installed by default. For more information, see Windows Support Tools.

ADSI Edit and the setSPN tool are the most common ways of setting SPNs:

ADSI Edit is an LDAP editor that allows you to manage objects and attributes in Active Directory. ADSI Edit allows you to browse through the objects much like Active Directory Users and Computers. To change the SPN in ADSI Edit, first browse to the user or computer object and open its properties. Find the Service Principal Name property in the list and choose Edit. Here it is easy to add, edit, or delete the SPN for this object.

setSPN is a command-line tool that allows you to read, modify, and delete the SPN for an Active Directory object. It is important to understand that the setSPN tool does actions against a specific account and cannot query for an SPN throughout your domain or forest unless you are using the Windows Server 2008 version of the tool.

The following table shows the typical uses of setSPN.

Task	Command	Examples
List SPNs	setspn –l objectname	setspn –l microsoft\CrmAdmin setspn –l CrmAppServer
Add SPNs	setspn –a service\name objectname	setspn –a HTTP/crm microsoft\CrmAdmin setspn –a HTTP/crm CrmAppServer
Remove SPNs	setspn –d service\name objectname	setspn –d HTTP/crm microsoft\CrmAdmin setspn –d HTTP/crm CrmAppServer

Important

SPNs must be unique. When moving or adding SPNs it is important that a duplicate is not created.

Before you add any SPN entries in Active Directory, it is a good idea to make sure that the SPN is not currently being used by any other accounts within the Active Directory forest. This can be accomplished with several different tools:

You could use LIDFDE to search for the SPN within all domains of the forest.
You could use LDP to search for the SPN within all domains of the forest.
You could use querySPN.vbs.

The best method is to use querySPN.vbs. With this tool, if you target a Global Catalog it can search through the entire domain tree. If you have multiple domain trees in the forest or you have multiple forests, you will need to specify each domain tree root individually and search this way.

The resolution section of the following Microsoft Knowledge Base article explains how to use these tools to work with SPNs: Microsoft Knowledge Base Article 321044: Event ID 11 in the System Log.

For more information about SPNs, see http://blogs.technet.com/askds/archive/2008/03/06/kerberos-for-the-busy-admin.aspx.

Top

Scenarios specific to Microsoft Dynamics CRM

Here are some scenarios where additional SPNs need to be added, or existing SPNs must be moved to a different object in Active Directory. For each scenario, the configuration details are listed. Additional consideration must be taken when other sites are hosted on the servers and other applications are using the same instance of SQL Server.

Important

Be sure to note any changes in case the changes need to be reversed.

Scenario 1: Host header added to site

The host header CRM on port 80 was added to the Microsoft Dynamics CRM Web site. The Microsoft Dynamics CRM Web site is on the server CRMAppServer.contoso.com and the application pool for this Web site is running under Network Service. Because the application pool is running under a computer account, Network Service, this is the location the SPN must be registered.

The following SPNs need to be added to the CRMAppServer.contoso.com object:

HTTP/CRM

HTTP/CRM.contoso.com

To add the SPNs:

First check to ensure that the SPNs aren't already in use.
Type the following in a Command Prompt window:

queryspn.vbs http:/crm*
If none are found the result will display "No SPNs found!"
If no SPNs are found you can add the new SPNs. Type:

setspn -a HTTP/crm CRMAppServer

setspn -a HTTP/crm.contoso.com CRMAppServer

There are a few catches when using Kerberos for authentication. We recommend that you do not use a CNAME record in DNS. Instead, use an A-record or Host record in DNS. If you chose to use a CNAME and your application pool is not configured to use Network Service you will need to deploy an Internet Explorer fix and deploy a registry change (if Internet Explorer 6), or just deploy a registry change (if Internet Explorer 7 or higher) in order to properly authenticate using Kerberos. For more information, see:

Scenario 2: Change Microsoft Dynamics CRM application pool to run as domain user

The Microsoft Dynamics CRM Web site is on the server CRMAppServer.contoso.com. The host header CRM was previously implemented on the Web site. The application pool for the Microsoft Dynamics CRM Web site is currently running under Network Service. The company would like the application pool to run under the domain user CRMService. When changing the account running an application pool, SPNs for the server name and any host headers need to be registered under the new account using the HTTP service class. No duplicates can be created, so some existing SPNs must be removed.

Determine the SPNs that are registered under the current application pool account. The current account is Network Service, which is the local computer object, CRMAppServer.contoso.com. SPNs can be found with ADSI Edit or setSPN. Listed here are the expected SPNs under this object that would be related to IIS. There may be additional SPNs added to the object depending on the installed services.
HOST/CRMAppServer

HOST/CRMAppServer.contoso.com

HTTP/CRM

HTTP/CRM.contoso.com
There are SPNs with two different service classes registered, the default Host SPNs and the HTTP SPNs for the host header. The current HTTP SPNs will need to be removed so they can be added under the new service account. The HOST SPNs do not get removed because these will not cause duplicates due to the unique service class. The following SPNs can be removed using ADSI Edit or setSPN.
HTTP/CRM

HTTP/CRM.contoso.com

Type the following in a Command Prompt window:

setspn -d HTTP/crm CRMAppServer

setspn -d HTTP/crm.contoso.com CRMAppServer
The following SPNs need to be added to the contoso\CRMService object. These are the SPNs for the servername and the host header. Additional SPNs will need to be created if other host headers are used.
HTTP/CRMAppServer

HTTP/CRMAppServer.contoso.com

HTTP/CRM

HTTP/CRM.contoso.com

To add the SPNs:
1. First check to ensure that the SPNs aren't already in use.
  Type the following in a Command Prompt window:
  
  queryspn.vbs http/crm*
2. If none are found the result will display "No SPNs found!"
  If no SPNs are found you can add the new SPNs. Type:
  
  setspn -a HTTP/CRMAppServer contoso\crmservice
3. Repeat this for the remaining SPNs.

Scenario 3: Change the Microsoft Dynamics CRM application pool to run as domain user when other application pools run under separate domain user accounts

The Microsoft Dynamics CRM Web site is on the server CRMAppServer.contoso.com and running under port 5555. The host header CRM was previously implemented on the Web site on port 80. Microsoft Dynamics CRM is accessed with http://CRMAppServer:5555 and http://CRM. The application pool for the Microsoft Dynamics CRM Web site is currently running under Network Service. The company would like the application pool to run under the domain user CRMService.

The server also hosts an intranet site and its application pool runs under the domain user IntranetService. The intranet site is running under port 80. This site also has a host header of intranet on port 80. This site is accessed with http://CRMAppServer and http://Intranet.

Before you can change the account, there are a number of settings you need to get in place to qualify the account for CRMAppPool usage. For more details about other prerequisites needed for a future CRMAppPool account, see Microsoft Knowledge Base Article 932476: Error message in the Workflow Monitor when you use a callout to programmatically run a workflow rule that sends an e-mail message in Microsoft Dynamics CRM 3.0: "0X800404cc".

When changing the account running an application pool, SPNs for the server name and any host headers need to be registered under the new account using the HTTP service class. No duplicates can be created so some existing SPNs must be removed. The problem here is that we have two sites that are running under different accounts and are accessed with the same host name. Adding the HTTP/CRMAppServer SPNs to the CRMService account would create duplicates. We are unable to remove these from the IntranetService because it will cause authentication to fail on that site. This is a scenario where the port is needed in the SPN to uniquely identify the site.

Determine the SPNs that are registered under the current application pool account. The current account is network service, which is the local computer object, CRMAppServer.contoso.com. SPNs can be found with ADSI Edit or setSPN. Here are the expected SPNs that would be related to IIS. There may be additional SPNs added to the object depending on the installed services.
OBJECT: CRMAppServer.contoso.com

HOST/CRMAppServer

HOST/CRMAppServer.contoso.com

HTTP/CRM

HTTP/CRM.contoso.com

OBJECT: contoso\IntranetService

HTTP/CRMAppServer

HTTP/CRMAppServer.contoso.com

HTTP/Intranet

HTTP/Intranet.contoso.com
There are SPNs with two different service classes registered under CRMAppServer.contoso.com, the default Host SPNs and the HTTP SPNs for the host header. The current HTTP SPNs for the Microsoft Dynamics CRM host header will need to be removed so they can be added under the new service account. These SPNs can be removed using ADSI Edit or setSPN.
HTTP/CRM HTTP/CRM.contoso.com
The following SPNs need to be added to the contoso\CRMService object. These are the SPNs for the server name and the host header. Notice that the port number is appended to the SPNs to prevent duplicate SPNs. Additional SPNs will need to be created if other host headers are used.
HTTP/CRMAppServer:5555

HTTP/CRMAppServer.cont:5555

HTTP/CRM

HTTP/CRM.contoso.com

To add the SPNs:
1. First check to ensure that the SPNs aren't already in use.
  Type the following in a Command Prompt window:
  
  queryspn.vbs http/crm*
  
  If none are found the result will display "No SPNs found!"I
2. If no SPNs are found you can add the new SPNs. Type:
  setspn -a HTTP/CRMAppServer contoso\crmservice
3. Repeat this for the remaining SPNs.

When using a non-default port (the default being 80 or 443), Internet Explorer 6 will require a hotfix and a registry change to properly use the Kerberos authentication protocol. The fix is included in Internet Explorer 7, however, it will have to be activated using the same registry keys as Internet Explorer 6. For more information, see Microsoft Knowledge Base Article 908209: Internet Explorer 6 cannot use the Kerberos authentication protocol to connect to a Web site that uses a non-standard port in Windows XP and in Windows Server 2003

Top