Edit

Share via

CAccessToken Class

  • Article

This class is a wrapper for an access token.

Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

Syntax

class CAccessToken

Members

Public Constructors

Name Description
CAccessToken::~CAccessToken The destructor.

Public Methods

Name Description
CAccessToken::Attach Call this method to take ownership of the given access token handle.
CAccessToken::CheckTokenMembership Call this method to determine if a specified SID is enabled in the CAccessToken object.
CAccessToken::CreateImpersonationToken Call this method to create a new impersonation access token.
CAccessToken::CreatePrimaryToken Call this method to create a new primary token.
CAccessToken::CreateProcessAsUser Call this method to create a new process running in the security context of the user represented by the CAccessToken object.
CAccessToken::CreateRestrictedToken Call this method to create a new, restricted CAccessToken object.
CAccessToken::Detach Call this method to revoke ownership of the access token.
CAccessToken::DisablePrivilege Call this method to disable a privilege in the CAccessToken object.
CAccessToken::DisablePrivileges Call this method to disable one or more privileges in the CAccessToken object.
CAccessToken::EnablePrivilege Call this method to enable a privilege in the CAccessToken object.
CAccessToken::EnablePrivileges Call this method to enable one or more privileges in the CAccessToken object.
CAccessToken::GetDefaultDacl Call this method to return the CAccessToken object's default DACL.
CAccessToken::GetEffectiveToken Call this method to get the CAccessToken object equal to the access token in effect for the current thread.
CAccessToken::GetGroups Call this method to return the CAccessToken object's token groups.
CAccessToken::GetHandle Call this method to retrieve a handle to the access token.
CAccessToken::GetImpersonationLevel Call this method to get the impersonation level from the access token.
CAccessToken::GetLogonSessionId Call this method to get the Logon Session ID associated with the CAccessToken object.
CAccessToken::GetLogonSid Call this method to get the Logon SID associated with the CAccessToken object.
CAccessToken::GetOwner Call this method to get the owner associated with the CAccessToken object.
CAccessToken::GetPrimaryGroup Call this method to get the primary group associated with the CAccessToken object.
CAccessToken::GetPrivileges Call this method to get the privileges associated with the CAccessToken object.
CAccessToken::GetProcessToken Call this method to initialize the CAccessToken with the access token from the given process.
CAccessToken::GetProfile Call this method to get the handle pointing to the user profile associated with the CAccessToken object.
CAccessToken::GetSource Call this method to get the source of the CAccessToken object.
CAccessToken::GetStatistics Call this method to get information associated with the CAccessToken object.
CAccessToken::GetTerminalServicesSessionId Call this method to get the Terminal Services Session ID associated with the CAccessToken object.
CAccessToken::GetThreadToken Call this method to initialize the CAccessToken with the token from the given thread.
CAccessToken::GetTokenId Call this method to get the Token ID associated with the CAccessToken object.
CAccessToken::GetType Call this method to get the token type of the CAccessToken object.
CAccessToken::GetUser Call this method to identify the user associated with the CAccessToken object.
CAccessToken::HKeyCurrentUser Call this method to get the handle pointing to the user profile associated with the CAccessToken object.
CAccessToken::Impersonate Call this method to assign an impersonation CAccessToken to a thread.
CAccessToken::ImpersonateLoggedOnUser Call this method to allow the calling thread to impersonate the security context of a logged-on user.
CAccessToken::IsTokenRestricted Call this method to test if the CAccessToken object contains a list of restricted SIDs.
CAccessToken::LoadUserProfile Call this method to load the user profile associated with the CAccessToken object.
CAccessToken::LogonUser Call this method to create a logon session for the user associated with the given credentials.
CAccessToken::OpenCOMClientToken Call this method from within a COM server handling a call from a client to initialize the CAccessToken with the access token from the COM client.
CAccessToken::OpenNamedPipeClientToken Call this method from within a server taking requests over a named pipe to initialize the CAccessToken with the access token from the client.
CAccessToken::OpenRPCClientToken Call this method from within a server handling a call from an RPC client to initialize the CAccessToken with the access token from the client.
CAccessToken::OpenThreadToken Call this method to set the impersonation level and then initialize the CAccessToken with the token from the given thread.
CAccessToken::PrivilegeCheck Call this method to determine whether a specified set of privileges are enabled in the CAccessToken object.
CAccessToken::Revert Call this method to stop a thread that is using an impersonation token.
CAccessToken::SetDefaultDacl Call this method to set the default DACL of the CAccessToken object.
CAccessToken::SetOwner Call this method to set the owner of the CAccessToken object.
CAccessToken::SetPrimaryGroup Call this method to set the primary group of the CAccessToken object.

