The Microsoft Dynamics CRM Blog
News and views from the Microsoft Dynamics CRM Team

Configuring Service Principal Names

Configuring Service Principal Names

  • Comments 6

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’s must be set properly. SPN’s are Active Directory attributes, but are not exposed in the standard AD snap-ins.

IMPORTANCE OF SPN’s

Ensuring the correct SPN’s are set becomes very important when applications such as CRM, SQL Reporting Services (SRS), and SQL are split into multiple servers. By splitting these applications across the servers we require the users’ credentials to be passed from one server to another. This process is called Kerberos delegation.

Kerberos delegation is the process of allowing a service to impersonate your credentials to another server. For example when a user runs a SRS report in CRM we must authenticate into CRM and then the request is sent to the SRS server. The CRM server will impersonate the user and the request to SRS will look as if it came directly from the user. When SPN’s are not set correctly authentication will be dropped at the CRM server and the request to SRS will come from NT Authority\Anonymous Logon. This will result in a 401 authentication error.

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 port or service name used with SQL SPN’s. You typically define either the SQL port used, service name of the database instance or the SQL named instance name. In some scenarios they are also needed for IIS applications. You only need to define the port for IIS when the web application / 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 SPN’s
By default SPN’s 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’s will be HOST/<ComputerName> and HOST/<ComputerName>.<FQDN>.

When SQL Server is installed it asks for the account that will run the SQL Service. A SPN will automatically get registered under this account with the format MSSQLSvc\<ComputerName>:<Port>. If you change the service account used by SQL 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 SPN’s
Additional SPN’s will need to be set in a couple different scenarios. Any time an IIS application pool is running as a service account additional SPN’s 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. Please note that if the site is a SSL website you still only use the HTTP service class.

HTTP/<computer name> and HTTP/<computer name>.<fqdn>.

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

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 and use Local System for the Service. This will cause the MSSQLSvc/<COMPUTERNAME>:<PORT> SPN to be registered under the computer which SQL was installed. At a later time if they wish 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 A SPN
SPN’s can be set from any domain server that has the Windows Support Tools installed. Using ADSI Edit and the SetSPN command-line tool are the most common ways of setting SPN’s.

NOTE: When moving or adding SPN’s it is important that a duplicate is not created. SPN’s must be Unique.

ADSI Edit is a 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’s for this Object. If you are running Windows Server 2003, you will need to download the Support Tools. If you are running this from a Windows Server 2008 domain controller it is installed by default.

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 a SPN throughout your domain or forest unless you are using the Windows Server 2008 version of the tool.

  • Listing SPN’s: To list SPN’s for a particular object use the command setspn –l <objectname>.
    example: setspn –l microsoft\CrmAdmin or setspn –l CrmAppServer
  • Adding SPN’s: To add an SPN to an object use the command setspn – a <service\name> <objectname>.
    example: setspn –a HTTP/crm microsoft\CrmAdmin or setspn –a HTTP/crm CrmAppServer
  • Removing SPN’s: To remove an SPN use the command setspn –d <service\name> <objectname>
    example: setspn –d HTTP/crm microsoft\CrmAdmin or setspn –d HTTP/crm CrmAppServer

Prior to adding 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 in several different ways.

  • 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. 

You can review the following KB article on how to use each of these tools: KB321044 for more detailed information on how to use these tools. 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.

For more information on SPN’s please see the following blog posting: http://blogs.technet.com/askds/archive/2008/03/06/kerberos-for-the-busy-admin.aspx

SCENARIOS SPECIFIC TO MICROSOFT CRM

Below are some following scenarios where additional SPN’s need to be added or existing SPN’s must be moved to a different object in AD. 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. 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 CRM website. The CRM website is on the server CRMAppServer.contoso.com and the application pool for this website is running under Network Service. Since the application pool is running under a computer account, Network Service, this is the location the SPN’s must be registered.

The following SPN’s need to be added to the CRMAppServer.contoso.com object.

  • HTTP/CRM
  • HTTP/CRM.contoso.com

