ImpersonateSecurityContext function (sspi.h)
The ImpersonateSecurityContext function allows a server to impersonate a client by using a token previously obtained by a call to AcceptSecurityContext (General) or QuerySecurityContextToken. This function allows the application server to act as the client, and thus all necessary access controls are enforced.
KSECDDDECLSPEC SECURITY_STATUS SEC_ENTRY ImpersonateSecurityContext(
[in] PCtxtHandle phContext
The handle of the context to impersonate. This handle must have been obtained by a call to the AcceptSecurityContext (General) function.
If the function succeeds, the function returns SEC_E_OK.
If the function fails, it returns the following error code.
|The handle passed to the function is not valid.
|The client could not be impersonated.
|This value is returned by Schannel kernel mode to indicate that this function is not supported.
The server application calls the ImpersonateSecurityContext function when it needs to impersonate the client. Before doing so, the server must have obtained a valid context handle. To obtain the context handle, the server must call AcceptSecurityContext (General) to submit the client's incoming security token to the security system. The server gets a context handle if the inbound context is validated. The function creates an impersonation token and allows the thread or process to run with the impersonation context.
When using the Schannel security support provider (SSP), the server application must pass the ASC_REQ_MUTUAL_AUTH flag when calling AcceptSecurityContext (General). This ensures that the client is asked for a client certificate during the SSL/TLS handshake. When a client certificate is received, the Schannel package verifies the client certificate and attempts to map it to a user account. When this mapping is successful, then a client user token is created and this function succeeds.
ImpersonateSecurityContext is not available with all security packages on all platforms. Typically, it is implemented only on platforms and with security packages that support impersonation. To learn whether a security package supports impersonation, call the QuerySecurityPackageInfo function.
- The requested impersonation level of the token is less than SecurityImpersonation, such as SecurityIdentification or SecurityAnonymous.
- The caller has the SeImpersonatePrivilege privilege.
- A process (or another process in the caller's logon session) created the token using explicit credentials through LogonUser or LsaLogonUser function.
- The authenticated identity is same as the caller.
Windows XP: The SeImpersonatePrivilege privilege is not supported until Windows XP with Service Pack 2 (SP2).
|Minimum supported client
|Windows XP [desktop apps only]
|Minimum supported server
|Windows Server 2003 [desktop apps only]
|sspi.h (include Security.h)