Remarks

An access token is an object that describes the security context of a process or thread and is allocated to each user logged onto a Windows system.

For an introduction to the access control model in Windows, see Access Control in the Windows SDK.

Requirements

Header: atlsecurity.h

CAccessToken::Attach

Call this method to take ownership of the given access token handle.

void Attach(HANDLE hToken) throw();

Parameters

hToken
A handle to the access token.

Remarks

In debug builds, an assertion error will occur if the CAccessToken object already has ownership of an access token.

CAccessToken::~CAccessToken

The destructor.

virtual ~CAccessToken() throw();

Remarks

Frees all allocated resources.

CAccessToken::CheckTokenMembership

Call this method to determine if a specified SID is enabled in the CAccessToken object.

bool CheckTokenMembership(
    const CSid& rSid,
    bool* pbIsMember) const throw(...);

Parameters

rSid
Reference to a CSid Class object.

pbIsMember
Pointer to a variable that receives the results of the check.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

The CheckTokenMembership method checks for the presence of the SID in the user and group SIDs of the access token. If the SID is present and has the SE_GROUP_ENABLED attribute, pbIsMember is set to TRUE; otherwise, it is set to FALSE.

In debug builds, an assertion error will occur if pbIsMember is not a valid pointer.

Note

The CAccessToken object must be an impersonation token and not a primary token.

CAccessToken::CreateImpersonationToken

Call this method to create an impersonation access token.

bool CreateImpersonationToken(
    CAccessToken* pImp,
    SECURITY_IMPERSONATION_LEVEL sil = SecurityImpersonation) const throw(...);

Parameters

pImp
Pointer to the new CAccessToken object.

sil
Specifies a SECURITY_IMPERSONATION_LEVEL enumerated type that supplies the impersonation level of the new token.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

CreateImpersonationToken calls DuplicateToken to create a new impersonation token.

CAccessToken::CreatePrimaryToken

Call this method to create a new primary token.

bool CreatePrimaryToken(
    CAccessToken* pPri,
    DWORD dwDesiredAccess = MAXIMUM_ALLOWED,
    const CSecurityAttributes* pTokenAttributes = NULL) const throw(...);

Parameters

pPri
Pointer to the new CAccessToken object.

dwDesiredAccess
Specifies the requested access rights for the new token. The default, MAXIMUM_ALLOWED, requests all access rights that are valid for the caller. See Access Rights and Access Masks for more on access rights.

pTokenAttributes
Pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new token and determines whether child processes can inherit the token. If pTokenAttributes is NULL, the token gets a default security descriptor and the handle cannot be inherited.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

CreatePrimaryToken calls DuplicateTokenEx to create a new primary token.

CAccessToken::CreateProcessAsUser

Call this method to create a new process running in the security context of the user represented by the CAccessToken object.

bool CreateProcessAsUser(
    LPCTSTR pApplicationName,
    LPTSTR pCommandLine,
    LPPROCESS_INFORMATION pProcessInformation,
    LPSTARTUPINFO pStartupInfo,
    DWORD dwCreationFlags = NORMAL_PRIORITY_CLASS,
    bool bLoadProfile = false,
    const CSecurityAttributes* pProcessAttributes = NULL,
    const CSecurityAttributes* pThreadAttributes = NULL,
    bool bInherit = false,
    LPCTSTR pCurrentDirectory = NULL) throw();

Parameters

pApplicationName
Pointer to a null-terminated string that specifies the module to execute. This parameter may not be NULL.

pCommandLine
Pointer to a null-terminated string that specifies the command line to execute.

pProcessInformation
Pointer to a PROCESS_INFORMATION structure that receives identification information about the new process.

pStartupInfo
Pointer to a STARTUPINFO structure that specifies how the main window for the new process should appear.

dwCreationFlags
Specifies additional flags that control the priority class and the creation of the process. See the Win32 function CreateProcessAsUser for a list of flags.

