Platform SDK: Access Control |
The DuplicateTokenEx function creates a new access token that duplicates an existing token. This function can create either a primary token or an impersonation token.
BOOL DuplicateTokenEx( HANDLE hExistingToken, // handle to token to duplicate DWORD dwDesiredAccess, // access rights of new token LPSECURITY_ATTRIBUTES lpTokenAttributes, // attributes SECURITY_IMPERSONATION_LEVEL ImpersonationLevel, // level TOKEN_TYPE TokenType, // primary or impersonation token PHANDLE phNewToken // handle to duplicated token );
For a list of access rights for access tokens, see Access Rights for Access-Token Objects.
Value | Meaning |
---|---|
TokenPrimary | The new token is a primary token that you can use in the CreateProcessAsUser function. |
TokenImpersonation | The new token is an impersonation token. |
If the function succeeds, the return value is a nonzero value.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
The DuplicateTokenEx function allows you to create a primary token that you can use in the CreateProcessAsUser function. This allows a server application that is impersonating a client to create a process that has the security context of the client. Note that the DuplicateToken function can create only impersonation tokens, which are not valid for CreateProcessAsUser.
The following is a typical scenario for using DuplicateTokenEx to create a primary token. A server application creates a thread that calls one of the impersonation functions, such as ImpersonateNamedPipeClient, to impersonate a client. The impersonating thread then calls the OpenThreadToken function to get its own token, which is an impersonation token that has the security context of the client. The thread specifies this impersonation token in a call to DuplicateTokenEx, specifying the TokenPrimary flag. DuplicateTokenEx creates a primary token that has the security context of the client.
When you have finished using the new token, call the CloseHandle function to close the token handle.
Windows NT/2000: Requires Windows NT 4.0 or later.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Advapi32.lib.
Access Control Overview, Access Control Functions, CloseHandle, CreateProcessAsUser, DdeImpersonateClient, DuplicateToken, ImpersonateNamedPipeClient, OpenThreadToken, RevertToSelf, RpcImpersonateClient, SECURITY_ATTRIBUTES, SECURITY_IMPERSONATION_LEVEL