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

Operation

[in] Specifies what operation DsWriteAccountSpn should perform. This parameter can have one of the following values.

Value	Meaning
DS_SPN_ADD_SPN_OP	Adds the specified SPNs to the pszAccount account.
DS_SPN_DELETE_SPN_OP	Deletes the specified SPNs from the pszAccount account.
DS_SPN_REPLACE_SPN_OP	Removes all SPNs currently registered on the pszAccount account and replaces them with those specified in rpszSpn.

pszAccount

[in] Pointer to a constant null-terminated Unicode string specifying 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 is 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 Unicode strings specifying the SPNs to be added to or removed from the pszAccount account. Use the DsGetSpn function to compose SPNs for a service.

Return Values

If the function successfully registers one or more SPNs, it returns ERROR_SUCCESS. Modification is performed permissively, so that adding a value that already exists does not return an error.

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 only allows domain administrators to register SPNs in most cases.

The 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: InstancePort

If the host specified in the SPN is the DNS or NetBIOS name of the computer on which the service is running.

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

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Ntdsapi.h.
  Library: Included as a resource in Ntdsapi.dll.
  Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

DC and Replication Management Functions, DsBind, DsBindWithCred, DsGetSpn