bLoadProfile
If TRUE, the user's profile is loaded with LoadUserProfile.

pProcessAttributes
Pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new process and determines whether child processes can inherit the returned handle. If pProcessAttributes is NULL, the process gets a default security descriptor and the handle cannot be inherited.

pThreadAttributes
Pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new thread and determines whether child processes can inherit the returned handle. If pThreadAttributes is NULL, the thread gets a default security descriptor and the handle cannot be inherited.

bInherit
Indicates whether the new process inherits handles from the calling process. If TRUE, each inheritable open handle in the calling process is inherited by the new process. Inherited handles have the same value and access privileges as the original handles.

pCurrentDirectory
Pointer to a null-terminated string that specifies the current drive and directory for the new process. The string must be a full path that includes a drive letter. If this parameter is NULL, the new process will have the same current drive and directory as the calling process.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

CreateProcessAsUser uses the CreateProcessAsUser Win32 function to create a new process that runs in the security context of the user represented by the CAccessToken object. See the description of the CreateProcessAsUser function for a full discussion of the parameters required.

For this method to succeed, the CAccessToken object must hold AssignPrimaryToken (unless it is a restricted token) and IncreaseQuota privileges.

CAccessToken::CreateRestrictedToken

Call this method to create a new, restricted CAccessToken object.

bool CreateRestrictedToken(
    CAccessToken* pRestrictedToken,
    const CTokenGroups& SidsToDisable,
    const CTokenGroups& SidsToRestrict,
    const CTokenPrivileges& PrivilegesToDelete = CTokenPrivileges()) const throw(...);

Parameters

pRestrictedToken
The new, restricted CAccessToken object.

SidsToDisable
A CTokenGroups object that specifies the deny-only SIDs.

SidsToRestrict
A CTokenGroups object that specifies the restricting SIDs.

PrivilegesToDelete
A CTokenPrivileges object that specifies the privileges to delete in the restricted token. The default creates an empty object.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

CreateRestrictedToken uses the CreateRestrictedToken Win32 function to create a new CAccessToken object, with restrictions.

Important

When using CreateRestrictedToken, ensure the following: the existing token is valid (and not entered by the user) and SidsToDisable and PrivilegesToDelete are both valid (and not entered by the user). If the method returns FALSE, deny functionality.

CAccessToken::Detach

Call this method to revoke ownership of the access token.

HANDLE Detach() throw();

Return Value

Returns the handle to the CAccessToken which has been detached.

Remarks

This method revokes the CAccessToken's ownership of the access token.

CAccessToken::DisablePrivilege

Call this method to disable a privilege in the CAccessToken object.

bool DisablePrivilege(
    LPCTSTR pszPrivilege,
    CTokenPrivileges* pPreviousState = NULL) throw(...);

Parameters

pszPrivilege
Pointer to a string containing the privilege to disable in the CAccessToken object.

pPreviousState
Pointer to a CTokenPrivileges object which will contain the previous state of the privileges.

Return Value

Returns TRUE on success, FALSE on failure.

CAccessToken::DisablePrivileges

Call this method to disable one or more privileges in the CAccessToken object.

bool DisablePrivileges(
    const CAtlArray<LPCTSTR>& rPrivileges,
    CTokenPrivileges* pPreviousState = NULL) throw(...);

Parameters

rPrivileges
Pointer to an array of strings containing the privileges to disable in the CAccessToken object.

pPreviousState
Pointer to a CTokenPrivileges object which will contain the previous state of the privileges.

Return Value

Returns TRUE on success, FALSE on failure.

CAccessToken::EnablePrivilege

Call this method to enable a privilege in the CAccessToken object.

bool EnablePrivilege(
    LPCTSTR pszPrivilege,
    CTokenPrivileges* pPreviousState = NULL) throw(...);

Parameters

pszPrivilege
Pointer to a string containing the privilege to enable in the CAccessToken object.

pPreviousState
Pointer to a CTokenPrivileges object which will contain the previous state of the privileges.

Return Value

Returns TRUE on success, FALSE on failure.

CAccessToken::EnablePrivileges

Call this method to enable one or more privileges in the CAccessToken object.

bool EnablePrivileges(
    const CAtlArray<LPCTSTR>& rPrivileges,
    CTokenPrivileges* pPreviousState = NULL) throw(...);

