DsBindWithSpn

The DsBindWithSpn function enables the client to specify the service principal name (SPN) to use for mutual authentication against the destination server. This function is provided for those situations where complete control is required over mutual authentication. Do not use this function if you expect DsBind to find a server for you, because SPNs are machine-specific, and it is unlikely that the SPN you provide will match the server that DsBind finds for you. Providing a NULL ServicePrincipalName argument results in behavior that is identical to DsBindWithCred.

DWORD DsBindWithSpn(
  LPCTSTR DomainControllerName,
  LPCTSTR DnsDomainName,
  RPC_AUTH_IDENTITY_HANDLE AuthIdentity,
  LPCTSTR ServicePrincipalName,
  HANDLE* phDS
);

Parameters

DomainControllerName

[in, optional] Pointer to a null-terminated string that specifies the address of the domain controller. If this parameter is NULL, DsBindWithSpn will attempt to find and use a domain controller in the domain specified by DnsDomainName.

If this parameter is NULL and DnsDomainName is NULL, DsBindWithSpn attempts to find and use a global catalog server in the forest of the local computer.

DnsDomainName

[in, optional] Pointer to a null-terminated string that specifies the dotted DNS name for a domain. If this parameter is NULL and DomainController is NULL, DsBindWithSpn attempts to find and use a global catalog server in the forest of the local computer.

If this parameter is NULL and DomainController is not NULL, DsBindWithSpn uses the domain name of the primary domain of the local computer.

AuthIdentity

[in, optional] Handle to the credentials used to start the RPC session. Use the DsMakePasswordCredentials function to create a structure suitable for AuthIdentity.

Passing NULL in AuthIdentity is equivalent to a call to DsBind.

ServicePrincipalName

[in, optional] Pointer to a null-terminated string that specifies the Service Principal Name to assign to the client. Passing NULL in ServicePrincipalName is equivalent to a call to the DsBindWithCred function.

phDS

[out] Address of a HANDLE value that receives the bind handle. To close this handle, call DsUnBind.

Return Values

When the function succeeds, NO_ERROR is returned.

If the function fails, the return value is either an RPC error code or one of the following.

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, DsUnBind, Domain Controller and Replication Management Functions