First let’s check to ensure that the SPN’s aren’t already in use. If none are found the result will display "No SPNs found!" If no SPN’s are found you can add the new SPN’s

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 NetworkService you will need to deploy an IE fix and deploy a registry change (if IE6), or just deploy a registry change (if IE7 or higher) in order to properly authenticate using Kerberos.

KB 911149 Error message in Internet Explorer when you try to access a Web site that requires Kerberos authentication on a Windows XP-based computer: "HTTP Error 401 - Unauthorized: Access is denied due to invalid credentials"

http://support.microsoft.com/default.aspx?scid=kb;EN-US;911149

KB 938305 Error message when you try to log on to a Web site that requires Kerberos authentication by using Internet Explorer 7: "Access is denied due to invalid credentials"

http://support.microsoft.com/default.aspx?scid=kb;EN-US;938305

Scenario 2 – Change CRM Application Pool to run as Domain User.
The CRM website is on the server CRMAppServer.contoso.com. The host header CRM was previously implemented on the website. The application pool for the CRM website 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, SPN’s for the servername and any hostheaders need to be registered under the new account using the HTTP service class. No duplicates can be created so some existing SPN’s must be removed.

1. Determine the SPN’s that are registered under the current application pool account. The current account is network service which is the local computer object, CRMAppServer.contoso.com. SPN’s can be found with ADSI Edit or SetSPN. Below are the expected SPN’s under this object that would be related to IIS. There may be additional SPN’s added to the object depending on the installed services.

  • HOST/CRMAppServer
  • HOST/CRMAppServer.contoso.com
  • HTTP/CRM
  • HTTP/CRM.contoso.com

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

  • HTTP/CRM
  • HTTP/CRM.contoso.com

3. The following SPN’s need to be added to the contoso\CRMService object. These are the SPN’s for the servername and the host header. Additional SPN’s will need to be created if other host headers are used.

  • HTTP/CRMAppServer
  • HTTP/CRMAppServer.contoso.com
  • HTTP/CRM
  • HTTP/CRM.contoso.com

First let’s check to ensure that the SPN’s aren’t already in use. If none are found the result will display "No SPNs found!" If no SPN’s are found you can add the new SPN’s

Repeat this for the remaining SPN’s listed in step 3

Scenario 3 – Change CRM Application Pool to run as Domain User when other application pools run under separate domain user accounts.
The CRM website is on the server CRMAppServer.contoso.com and running under port 5555. The host header CRM was previously implemented on the website on port 80. CRM is accessed with http://CRMAppServer:5555 and http://CRM. The application pool for the CRM website 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 first in order to qualify the account for CRMAppPool usage – this blog focuses on SPN’s please see KB932476 for more details on other prerequisites needed for a future CRMAppPool account.

When changing the account running an application pool, SPN’s for the servername and any hostheaders need to be registered under the new account using the HTTP service class. No duplicates can be created so some existing SPN’s 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 SPN’s to the CRMService account would create duplicates. We are unable to remove these from the IntranetService as 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.

1. Determine the SPN’s that are registered under the current application pool account. The current account is network service which is the local computer object, CRMAppServer.contoso.com. SPN’s can be found with ADSI Edit or SetSPN. Below are the expected SPN’s that would be related to IIS. There may be additional SPN’s 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

2. There are SPNs with two different service classes registered under CRMAppServer.contoso.com, the default Host SPN’s and the HTTP SPN’s for the host header. The current HTTP SPN’s for the CRM host header will need to be removed so they can be added under the new service account. These SPN’s can be removed using ADSI Edit or SetSPN.

  • HTTP/CRM
  • HTTP/CRM.contoso.com

3. The following SPN’s need to be added to the contoso\CRMService object. These are the SPN’s for the servername and the host header. Notice that the port number is appended to the SPN to prevent duplicate SPN’s. Additional SPN’s will need to be created if other host headers are used.

  • HTTP/CRMAppServer:5555
  • HTTP/CRMAppServer.cont:5555
  • HTTP/CRM
  • HTTP/CRM.contoso.com

First let’s check to ensure that the SPN’s aren’t already in use. If none are found the result will display "No SPNs found!" If no SPN’s are found you can add the new SPN’s

Repeat this for the remaining SPN’s listed in step 3