Parameters

rPrivileges
Pointer to an array of strings containing the privileges to enable in the CAccessToken object.

pPreviousState
Pointer to a CTokenPrivileges object which will contain the previous state of the privileges.

Return Value

Returns TRUE on success, FALSE on failure.

CAccessToken::GetDefaultDacl

Call this method to return the CAccessToken object's default DACL.

bool GetDefaultDacl(CDacl* pDacl) const throw(...);

Parameters

pDacl
Pointer to the CDacl Class object which will receive the CAccessToken object's default DACL.

Return Value

Returns TRUE if the default DACL has been recovered, FALSE otherwise.

CAccessToken::GetEffectiveToken

Call this method to get the CAccessToken object equal to the access token in effect for the current thread.

bool GetEffectiveToken(DWORD dwDesiredAccess) throw();

Parameters

dwDesiredAccess
Specifies an access mask that specifies the requested types of access to the access token. These requested access types are compared with the token's DACL to determine which accesses are granted or denied.

Return Value

Returns TRUE on success, FALSE on failure.

CAccessToken::GetGroups

Call this method to return the CAccessToken object's token groups.

bool GetGroups(CTokenGroups* pGroups) const throw(...);

Parameters

pGroups
Pointer to the CTokenGroups Class object which will receive the group information.

Return Value

Returns TRUE on success, FALSE on failure.

CAccessToken::GetHandle

Call this method to retrieve a handle to the access token.

HANDLE GetHandle() const throw();

Return Value

Returns a handle to the CAccessToken object's access token.

CAccessToken::GetImpersonationLevel

Call this method to get the impersonation level from the access token.

bool GetImpersonationLevel(
    SECURITY_IMPERSONATION_LEVEL* pImpersonationLevel) const throw(...);

Parameters

pImpersonationLevel
Pointer to a SECURITY_IMPERSONATION_LEVEL enumeration type which will receive the impersonation level information.

Return Value

Returns TRUE on success, FALSE on failure.

CAccessToken::GetLogonSessionId

Call this method to get the Logon Session ID associated with the CAccessToken object.

bool GetLogonSessionId(LUID* pluid) const throw(...);

Parameters

pluid
Pointer to a LUID which will receive the Logon Session ID.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

In debug builds, an assertion error will occur if pluid is an invalid value.

CAccessToken::GetLogonSid

Call this method to get the Logon SID associated with the CAccessToken object.

bool GetLogonSid(CSid* pSid) const throw(...);

Parameters

pSid
Pointer to a CSid Class object.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

In debug builds, an assertion error will occur if pSid is an invalid value.

CAccessToken::GetOwner

Call this method to get the owner associated with the CAccessToken object.

bool GetOwner(CSid* pSid) const throw(...);

Parameters

pSid
Pointer to a CSid Class object.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

The owner is set by default on any objects created while this access token is in effect.

CAccessToken::GetPrimaryGroup

Call this method to get the primary group associated with the CAccessToken object.

bool GetPrimaryGroup(CSid* pSid) const throw(...);

Parameters

pSid
Pointer to a CSid Class object.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

The group is set by default on any objects created while this access token is in effect.

CAccessToken::GetPrivileges

Call this method to get the privileges associated with the CAccessToken object.

bool GetPrivileges(CTokenPrivileges* pPrivileges) const throw(...);

Parameters

pPrivileges
Pointer to a CTokenPrivileges Class object which will receive the privileges.

Return Value

Returns TRUE on success, FALSE on failure.

CAccessToken::GetProcessToken

Call this method to initialize the CAccessToken with the access token from the given process.

bool GetProcessToken(DWORD dwDesiredAccess, HANDLE hProcess = NULL) throw();

Parameters

dwDesiredAccess
Specifies an access mask that specifies the requested types of access to the access token. These requested access types are compared with the token's DACL to determine which accesses are granted or denied.

hProcess
Handle to the process whose access token is opened. If the default value of NULL is used, the current process is used.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

Calls the OpenProcessToken Win32 function.

CAccessToken::GetProfile

Call this method to get the handle pointing to the user profile associated with the CAccessToken object.

HANDLE GetProfile() const throw();

Return Value

