How Service Publication and Service Principal Names Work
Applies To: Windows Server 2003, Windows Server 2003 R2, Windows Server 2003 with SP1, Windows Server 2003 with SP2, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2
In this section
Service Publication and SPN Architecture
Service Publication and SPN Protocols
Service Publication and SPN Physical Structure
Service Publication and SPN Processes and Interactions
Related Information
Services use service publication in Active Directory to provide information about themselves in the directory for easy discovery by client applications and other services. In addition, Active Directory supports service principal names (SPNs) as a means by which client applications can identify and authenticate the services that the client applications use. Service publication is accomplished through the creation of service objects (also called connection point objects) in Active Directory. Service authentication is accomplished through Kerberos authentication of SPNs.
Note
In Windows 2000 Server and Windows Server 2003, the directory service is named Active Directory. In Windows Server 2008 and Windows Server 2008 R2, the directory service is named Active Directory Domain Services (AD DS). The rest of this topic refers to Active Directory, but the information is also applicable to AD DS.
Service publication and SPNs work through special objects and attributes that are stored in Active Directory. These objects and attributes are published to the directory by the respective services that the objects and attributes represent. Service publication and SPNs are optional capabilities of Active Directory, and they are not required for a properly functioning Active Directory infrastructure. However, a properly functioning Active Directory infrastructure is required for service publication and SPNs to work.
In addition to a properly functioning Active Directory infrastructure, an ideal environment for service publication and SPNs requires that the following components be present and functioning properly:
Kerberos and Key Distribution Center (KDC)
The services that use Active Directory to publish information about themselves
The client applications that authenticate and use the published services
Network connectivity, including Internet Protocol (IP), among all components
This section describes the elements of Active Directory service publication and SPNs, including their architecture, protocols, physical structure, and processes and interactions.
Service Publication and SPN Architecture
The primary components of the service publication and SPN architecture are the services that publish information about themselves and the client applications that search the directory to discover the services. In addition, Active Directory plays a key role in the architecture, both as the storage and distribution mechanism for published service information and as a source for the SPN attributes that are used in mutual authentication. Finally, the KDC provides the mechanism for authenticating services by means of the SPNs that are constructed by the client applications. The relationships of these components are shown in the following figure.
Service Publication and SPN Architecture
.gif "Service Publication and SPN Architecture")
The following table describes the service publication and SPN components.
Service Publication and SPN Components
| Component | Description |
|---|---|
Service |
An application that makes data or operations available to network clients. |
Client application |
An application running on a workstation or on a server that makes use of a service. |
KDC |
A service running on every domain controller that provides authentication services for clients, as well as for servers and services. A client application requests the authentication of an SPN through a KDC. |
Active Directory |
The directory that is used to store connection point objects and service account objects. |
Connection point object |
An object in Active Directory that contains information about a service. Client applications search for these objects to find out about services that are available on the network. Typically, connection point objects are created on the computer object of the computer on which a given service is running. |
SPN attribute |
An attribute that contains a unique name that identifies an instance of a service. An SPN attribute resides on the service account object in whose security context a given service instance runs. |
Service Publication and SPN Protocols
Service publication and SPNs rely on the IP network protocol as well as on transport protocols, including Transmission Control Protocol (TCP) and User Datagram Protocol (UDP). Client applications perform service discovery against Active Directory by using the standard operations of the Lightweight Directory Access Protocol (LDAP). Client applications request mutual authentication of services by using the Kerberos V5 authentication protocol. The protocols that are used in service publication and authentication are shown in the following figure.
Service Publication and SPN Protocols
.gif "Service Publication and SPN Protocols")
The following table describes the service publication and SPN protocols.
Service Publication and SPN Protocols
| Protocol | Description |
|---|---|
LDAP |
The core protocol that is used to communicate with Active Directory. LDAP is described in RFC 2551 (LDAP v3) and RFC 1777 (LDAP v2). |
Kerberos |
The authentication protocol that is used by clients and services to communicate with the KDC. |
TCP |
The connection-oriented session protocol on which LDAP runs. |
UDP |
The connectionless session protocol on which Kerberos runs. |
IP |
The standard network protocol that is used by Windows Server 2003. |
Service Publication and SPN Physical Structure
In Active Directory, the physical structure for service publication consists of connection point objects and the containers in which those objects reside. Typically, connection point objects are created on the computer object of the computer on which a given service is running.
Microsoft SQL Server 2000 is an example of an application that supports the publication of information about itself in Active Directory by using connection point objects. SQL Server 2000 supports the registration of instances of the SQL Server relational database engine, databases, replication publications, and analysis servers in Active Directory.
For example, SQL Server 2000 can be installed on a computer for which the distinguished name in Active Directory is the following:
CN=dbserver,OU=ComputersOU,DC=corp,DC=cohovineyard,DC=com
After installing SQL Server 2000, an administrator can register an instance of the SQL Server relational database engine in Active Directory by using the tools that are provided by SQL Server 2000. After the database engine is registered in Active Directory, an MS-SQL-SQLServer connection point object is added to the container. This new connection point object has the following distinguished name:
CN=MS-SQL-SQLServer,CN=dbserver,OU=ComputersOU,DC=corp,DC=cohovineyard,DC=com
For more information about SQL Server 2000 service publication, see “Active Directory Integration” in the “Microsoft Platform SDK” on MSDN.
Note
You can search Active Directory for existing connection point objects, using the dsquery command-line tool, by typing the following at a command prompt:
dsquery * forestroot -filter (objectclass=serviceconnectionpoint)
For more information about dsquery, at a command-line prompt, type:
dsquery /?
The physical structure for client authentication of services consists of the service account objects of the services to be authenticated, the SPN attributes that reside on those objects, and the containers in which those objects reside. The service account under which a service runs determines the security identity of the service at run time, that is, it determines the service’s primary security context. The security context determines the service’s ability to access local and network resources. Generally, the service installer specifies the service account when it calls the CreateService function to install the service on a host computer. In addition, if the service is to support mutual authentication by means of SPNs, the service installer registers SPNs on the service account object as an attribute. If the service runs under a domain user account, the SPN attribute is created on the domain user account under which the service runs. If the service runs under the Local System account, the service’s logon account is the computer account of the host computer.
Connection Point Objects
A connection point object is used in Active Directory to represent a service and to store information about that service. Connection point objects are derived from the connectionPoint schema class, which is the base class from which all objects representing connectable resources are derived. The following figure shows some of the object classes that are derived from the connectionPoint object class.
connectionPoint Class and Derived Classes
.gif "Class and Derived Classes")
The following items are examples of objects that are derived from the connectionPoint class and that are used by various services to publish their availability on the network.
printQueue and volume
The printQueue and volume objects are the standard connection points that are used by print services and file services, respectively. These objects are used to help directory clients find available printers and shared volumes on the network.
rpcEntry
The rpcEntry object class is used by services that publish information about themselves by using the RPC Name Service (RpcNs) application programming interfaces (APIs). Typically, objects of this class can be found in a container in the domain directory partition whose distinguished name is similar to the following:
CN=RpcServices,CN=System,DC=cohovineyard,DC=com
serviceInstance
The serviceInstance object class is used by Windows Sockets (Winsock) services that publish information about themselves by using registration and resolution (RnR).
Typically, objects of this class can be found in a container in the domain directory partition whose distinguished name is similar to the following:
CN=WinsockServices,CN=System,DC=cohovineyard,DC=com
serviceConnectionPoint
The serviceConnectionPoint object class is most commonly used by application-oriented (rather than infrastructure) services that publish information about themselves in Active Directory. Examples of services that publish information about themselves by using service connection points (SCPs) include SQL Server 2000, Remote Installation Services (RIS), and Active Directory Application Mode (ADAM).
Active Directory does not define how the attributes of the serviceConnectionPoint class are to be used; therefore, clients of a service that is published as an SCP must be able to interpret and use the data that is published in the SCP. Services that must publish additional data about themselves can extend the Active Directory schema by creating a subclass of the serviceConnectionPoint class and giving the subclass a distinct name.
The most important attributes of the serviceConnectionPoint class are keywords, serviceDNSName, serviceDNSNameType, serviceClassName, and serviceBindingInformation. Client applications search the directory for keywords values to locate a connection point object. When a connection point object is found, clients can read other attributes to retrieve service data. The most important attributes of the serviceConnectionPoint class are described in the following table.
serviceConnectionPoint Attributes
| Attribute | Description |
|---|---|
keywords |
The keywords attribute can contain multiple string values that identify a given service. This attribute is included in the global catalog, which means that clients in any domain of a forest can search the global catalog for keywords that are associated with the service. This attribute is also indexed, which improves query performance. The installer that creates the SCP object sets the values of the keywords attribute. Typically, these values are not modified by the active service. The exact keywords that should be included in your SCP depend on how clients search for the service. One type of keyword that is important to include is the GUID string, because globally unique identifiers (GUIDs) are guaranteed to be unique in a forest. Use the GUID string format that is returned by the GuidToString function in the remote procedure call (RPC) library. Also important to include are human-readable names for clients to search for a given service. The keywords in an SCP object should include GUID strings and names that identify the following data about the service:
For SCP objects that publish a specific set of data or capabilities for a type of service, a GUID string or name should be included that identifies the specific instance. For example, a database service might publish an SCP object for a specific database. In this case, the SCP object should include a product GUID to identify the service and another GUID to identify the database. |
serviceDNSName and serviceDNSNameType |
Client applications use the serviceDNSName and serviceDNSNameType attributes to determine the service’s host computer. These attributes are not indexed, and they are not replicated as part of the global catalog. The serviceDNSNameType value indicates the type of DNS name that is specified by serviceDNSName — usually, “A” if serviceDNSName contains a host name or “SRV” if serviceDNSName contains an SRV record name. The serviceDNSName value is typically the DNS name of the service’s host computer. Your service installer can call the GetComputerNameEx function to get the DNS name of the local computer. For services that have DNS SRV records, serviceDNSName can be the name of the SRV record. A client application uses the DNS APIs to retrieve all the SRV records that match this name. The client then retrieves the DNS host name from one of the SRV records. This technique is useful for replicated services, because SRV records also include data that enables the client to select the best replica. |
serviceClassName |
This is a single-value property that identifies the class of service that is represented by the SCP. This attribute is not indexed, and it is not replicated as part of the global catalog. This is a descriptive string that is specific to the service that published the SCP; for example SqlServer. For services that support mutual authentication, clients can use this property, along with the DNS name of the service’s host computer, to form an SPN. |
serviceBindingInformation |
This is a multivalue property that contains string values that store data that is required to bind to a service. This property is indexed, and it is replicated to the global catalog. The content of serviceBindingInformation is specific to the service that publishes the SCP; clients must interpret the binding data. In the most common case, the binding data consists of a port number on the service host computer. Examples of service binding information include the following:
|
SPNs
A service principal name (SPN) is the name by which a client uniquely identifies an instance of a service. SPN structures generally follow Internet Engineering Task Force (IETF) naming conventions, and they often include the name of the computer on which the service is running. SPNs may be used to request Kerberos tickets, and they are required for mutual authentication. An example of an SPN is MyDBService/host1.cohovineyard.com, where MyDBService is the name of the service and host1.cohovineyard.com is the name of the host on which the service resides. If multiple instances of a service are installed 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; therefore, a service instance might register an SPN for each name or alias of its host.
Before Kerberos can use an SPN to authenticate a service, the SPN must be registered on the account object that the instance of the service uses to log on. A given SPN can be registered on only one account. For Win32 services, a service installer specifies the logon account when an instance of the service is installed. The installer then composes the SPNs and writes them as a property of the account object in Active Directory. If the logon account of a service instance changes, the SPNs must be manually registered again under the new account.
When a client attempts to connect to a service, it locates an instance of the service, composes an SPN for that service instance, connects to the service, and presents the SPN for the service to authenticate.
Name Formats for Unique SPNs
An SPN must be unique in the forest in which it is registered. If it is not unique, authentication will fail. The SPN syntax has four elements: two required elements and two additional elements that can be used, if necessary, to produce a unique name, as follows:
ServiceClass/Host:Port/ServiceName
Each of these SPN elements is described in the following table.
SPN Elements
| 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; therefore, the forward slash 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 network basic input/output system (NetBIOS) name. Be aware that NetBIOS names are not guaranteed to be unique in a forest, and Active Directory does not enforce uniqueness for the host component of an SPN. |
Port |
An optional port number to differentiate between multiple instances of the same service class on a single host computer. This component can be omitted if the service uses the default port number that is reserved for its service class (port number 389 for LDAP, for example). |
ServiceName |
An optional name that is used in the SPN of a replicable service to identify the data or services that are provided by the service or to identify the domain that is served by the service. This component can have one of the following formats (each of which are guaranteed to be unique within Active Directory):
|
The components that are present in a service’s SPNs depend on how the service is identified and replicated. There two types of services: host-based services and replicable services.
Host-based services
For a host-based service, the ServiceName component is omitted because the service is uniquely identified by the service class and by the name of the host computer on which the service is installed, as follows:
ServiceClass/Host
The service class alone is sufficient to identify for clients the features that the service provides. You can install instances of the service class on many computers, and each instance provides services that are identified with its host computer. File Transfer Protocol (FTP) and Telnet are examples of host-based services. The SPNs of a host-based service instance can include the port number if the service uses a nondefault port or if there are multiple instances of the service on the host, as follows:
ServiceClass/Host:Port
Replicable services
For a replicable service, there can be one or many instances of the service (replicas), and clients do not differentiate which replica they connect to because each replica provides the same service. The SPNs for each replica have the same ServiceClass and ServiceName components, where ServiceName identifies more specifically the features that are provided by the service. Only the Host and optional Port components vary from SPN to SPN.
An example of a replicable service is an instance of a database service that provides access to a specified database. In this case, ServiceClass identifies the database application, and ServiceName identifies the specific database. ServiceName might be the distinguished name of an SCP object that contains connection data for the database. As shown in the following examples, only the value for host varies among the service instances:
MyDBService/host1.cohovineyard.com/CN=hrdb,OU=mktg,DC=cohovineyard,DC=com
MyDBService/host2.cohovineyard.com/CN=hrdb,OU=mktg,DC=cohovineyard,DC=com
MyDBService/host3.cohovineyard.com/CN=hrdb,OU=mktg,DC=cohovineyard,DC=com
If clients use the NetBIOS name to compose a service’s SPN, each replica must also register an SPN that contains the NetBIOS name. The following examples show SPNs that are constructed by using NetBIOS host names:
MyDBService/host1/CN=hrdb,OU=mktg,DC=example,DC=com
MyDBService/host2/CN=hrdb,OU=mktg,DC=example,DC=com
MyDBService/host3/CN=hrdb,OU=mktg,DC=example,DC=com
Another example of a replicable service is one that provides services to an entire domain. In this case, the ServiceName component is the DNS name of the domain being served. A Kerberos KDC is an example of this type of replicable service.
Be aware that if the DNS name of a computer changes, that computer updates the Host element for all registered SPNs for that computer in the forest.
With Active Directory you can find and connect to a directory-enabled service by using attributes other than the computer name or the IP address of the computer on which the service exists. Active Directory uses other object attributes, such as the service display name (commonly called the friendly name) to find services like Dynamic Host Configuration Protocol (DHCP).
Service Publication and SPN Processes and Interactions
This section describes the processes and interactions that are related to service publication and SPNs.
How a Service Publishes Its Service Information
Typically, a setup program for a service (or an installation option for the executable routine of the service) installs the service and creates a service account, if necessary, and the SCP. At service startup, the service itself checks to ensure that the SCP contains the correct binding information.
To create an object of any kind, the process that creates the object must have permission to create a child in the container in which the object is to be created. For example, to create the object CN=MS-SQL-SQLServer,CN=dbserver,OU=ComputersOU,DC=corp,DC=cohovineyard,DC=com, the process must have permission to create a child in the CN=dbserver,OU=ComputersOU,DC=corp,DC=cohovineyard,DC=com container. To remove an object, the process that deletes the object must have permission to delete a child from the container from which the object is to be deleted. Or, the process must have permission to delete the object itself. To update a connection point object, the process performing the operation must have permission to write to the properties of the object that needs to be updated.
These permissions to create objects might not be available to a service account or computer account during the installation of a service, but an administrator, or anyone with the necessary permissions, can perform the installation. When you install a published service, you can set the protection on any connection point object to allow updates by the service at run time. This way, the service can run with a minimally privileged account as a security precaution and still be able to maintain its connection point.
Where Services Are Published
In the domain hierarchy of Active Directory, service-related objects can be created in three places:
Computer object
Organizational Unit container
System container (or one of its children)
The following sections describe these locations in Active Directory for service-related objects.
Computer object
When a service that supports service publication is installed on a computer, the service generally (but not always) publishes its connection point object as a child object of the Computer object on which the service is installed.
The Computer object where the service is installed is a convenient and intuitive location for these objects, because when a Computer object is moved to a different location, Active Directory also moves any service objects on the Computer object to the new location. In addition, when a Computer object is deleted or when it is joined to a different domain, the service objects are also deleted or moved; therefore, there is less likelihood that a service will become an orphan.
Note
- A computer must be a domain member to have a valid Computer object in the directory.
Organizational Unit container
An Organizational Unit container is a general-purpose container that can be used to group together and organize objects, including computer objects, for administrative purposes. Organizational Unit containers can also be used to group connection point objects together for administrative purposes.
All of the object classes that are derived from the connectionPoint class are valid children of the organizationalUnit object class, from which Organizational Unit containers are derived. This means that a service connection point object can be created in any container.
System container
The System container stores operational information, which is organized by domain. This information includes the default local security policy, file link tracking, network meetings, and containers for connection points to RPC and Winsock. By default, the System container is hidden, and it provides a convenient place for storing objects that are of interest to administrators but not to users.
Services that use the Winsock RnR or RpcNs APIs to advertise themselves automatically create connection point objects in the WinsockServices and RpcServices containers*.*
Services that create connection point objects in the System container perform the following operations when they create a connection point object:
They create a subcontainer in the System container and give it a name that clearly relates it to the service.
They publish the connection point objects in the System container. For example, Microsoft NetMeeting uses the Meetings container to publish network meeting objects. When multiple products from a single vendor publish objects in this manner, the containers for each service must be created as children of a container (an object of the class container), and the container must be given a name that clearly relates to the particular vendor. The vendor-specific container must be created as a child of the System container.
Publishing with the RPC Name Service
RPC services use the RpcNs API to publish themselves in a namespace; the RpcNs APIs publish the RPC entries in Active Directory. Services create RPC bindings and publish them in the Active Directory namespace as named RPC Server entries with attributes. The attributes include the unique interface ID and a GUID that are known to clients. Clients can then search for RPC servers that offer the desired interface, import the binding, and connect to the server.
Publishing with Winsock RnR
Winsock services can use the RnR APIs to publish services and to locate those services. RnR publication occurs in two steps. The first step installs a service class that associates a GUID with a name for the service. The service class can hold service-specific configuration information. Services can then publish themselves as instances of the service class. After the services are published, clients can query Active Directory for instances of a given class, using the RnR APIs, and then select an instance to which to bind.
How a Service Registers Its SPNs
Before a client can use an SPN to authenticate an instance of a service, the SPN must be registered on the user or computer account that the service instance will use to log on. Typically, SPN registration is performed by the service installation program that installs the service.
The service installation program that installs a service instance on a host computer typically performs the following steps:
Calls the DsGetSpn function to create one or more unique SPNs for the service instance.
Calls the DsWriteAccountSpn function to register the names on the service’s logon account.
DsWriteAccountSpn registers SPNs as a property of a user or computer account object in the directory. User and Computer objects have a servicePrincipalName attribute, which is a multivalued attribute for storing all the SPNs that are associated with a user or computer account. If the service runs under a user account, the SPNs are stored in the servicePrincipalName attribute of that account. If the service runs in the Local System account, the SPNs are stored in the servicePrincipalName attribute of the account of the service’s host computer. The DsWriteAccountSpn caller must specify the distinguished name of the account object under which the SPNs are stored.
To ensure that registered SPNs are secure, the servicePrincipalName attribute cannot be written directly; it can only be written by calling DsWriteAccountSpn. The caller must have Write access to the servicePrincipalName attribute of the target account. Typically, Write access is granted by default only to domain administrators. However, there is a special case in which Active Directory allows a service running under the Local System account to register its own SPNs on the computer account of the service’s host. In this case, the SPN being written must have the form ServiceClass/Host, and Host must be the DNS name of the local computer.
DsWriteAccountSpn can also remove SPNs from an account. An operation parameter indicates whether the SPNs are to be added to the account, removed from the account, or used to completely replace all current SPNs for the account.
For more information about how a service registers its SPNs, see the “Microsoft Platform SDK” on MSDN.
Host-based services that use the simple SPN format ServiceClass/Host have the option of using the DsServerRegisterSpn function, which both creates and registers SPNs for a service instance. DsServerRegisterSpn is a helper function that calls DsGetSpn and DsWriteAccountSpn.
How a Client Application Finds a Service
Clients find service objects by querying the directory. The client can limit the scope of the query to its domain, or it can search the entire forest by using the global catalog. In either case, the client does not need information about the location of the service to perform the search.
If the connection point objects that are being searched for are direct instances of the serviceConnectionPoint class, a client application can locate published services by searching for any object where objectCategory is equal to serviceConnectionPoint and objectClass is equal to serviceConnectionPoint. The keywordsattribute contains the vendor-specific and application-specific GUID.
For more information about how a client application finds a service, see the “Microsoft Platform SDK” on MSDN.
How a Client Composes an SPN
To mutually authenticate a service, a client application composes an SPN for the service instance to which it wants to connect and then presents this SPN to the KDC for authentication. The client application can use DsMakeSpnfunction to compose an SPN. The client specifies the components of the SPN by using known information or information that is retrieved from sources other than the service itself.
The form of an SPN is as follows, where ServiceClass and Host are required and Port and ServiceName are optional:
ServiceClass/Host:Port/ServiceName
A client application can retrieve components of the SPN from sources such as a connection point object, user input, or hard-coded strings that are contained within the client application. For example, the client can read the serviceDNSName attribute of a service’s connection point object to get the Host component. The serviceDNSName attribute contains either the DNS name of the server on which the service instance is running or the DNS name of SRV records that contain the host information for service replicas. The ServiceName component, which is used only for replicable services, can be the distinguished name of the service’s connection point object, the DNS name of the domain that is served by the service, or the DNS name of SRV or MX records.
How a Client Authenticates a Service
The means by which a client authenticates a service ensures the authenticity of the service in two ways. First, because an SPN is constructed from several elements and must be unique, a rogue service has no way of publishing a valid SPN to the directory. Next, a given service can only be authenticated if that service can successfully exchange encrypted information with a KDC.
The Kerberos mechanism by which a client authenticates a service works as follows. When a service is installed, a service installer, running with administrator privileges, registers one or more unique SPNs for each service instance. The names are registered in Active Directory on the user or computer account object that the service instance will use to log on. When a client requests a connection to a service, it composes an SPN for a service instance, using known data or data that is provided by the user. The client then uses the Security Support Provider Interface (SSPI) negotiate package to present the SPN to the KDC for the client domain account. The KDC searches the forest for a user or computer account on which that SPN is registered. If the SPN is registered on more than one account, the authentication fails (which prevents a rogue service from attempting to impersonate a valid service). Otherwise, the KDC encrypts a message using the password of the account on which the SPN was registered. The KDC passes this encrypted message to the service instance. The service uses the SSPI negotiate package to decrypt the message (using the password that only the service and the KDC possess), which it passes back to the KDC. The KDC authenticates the service if the decrypted message matches the original message.
Related Information
“Microsoft Platform SDK” on MSDN for more information about SQL Server 2000 service publication (in “Active Directory Integration”)
“Microsoft Platform SDK” on MSDN for more information about how a service registers its SPNs (in “How a Service Registers its SPNs”)
“Microsoft Platform SDK” on MSDN for more information about how a client application finds a service (in “Service Publication”)
“Microsoft Platform SDK” on MSDN for more information about the use of SPNs in authentication (in “About Mutual Authentication Using Kerberos”)