Edit

Share via

Access Tokens

  • Article

An access token is an object that describes the security context of a process or thread. The information in a token includes the identity and privileges of the user account associated with the process or thread. When a user logs on, the system verifies the user's password by comparing it with information stored in a security database. If the password is authenticated, the system produces an access token. Every process executed on behalf of this user has a copy of this access token.

The system uses an access token to identify the user when a thread interacts with a securable object or tries to perform a system task that requires privileges. Access tokens contain the following information:

  • The security identifier (SID) for the user's account
  • SIDs for the groups of which the user is a member
  • A logon SID that identifies the current logon session
  • A list of the privileges held by either the user or the user's groups
  • An owner SID
  • The SID for the primary group
  • The default DACL that the system uses when the user creates a securable object without specifying a security descriptor
  • The source of the access token
  • Whether the token is a primary or impersonation token
  • An optional list of restricting SIDs
  • Current impersonation levels
  • Other statistics

Every process has a primary token that describes the security context of the user account associated with the process. By default, the system uses the primary token when a thread of the process interacts with a securable object. Moreover, a thread can impersonate a client account. Impersonation allows the thread to interact with securable objects using the client's security context. A thread that is impersonating a client has both a primary token and an impersonation token.

Use the OpenProcessToken function to retrieve a handle to the primary token of a process. Use the OpenThreadToken function to retrieve a handle to the impersonation token of a thread. For more information, see Impersonation.

You can use the following functions to manipulate access tokens.

Function Description
AdjustTokenGroups Changes the group information in an access token.
AdjustTokenPrivileges Enables or disables the privileges in an access token. It does not grant new privileges or revoke existing ones.
CheckTokenMembership Determines whether a specified SID is enabled in a specified access token.
CreateRestrictedToken Creates a new token that is a restricted version of an existing token. The restricted token can have disabled SIDs, deleted privileges, and a list of restricted SIDs.
DuplicateToken Creates a new impersonation token that duplicates an existing token.
DuplicateTokenEx Creates a new primary token or impersonation token that duplicates an existing token.
GetTokenInformation Retrieves information about a token.
IsTokenRestricted Determines whether a token has a list of restricting SIDs.
OpenProcessToken Retrieves a handle to the primary access token for a process.
OpenThreadToken Retrieves a handle to the impersonation access token for a thread.
SetThreadToken Assigns or removes an impersonation token for a thread.
SetTokenInformation Changes a token's owner, primary group, or default DACL.

 

The access token functions use the following structures to describe the parts of an access token.

Structure Description
TOKEN_CONTROL Information that identifies an access token.
TOKEN_DEFAULT_DACL The default DACL that the system uses in the security descriptors of new objects created by a thread.
TOKEN_GROUPS Specifies the SIDs and attributes of the group SIDs in an access token.
TOKEN_OWNER The default owner SID for the security descriptors of new objects.
TOKEN_PRIMARY_GROUP The default primary group SID for the security descriptors of new objects.
TOKEN_PRIVILEGES The privileges associated with an access token. Also determines whether the privileges are enabled.
TOKEN_SOURCE The source of an access token.
TOKEN_STATISTICS Statistics associated with an access token.
TOKEN_USER The SID of the user associated with an access token.

 

The access token functions use the following enumeration types.

Enumeration type Specifies
TOKEN_INFORMATION_CLASS Identifies the type of information being set or retrieved from an access token.
TOKEN_TYPE Identifies an access token as a primary or impersonation token.