Returns a handle pointing to the user profile, or NULL if no profile exists.

CAccessToken::GetSource

Call this method to get the source of the CAccessToken object.

bool GetSource(TOKEN_SOURCE* pSource) const throw(...);

Parameters

pSource
Pointer to a TOKEN_SOURCE structure.

Return Value

Returns TRUE on success, FALSE on failure.

CAccessToken::GetStatistics

Call this method to get information associated with the CAccessToken object.

bool GetStatistics(TOKEN_STATISTICS* pStatistics) const throw(...);

Parameters

pStatistics
Pointer to a TOKEN_STATISTICS structure.

Return Value

Returns TRUE on success, FALSE on failure.

CAccessToken::GetTerminalServicesSessionId

Call this method to get the Terminal Services Session ID associated with the CAccessToken object.

bool GetTerminalServicesSessionId(DWORD* pdwSessionId) const throw(...);

Parameters

pdwSessionId
The Terminal Services Session ID.

Return Value

Returns TRUE on success, FALSE on failure.

CAccessToken::GetThreadToken

Call this method to initialize the CAccessToken with the token from the given thread.

bool GetThreadToken(
    DWORD dwDesiredAccess,
    HANDLE hThread = NULL,
    bool bOpenAsSelf = true) throw();

Parameters

dwDesiredAccess
Specifies an access mask that specifies the requested types of access to the access token. These requested access types are compared with the token's DACL to determine which accesses are granted or denied.

hThread
Handle to the thread whose access token is opened.

bOpenAsSelf
Indicates whether the access check is to be made against the security context of the thread calling the GetThreadToken method or against the security context of the process for the calling thread.

If this parameter is FALSE, the access check is performed using the security context for the calling thread. If the thread is impersonating a client, this security context can be that of a client process. If this parameter is TRUE, the access check is made using the security context of the process for the calling thread.

Return Value

Returns TRUE on success, FALSE on failure.

CAccessToken::GetTokenId

Call this method to get the Token ID associated with the CAccessToken object.

bool GetTokenId(LUID* pluid) const throw(...);

Parameters

pluid
Pointer to a LUID which will receive the Token ID.

Return Value

Returns TRUE on success, FALSE on failure.

CAccessToken::GetType

Call this method to get the token type of the CAccessToken object.

bool GetType(TOKEN_TYPE* pType) const throw(...);

Parameters

pType
Address of the TOKEN_TYPE variable that, on success, receives the type of the token.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

The TOKEN_TYPE enumeration type contains values that differentiate between a primary token and an impersonation token.

CAccessToken::GetUser

Call this method to identify the user associated with the CAccessToken object.

bool GetUser(CSid* pSid) const throw(...);

Parameters

pSid
Pointer to a CSid Class object.

Return Value

Returns TRUE on success, FALSE on failure.

CAccessToken::HKeyCurrentUser

Call this method to get the handle pointing to the user profile associated with the CAccessToken object.

HKEY HKeyCurrentUser() const throw();

Return Value

Returns a handle pointing to the user profile, or NULL if no profile exists.

CAccessToken::Impersonate

Call this method to assign an impersonation CAccessToken to a thread.

bool Impersonate(HANDLE hThread = NULL) const throw(...);

Parameters

hThread
Handle to the thread to assign the impersonation token to. This handle must have been opened with TOKEN_IMPERSONATE access rights. If hThread is NULL, the method causes the thread to stop using an impersonation token.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

In debug builds, an assertion error will occur if CAccessToken does not have a valid pointer to a token.

The CAutoRevertImpersonation class can be used to automatically revert impersonated access tokens.

CAccessToken::ImpersonateLoggedOnUser

Call this method to allow the calling thread to impersonate the security context of a logged-on user.

bool ImpersonateLoggedOnUser() const throw(...);

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

Important

If a call to an impersonation function fails for any reason, the client is not impersonated and the client request is made in the security context of the process from which the call was made. If the process is running as a highly privileged account, or as a member of an administrative group, the user might be able to perform actions he or she would otherwise be disallowed. Therefore, the return value for this function should always be confirmed.

CAccessToken::IsTokenRestricted

Call this method to test if the CAccessToken object contains a list of restricted SIDs.

bool IsTokenRestricted() const throw();

Return Value

