DsWriteAccountSpn

The DsWriteAccountSpn function writes an array of service principal names (SPNs) to the servicePrincipalName attribute of a specified user or computer account object in Active Directory. The function can either register or unregister the SPNs.

DWORD DsWriteAccountSpn(
  HANDLE hDS,
  DS_SPN_WRITE_OP Operation,
  LPCTSTR pszAccount,
  DWORD cSpn,
  LPCTSTR* rpszSpn
);

Parameters

hDS

[in] Bind handle to the directory service. This handle is returned by a call to the DsBind or DsBindWithCred function.

Operation

[in] Contains one of the DS_SPN_WRITE_OP values that specifies the operation that DsWriteAccountSpn will perform.

pszAccount

[in] Pointer to a constant null-terminated string that specifies the distinguished name of a user or computer object in Active Directory. The caller must have write access to the servicePrincipalName property of this object.

cSpn

[in] Specifies the number of SPNs in rpszSpn. If this value is zero, and Operation contains DS_SPN_REPLACE_SPN_OP, the function removes all values from the servicePrincipalName attribute of the specified account.

rpszSpn

[in] Pointer to an array of constant null-terminated strings that specify the SPNs to be added to or removed from the account identified by the pszAccount parameter. The DsGetSpn function is used to compose SPNs for a service.

Return Values

Remarks

The DsWriteAccountSpn function registers the SPNs for one or more instances of a service. SPNs are used by clients, in conjunction with a trusted authentication service, to authenticate the service. To protect against security attacks where an application or service fraudulently registers an SPN that identifies some other service, the default DACL on user and computer accounts allows only domain administrators to register SPNs in most cases.

One exception to this rule is that a service running under the LocalSystem account can call DsWriteAccountSpn to register a simple SPN of the form "ServiceClass/Host:Port" if the host specified in the SPN is the DNS or NetBIOS name of the computer on which the service is running.

Another exception is that the default DACL on user and computer accounts allows callers to register SPNs on themselves, subject to certain constraints. For example, a computer account can have SPNs relative to its computername, of the form "host/<computername>". Because the computername is contained in the SPN, the SPN is allowable.

None of the rules above apply if the DSA is configured to allow any SPN to be written. This reduces security, however, so it is not recommended.

SPNs passed to DsWriteAccountSpn are actually added to the Service-Principal-Name attribute of the computer object in pszAccount. This call is made using RPC to the domain controller where the account object is stored so it can securely enforce policy on what SPNs are allowed on the account. Using LDAP to write directly to the SPN property is not allowed; all writes must come through this RPC call. Reads using LDAP are permitted.

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000/XP.
Header: Declared in Ntdsapi.h.
Library: Use Ntdsapi.lib.

See Also

DsBind, DsBindWithCred, DS_SPN_WRITE_OP, DsGetSpn, Domain Controller and Replication Management Functions