When using a non default port (Default being 80 or 443)_IE 6 will require a hotfix and a registry change to properly utilize the Kerberos authentication protocol. The fix is included in IE 7 however it will have to be activated using the same registry keys as IE 6.

KB 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. http://support.microsoft.com/default.aspx?scid=kb;EN-US;908209

If you are using IIS7 with Kernel-Mode authentication enabled please be aware that the SPN requirements are changed, for more details please review this blog: http://blogs.msdn.com/webtopics/archive/2009/01/19/service-principal-name-spn-checklist-for-kerberos-authentication-with-iis-7-0.aspx 

For additional learning/resources on Kerberos related issues please also visit the the AskDS blog site maintained by our Directory Services Support teams:

More detailed information on how Kerberos authentication works: http://blogs.technet.com/askds/archive/2008/03/06/kerberos-for-the-busy-admin.aspx

Detailed information on how to troubleshoot a SPN specific issues:

Cheers,

Jeremy Morlock and Henning Petersen

  • Very very very good article!

    Thanks!

  • Jeremy Morlock and Henning Petersen: Thanks so much!

  • Hi Jeremy & Henning,  great article on a complex topic.

    One question that is confusing me. It's recommended to use separate service accounts to run CRM and SSRS (in fact you can't install the Data Connector without this).

    Do we then need to add an SPN for this service account to delegate to MSSQLSvc? Doesn't that introduce a duplicate SPN for MSSQLSvc?

    thanks Charlie

  • Very odd. I have to use TWO different accounts foor the CRM Web Application pool AND the XRMDeployment Application Pool. They both run under the same URL however... so.. how to enable kerberos for this?

    Regards,

    Wesley Bakker

  • Your question is relevant for CRM 2011. This article was geared towards CRM 4.0 and IIS 6.0.

    CRM 2011 runs on IIS 7.x which has Kernel mode authentication enabled by default. When Kernel mode is turned on the SPN's go under the machine account regardless of who runs the CRM Application Pools. If you consider NLB then CRM AppPools would HAVE to share a Service account and you would need to run both CRMAppPool and CRMDeploymentServiceAppPool under the same account. OR if you prefer to not do that you can split the CRMDeployment service to a different CRM server.

    For more on SPN's and IIS 7.x please see

    blogs.msdn.com/.../service-principal-name-spn-checklist-for-kerberos-authentication-with-iis-7-0.aspx

    Thanks,

    Henning

  • Note that if you have http/ SPNs that also list a port number, that they could end up causing the CRM 2011 Outlook client from failing to configure.  Note that the CRM 2011 Outlook client configuration error doesn't really clue you in that the problem is really server side, so am including the call stack from that error below in the hopes it can save someone else time in resolving it if this is seen by another user:

    Error| Exception : An error has occurred. Try this action again. If the problem continues, check the Microsoft Dynamics CRM Community for solutions or contact your organization's Microsoft Dynamics CRM Administrator. Finally, you can contact Microsoft Support.    at Microsoft.Crm.MapiStore.DataStore.WaitInitialized()

      at Microsoft.Crm.Application.Outlook.Config.OutlookConfigurator.InitializeMapiStoreForFirstTime()

      at Microsoft.Crm.Application.Outlook.Config.OutlookConfigurator.Configure(IProgressEventHandler progressEventHandler)

      at Microsoft.Crm.Application.Outlook.Config.ConfigEngine.Configure(Object stateInfo)

    16:30:52|  Error| Exception : Server was unable to process request.

    That could be resolved by removing the http SPNs with a port number and adding the http SPNs without a port number like I've shown as an example below:

    1.  Removal of SPNs with port numbers:

    setspn -D http/hostnameofCRMServer.Domain.com:8080 Domain\CRMAppPoolAccountUser

    setspn -D http/hostnameofCRMServer:8080 Domain\CRMAppPoolAccountUser

    2.  Adding of correct SPNs wtihout the port numbers:

    setspn -S http/hostnameofCRMServer.Domain.com Domain\CRMAppPoolAccountUser

    setspn -S http/hostnameofCRMServer Domain\CRMAppPoolAccountUser

Page 1 of 1 (6 items)
Leave a Comment
  • Please add 5 and 4 and type the answer here:
  • Post