Returns TRUE if the object contains a list of restricting SIDs, FALSE if there are no restricting SIDs or if the method fails.

CAccessToken::LoadUserProfile

Call this method to load the user profile associated with the CAccessToken object.

bool LoadUserProfile() throw(...);

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

In debug builds, an assertion error will occur if the CAccessToken does not contain a valid token, or if a user profile already exists.

CAccessToken::LogonUser

Call this method to create a logon session for the user associated with the given credentials.

bool LogonUser(
    LPCTSTR pszUserName,
    LPCTSTR pszDomain,
    LPCTSTR pszPassword,
    DWORD dwLogonType = LOGON32_LOGON_INTERACTIVE,
    DWORD dwLogonProvider = LOGON32_PROVIDER_DEFAULT) throw();

Parameters

pszUserName
Pointer to a null-terminated string that specifies the user name. This is the name of the user account to log on to.

pszDomain
Pointer to a null-terminated string that specifies the name of the domain or server whose account database contains the pszUserName account.

pszPassword
Pointer to a null-terminated string that specifies the clear-text password for the user account specified by pszUserName.

dwLogonType
Specifies the type of logon operation to perform. See LogonUser for more details.

dwLogonProvider
Specifies the logon provider. See LogonUser for more details.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

The access token resulting from the logon will be associated with the CAccessToken. For this method to succeed, the CAccessToken object must hold SE_TCB_NAME privileges, identifying the holder as part of the trusted computer base. See LogonUser for more information regarding the privileges required.

CAccessToken::OpenCOMClientToken

Call this method from within a COM server handling a call from a client to initialize the CAccessToken with the access token from the COM client.

bool OpenCOMClientToken(
    DWORD dwDesiredAccess,
    bool bImpersonate = false,
    bool bOpenAsSelf = true) throw(...);

Parameters

dwDesiredAccess
Specifies an access mask that specifies the requested types of access to the access token. These requested access types are compared with the token's DACL to determine which accesses are granted or denied.

bImpersonate
If TRUE, the current thread will impersonate the calling COM client if this call completes successfully. If FALSE, the access token will be opened, but the thread will not have an impersonation token when this call completes.

bOpenAsSelf
Indicates whether the access check is to be made against the security context of the thread calling the GetThreadToken method or against the security context of the process for the calling thread.

If this parameter is FALSE, the access check is performed using the security context for the calling thread. If the thread is impersonating a client, this security context can be that of a client process. If this parameter is TRUE, the access check is made using the security context of the process for the calling thread.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

The CAutoRevertImpersonation Class can be used to automatically revert impersonated access tokens created by setting the bImpersonate flag to TRUE.

CAccessToken::OpenNamedPipeClientToken

Call this method from within a server taking requests over a named pipe to initialize the CAccessToken with the access token from the client.

bool OpenNamedPipeClientToken(
    HANDLE hPipe,
    DWORD dwDesiredAccess,
    bool bImpersonate = false,
    bool bOpenAsSelf = true) throw(...);

Parameters

hPipe
Handle to a named pipe.

dwDesiredAccess
Specifies an access mask that specifies the requested types of access to the access token. These requested access types are compared with the token's DACL to determine which accesses are granted or denied.

bImpersonate
If TRUE, the current thread will impersonate the calling pipe client if this call completes successfully. If FALSE, the access token will be opened, but the thread will not have an impersonation token when this call completes.

bOpenAsSelf
Indicates whether the access check is to be made against the security context of the thread calling the GetThreadToken method or against the security context of the process for the calling thread.

If this parameter is FALSE, the access check is performed using the security context for the calling thread. If the thread is impersonating a client, this security context can be that of a client process. If this parameter is TRUE, the access check is made using the security context of the process for the calling thread.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

The CAutoRevertImpersonation Class can be used to automatically revert impersonated access tokens created by setting the bImpersonate flag to TRUE.

CAccessToken::OpenRPCClientToken

Call this method from within a server handling a call from an RPC client to initialize the CAccessToken with the access token from the client.

bool OpenRPCClientToken(
    RPC_BINDING_HANDLE BindingHandle,
    DWORD dwDesiredAccess,
    bool bImpersonate = false,
    bool bOpenAsSelf = true) throw(...);

Parameters

BindingHandle
Binding handle on the server that represents a binding to a client.

