DsBindWithSpnExA function (ntdsapi.h)

Article
02/09/2023

The DsBindWithSpnEx function binds to a domain controller using the specified credentials and a specific service principal name (SPN) for mutual authentication. This function is similar to the DsBindWithSpn function except this function allows more binding options with the BindFlags parameter.

This function is provided 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 computer-specific, and it is unlikely that the SPN you provide will match the server that DsBind finds for you. Providing a NULLServicePrincipalName argument results in behavior that is identical to DsBindWithCred.

Syntax

NTDSAPI_POSTXP DWORD DsBindWithSpnExA(
  [in, optional] LPCSTR                   DomainControllerName,
  [in, optional] LPCSTR                   DnsDomainName,
  [in, optional] RPC_AUTH_IDENTITY_HANDLE AuthIdentity,
  [in, optional] LPCSTR                   ServicePrincipalName,
  [in, optional] DWORD                    BindFlags,
  [out]          HANDLE                   *phDS
);

Parameters

[in, optional] DomainControllerName

Pointer to a null-terminated string that contains the fully qualified DNS name of the domain to bind. For more information, see the DomainControllerName description in the DsBind topic.

[in, optional] DnsDomainName

Pointer to a null-terminated string that contains the fully qualified DNS name of the domain to bind. For more information, see the DnsDomainName description in the DsBind topic.

[in, optional] AuthIdentity

Contains an RPC_AUTH_IDENTITY_HANDLE value that represents the credentials to be used for the bind. The

DsMakePasswordCredentials function is used to obtain this value. If this parameter is NULL, the credentials of the calling thread are used.

DsUnBind must be called before freeing this handle with the DsFreePasswordCredentials function.

[in, optional] ServicePrincipalName

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.

[in, optional] BindFlags

Contains a set of flags that define the behavior of this function. This parameter can contain zero or a combination of the values listed in the following list.

NTDSAPI_BIND_ALLOW_DELEGATION (1)

Causes the bind to use the delegate impersonation level. This allows operations that require delegation, such as DsAddSidHistory, to succeed. Specifying this flag also causes DsBindWithSpnEx to operate like DsBindWithSpn.

If this flag is not specified, the bind will use the impersonate impersonation level. For more information, see Impersonation Levels.

Most operations do not require the delegate impersonation level, so this flag should only be specified if absolutely required. Binding to a rogue server with the delegate impersonation level will allow the rogue server to connect to a non-rogue server with your credentials and perform unintended operations.

NTDSAPI_BIND_FIND_BINDING (2)

Reserved.

NTDSAPI_BIND_FORCE_KERBEROS (4)

Active Directory Lightweight Directory Services: If this flag is specified, DsBindWithSpnEx forces Kerberos authentication to be used. If Kerberos authentication cannot be established, DsBindWithSpnEx will not attempt to authenticate with any other method.

[out] phDS

Address of a HANDLE value that receives the binding handle. To close this handle, pass it to the DsUnBind function.

Return value

Returns ERROR_SUCCESS if successful or a Windows or RPC error code otherwise. The following list lists common error codes.

Remarks

Note

The ntdsapi.h header defines DsBindWithSpnEx as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	ntdsapi.h
Library	Ntdsapi.lib
DLL	Ntdsapi.dll