RpcGetAuthorizationContextForClient function (rpcasync.h)
The RpcGetAuthorizationContextForClient function returns the Authz context for an RPC client that can be used with Authz functions for high-performance authentication. Supported for ncalrpc and ncacn_* protocol sequences only.
Syntax
RPC_STATUS RpcGetAuthorizationContextForClient(
[in, optional] RPC_BINDING_HANDLE ClientBinding,
[in] BOOL ImpersonateOnReturn,
[in] PVOID Reserved1,
[in, optional] PLARGE_INTEGER pExpirationTime,
[in] LUID Reserved2,
[in] DWORD Reserved3,
[in] PVOID Reserved4,
[out] PVOID *pAuthzClientContext
);
Parameters
[in, optional] ClientBinding
Binding handle on the server that represents a binding to a client. The server impersonates the client indicated by this handle. If a value of zero is specified, the server impersonates the client that is being served by this server thread.
[in] ImpersonateOnReturn
Directs the function to impersonate the client on return, and then return an AUTHZ_CLIENT_CONTEXT_HANDLE structure. Set this parameter to nonzero to impersonate the client. See Remarks.
[in] Reserved1
Reserved. Must be null.
[in, optional] pExpirationTime
Pointer to the expiration date and time of the token. If no value is passed, the token never expires. Expiration time is not currently enforced.
[in] Reserved2
Reserved. Must be a LUID structure with each member set to zero.
[in] Reserved3
Reserved. Must be zero.
[in] Reserved4
Reserved. Must be null.
[out] pAuthzClientContext
Pointer to an AUTHZ_CLIENT_CONTEXT_HANDLE structure that can be passed directly to Authz functions. If the function fails, the content of this parameter is undefined.
Return value
| Value | Meaning |
|---|---|
|
The call succeeded. |
|
A reserved parameter is different than its prescribed value. |
|
The RPC client has not been authenticated successfully. |
Failure returns an RPC_S_* error code, or a Windows error code. Extended error information is available through standard RPC or Windows error code retrieval mechanisms. For a list of valid error codes, see RPC Return Values.
Remarks
The RpcGetAuthorizationContextForClient function can be called in the same context as the RpcImpersonateClient function. All functions that impersonate check to determine whether the caller has the SeImpersonatePrivilege privilege. If the caller has the SeImpersonatePrivilege, or if the authenticated identity is the same as the caller, the requested impersonation is allowed. Otherwise, the impersonation succeeds at Identify level only.
Note The SeImpersonatePrivilege privilege is not supported until Windows XP with Service Pack 2 (SP2).
The RpcGetAuthorizationContextForClient function is supported for ncalrpc and ncacn_* protocol sequences only, and is not supported on named pipes that only implement transport security.
The RpcGetAuthorizationContextForClient function is thread-safe, and can be called from multiple threads. The context returned in pAuthzClientContext is independent of the function call, and can be used subsequent to its completion. The caller is responsible for freeing the context with a call to the RpcFreeAuthorizationContext function.
Performance improvement observed by using the RpcGetAuthorizationContextForClient function, when compared to previous methods of impersonation or access check or revert to self, depend on the following factors:
- How many times the function is called for a given client identity.
- Protocol sequence and identity tracking in effect for the function call.
Calls over ncalrpc with static identity tracking execute the RpcGetAuthorizationContextForClient function faster than calls over ncalrpc with dynamic identity tracking. Calls over ncacn_* execute with approximately the same speed for a given protocol sequence, regardless of whether identity tracking is static or dynamic.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | rpcasync.h (include Rpc.h) |
| Library | Rpcrt4.lib |
| DLL | Rpcrt4.dll |