dwDesiredAccess
Specifies an access mask that specifies the requested types of access to the access token. These requested access types are compared with the token's DACL to determine which accesses are granted or denied.

bImpersonate
If TRUE, the current thread will impersonate the calling RPC client if this call completes successfully. If FALSE, the access token will be opened, but the thread will not have an impersonation token when this call completes.

bOpenAsSelf
Indicates whether the access check is to be made against the security context of the thread calling the GetThreadToken method or against the security context of the process for the calling thread.

If this parameter is FALSE, the access check is performed using the security context for the calling thread. If the thread is impersonating a client, this security context can be that of a client process. If this parameter is TRUE, the access check is made using the security context of the process for the calling thread.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

The CAutoRevertImpersonation Class can be used to automatically revert impersonated access tokens created by setting the bImpersonate flag to TRUE.

CAccessToken::OpenThreadToken

Call this method to set the impersonation level and then initialize the CAccessToken with the token from the given thread.

bool OpenThreadToken(
    DWORD dwDesiredAccess,
    bool bImpersonate = false,
    bool bOpenAsSelf = true,
    SECURITY_IMPERSONATION_LEVEL sil = SecurityImpersonation) throw(...);

Parameters

dwDesiredAccess
Specifies an access mask that specifies the requested types of access to the access token. These requested access types are compared with the token's DACL to determine which accesses are granted or denied.

bImpersonate
If TRUE, the thread will be left at the requested impersonation level after this method completes. If FALSE, the thread will revert to its original impersonation level.

bOpenAsSelf
Indicates whether the access check is to be made against the security context of the thread calling the GetThreadToken method or against the security context of the process for the calling thread.

If this parameter is FALSE, the access check is performed using the security context for the calling thread. If the thread is impersonating a client, this security context can be that of a client process. If this parameter is TRUE, the access check is made using the security context of the process for the calling thread.

sil
Specifies a SECURITY_IMPERSONATION_LEVEL enumerated type that supplies the impersonation level of the token.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

OpenThreadToken is similar to CAccessToken::GetThreadToken, but sets the impersonation level before initializing the CAccessToken from the thread's access token.

The CAutoRevertImpersonation Class can be used to automatically revert impersonated access tokens created by setting the bImpersonate flag to TRUE.

CAccessToken::PrivilegeCheck

Call this method to determine whether a specified set of privileges are enabled in the CAccessToken object.

bool PrivilegeCheck(
    PPRIVILEGE_SET RequiredPrivileges,
    bool* pbResult) const throw();

Parameters

RequiredPrivileges
Pointer to a PRIVILEGE_SET structure.

pbResult
Pointer to a value the method sets to indicate whether any or all of the specified privilege are enabled in the CAccessToken object.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

When PrivilegeCheck returns, the Attributes member of each LUID_AND_ATTRIBUTES structure is set to SE_PRIVILEGE_USED_FOR_ACCESS if the corresponding privilege is enabled. This method calls the PrivilegeCheck Win32 function.

CAccessToken::Revert

Call this method to stop a thread from using an impersonation token.

bool Revert(HANDLE hThread = NULL) const throw();

Parameters

hThread
Handle to the thread to revert from impersonation. If hThread is NULL, the current thread is assumed.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

The reversion of impersonation tokens can be performed automatically with the CAutoRevertImpersonation Class.

CAccessToken::SetDefaultDacl

Call this method to set the default DACL of the CAccessToken object.

bool SetDefaultDacl(const CDacl& rDacl) throw(...);

Parameters

rDacl
The new default CDacl Class information.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

The default DACL is the DACL that is used by default when new objects are created with this access token in effect.

CAccessToken::SetOwner

Call this method to set the owner of the CAccessToken object.

bool SetOwner(const CSid& rSid) throw(...);

Parameters

rSid
The CSid Class object containing the owner information.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

The owner is the default owner that is used for new objects created while this access token is in effect.

CAccessToken::SetPrimaryGroup

Call this method to set the primary group of the CAccessToken object.

bool SetPrimaryGroup(const CSid& rSid) throw(...);

Parameters

rSid
The CSid Class object containing the primary group information.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

The primary group is the default group for new objects created while this access token is in effect.

See also

ATLSecurity Sample
Access Tokens
Class Overview