How Access Tokens Work
Applies To: Windows Server 2003, Windows Server 2003 R2, Windows Server 2003 with SP1, Windows Server 2003 with SP2
How Access Tokens Work
In this section
Access Tokens Interfaces
Access Tokens Physical Structure
Access Tokens Processes and Interactions
Related Information
When a user is authenticated, the Local Security Authority (LSA) creates an access token — in this case, a primary access token — for that user. An access token contains a security identifier (SID) for the user, all of the SIDs for the groups to which the user belongs, and the user’s privileges. If you add a user to a group after the user’s access token has been issued, or modify privileges assigned to the user account, the user must log off and then log on again before the access token will be updated.
Whenever a thread or process interacts with a securable object or tries to perform a system task that requires privileges, the operating system checks the effective access token to determine its level of authorization. If a thread is impersonating, the effective token is usually taken to be the token on the thread. If a thread interacting with the securable object is not impersonating, then the token on the process is examined for the access decision.
Thus, there are two kinds of access tokens, primary and impersonation. Every process has a primary token that describes the security context of the user account associated with the process. A primary access token is typically assigned to a process to represent the default security information for that process. Impersonation access tokens, on the other hand, are usually used for client/server scenarios. Impersonation tokens enable a thread to execute in a security context that differs from the security context of the process that owns the thread.
Access Tokens Interfaces
The tables below list APIs used to create, modify, or query access tokens.
Token Creation APIs
| API Name | Description |
|---|---|
CreateRestrictedToken |
Creates a new access token that is a restricted version of an existing access token. |
DuplicateToken |
Creates a new impersonation token that duplicates one already in existence. |
DuplicateTokenEx |
Creates a new access token that duplicates an existing token. This function can create either a primary token or an impersonation token. |
OpenProcessToken |
Opens the access token associated with a process. |
OpenThreadToken |
Opens the access token associated with a thread. Tokens with the anonymous impersonation level cannot be opened. |
Token Modification APIs
| API Name | Description |
|---|---|
AdjustTokenGroups |
Enables or disables groups already present in the specified access token. Access to TOKEN_ADJUST_GROUPS is required to enable or disable groups in an access token. You cannot enable a group that has the SE_GROUP_USE_FOR_DENY_ONLY attribute. |
AdjustTokenPrivileges |
Enables or disables existing privileges in the specified access token. Enabling or disabling privileges in an access token requires TOKEN_ADJUST_PRIVILEGES access. |
ImpersonateAnonymousToken |
Enables the specified thread to impersonate the system’s anonymous logon token. To ensure that a token matches the operating system’s concept of anonymous access, this function should be called before attempting network access to generate an anonymous token on the remote server. Anonymous tokens do not include the Everyone Group SID unless the system default has been overridden. |
ImpersonateSelf |
Obtains an access token that impersonates the security context of the calling process. The token is assigned to the calling thread. For this function to succeed, the DACL protecting the process token must grant the TOKEN_DUPLICATE right to itself. |
RevertToSelf |
Terminates the impersonation of a client application. |
SetThreadToken |
Assigns an impersonation token to a thread. The function can also cause a thread to stop using an impersonation token. |
SetTokenInformation |
Sets various types of information for a specified access token. The information that this function sets replaces existing information. The calling process must have appropriate access rights to set the information. Token-type information can be set only when an access token is created. |
Token Query APIs
| API Name | Description |
|---|---|
CheckTokenMembership |
Determines whether a specified SID is enabled in an access token. |
GetTokenInformation |
Retrieves a specified type of information about an access token. The calling process must have appropriate access rights to obtain the information. |
IsTokenRestricted |
Indicates whether a token contains a list of restricted SIDs. |
PrivilegeCheck |
Determines whether a specified set of privileges is enabled in an access token. The PrivilegeCheck function is typically called by a server application to check the privileges of a client’s access token. |
For more information about token APIs, search for Authorization Structures in the Authorization reference in the Microsoft SDK documentation on MSDN.
Access Tokens Physical Structure
Access Token
.gif "Access Token")
An access token contains a complete description of the security context for a process or thread, including the information in the following table.
Access Token Components
| Component | Description |
|---|---|
User |
The SID for the user’s account. If the user logs on to an account on the local computer, the user’s SID is taken from the account database maintained by the local Security Accounts Manager (SAM). If the user logs on to a domain account, the SID is taken from the Object-SID property of the User object in Active Directory. |
Groups |
A list of SIDs for security groups that include the user. The list also includes SIDs from the SID-History property of the User object representing the user’s account in Active Directory. |
Privileges |
A list of privileges held on the local computer by the user and by the user’s security groups. |
Default Owner |
The SID for the user or security group who, by default, becomes the owner of any object that the user either creates or takes ownership of. |
Primary Group |
The SID for the user’s primary security group. This information is used only by the POSIX subsystem and is ignored by the rest of Windows Server 2003. |
Default Discretionary Access Control List (DACL) |
A built-in set of permissions that the operating system applies to objects created by the user if no other access control information is available. The default DACL grants Full Control to Creator Owner and System. |
Source |
The process that caused the access token to be created, such as Session Manager, LAN Manager, or Remote Procedure Call (RPC) Server. |
Type |
A value indicating whether the access token is a primary or impersonation token. |
Impersonation Level |
A value that indicates to what extent a service can adopt the security context of a client represented by this access token. |
Statistics |
Information about the access token itself. The operating system uses this information internally. |
Restricting SIDs |
An optional list of SIDs added to an access token by a process with authority to create a restricted token. Restricting SIDs can limit a thread’s access to a level lower than what the user is allowed. |
TS Session ID |
A value that indicates whether the access token is associated with the Terminal Services client session. |
Session Reference |
Reserved for internal use. |
SandBox Inert |
Nonzero if the token includes the SANDBOX_INERT flag. |
Audit Policy |
Since Windows Server 2003, used for per user auditing. |
Origin |
Introduced with Windows Server 2003. If the token resulted from a logon using explicit credentials, then the token will contain the ID of the logon session that created it. If the token resulted from network authentication, then this value will be zero. |
SID Attributes in an Access Token
Each user and group SID in an access token can have one of two attributes that control how the system uses the SID in an access check. The following table lists the attributes that control access checking.
SID Attributes
| Attribute | Description |
|---|---|
SE_GROUP_ENABLED |
A SID with this attribute is enabled for access checks. When the system performs an access check, it checks for access control entries (ACEs) that apply to the SID. |
SE_GROUP_USE_FOR_DENY_ONLY |
Since Windows 2000, a SID with this attribute is a deny-only SID. When the system performs an access check, it checks for ACEs that deny access to the SID. It ignores ACEs that allow access for the SID. |
Both attributes are mutually exclusive. If one attribute is set, the other cannot be set. If neither attribute is set, the SID is ignored. Moreover, no process is ever allowed to remove a deny-only attribute from a SID.
SIDHistory
SIDHistory is used to store the former SIDs of moved objects such as user’s and security groups.
Prior to Windows 2000, restructuring a domain generally meant the creation of new accounts that needed to be placed in the same groups the old accounts were placed in. Since Windows 2000, domain restructuring is made considerably easier as a result of SIDHistory, which is a new attribute of Active Directory security principals.
APIs (or tools and support utilities built from these APIs) update the SIDHistory attribute of the object, representing it in Active Directory with its former SID as part of the move operation for the user or group. When the user then logs on to the system, not only the new SID, but also the old SID retrieved from the SIDHistory attribute, are added to the user’s access token and used to determine the user’s group memberships. The SIDs of the groups of which the user is a member through either the new SID or the old SID are then also added to the access token, together with any SIDHistory those groups might have.
Because groups can be moved, they can also have SIDHistory. The system also retrieves the SIDHistory attributes of all the groups of which the user is a member and then adds these attributes to the user’s access token.
Because these SIDHistory entries in the token look to the system like normal group memberships during authorization checks, the token can grant appropriate access even on earlier versions of the system.
Note
- The SIDHistory attribute can only be updated in native mode Windows 2000 or Windows 2003 domains, which has the effect of requiring all migration operations relying on SIDHistory to have a native mode target for restructure.
Access Tokens Processes and Interactions
Clients never get direct access to network resources; instead, network services build a client’s access token and then impersonate the client to execute the requested operations. The Windows operating system kernel uses security identifiers in the access token to verify whether the user is authorized the desired access rights to the target object.
There are two kinds of access tokens, primary and impersonation.
Primary Tokens
Every process has a primary token that describes the security context of the user account associated with the process. The primary token may be assigned to a process to represent the default security information for that process.
Creating a Primary Token
The access token is built from the SID list acquired through authentication. Group membership can be evaluated non-transitively (as was done with Windows NT) or transitively. Since Windows 2000, chaining of groups has been possible in native domains. This allows a member of group A to be a member of group B if group A is a member of group B.
Creating the SID List for User Account to Access System
.gif "Creating SID List for User Account System Access")
Creating User SID Lists
The following example is for a user logging onto a system. This occurs during authentication either during pass thru authentication for NTLM or when creating the ticket granting ticket and service ticket for Kerberos authentication. The user's domain controller will do two or more of the following:
Authenticate the user.
Only if the user’s domain is in native mode, retrieve the user’s SID history and add it to the SID list.
Retrieve the user's global group membership.
If the user's domain is in mixed mode, retrieve global group membership of the user's SID and add these to the SID list.
If the user's domain is in native mode, transitively retrieve the global group membership of both the user's SID and the user's SID history and add these to the SID list.
If the user's domain is in native mode, pass the list of SIDs to the global catalog.
The global catalog will transitively retrieve the universal group membership for each SID in the list and add these to the SID list.
Return the list back to the domain controller.
If the system's domain is in native mode, transitively retrieve the domain local group membership for each SID in the list and add these to the SID list.
Return the list to the system.
Building the access token
The system places the SIDs received from the domain controller and all the built-in groups for each SID into the access token. These built-in groups will include the following:
Logon type
For specific logon types, a specific SID is added for that logon type, such as INTERACTIVE, or BATCH, for example.
If using NTLM logon, the system adds a specific SID.
Implicit Membership
In the case of the token for a “NT AUTHORITY\SYSTEM” process, the SID for “Administrators” is added to the token. Therefore SYSTEM implicitly belongs to “Administrators.”
The SID “Everyone” is added to every token, except for Anonymous tokens when the security policy option “Let Everyone permissions apply to Anonymous user’s” is disabled.
“Authenticated Users” is added to non-anonymous tokens.
There is also a “NONE” group, which is added to local tokens on non-domain controllers; “NONE” is the SID for the primary group for local accounts.
Summary of Conditions Required for SIDs to Be in SID List
| SID Type | User’s Domain | System’s Domain | ||
|---|---|---|---|---|
|
Mixed |
Native |
Mixed |
Native |
SID History |
No |
Yes |
No |
Yes |
Built-in |
No |
No |
Yes, system’s built-in |
Yes, system’s built-in |
Domain Local |
No |
No |
Yes, if system is DC in User’s domain |
Yes, transitive |
Global |
Yes, not transitive |
Yes, transitive |
|
|
Universal |
No |
Yes, transitive |
No |
No |
Impersonation Tokens
Impersonation tokens are access tokens that have been created to capture the security information of a client process, thus enabling a server to impersonate the client process in security operations.
Impersonation is the ability of a thread to execute in a security context that is different from the context of the process that owns the thread. Impersonation is designed to meet the security requirements of client/server applications. When running in a client’s security context, a service “is” the client, to some degree. One of the service’s threads uses an access token representing the client’s credentials to obtain access to the objects to which the client has access.
The primary reason for impersonation is to cause access checks to be performed against the client’s identity. Using the client’s identity for access checks can cause access to be either restricted or expanded, depending on what the client has permission to do. For example, suppose a file server has files containing confidential information, and each of these files is protected by a DACL. To prevent a client from obtaining unauthorized access to information in these files, the service can impersonate the client before accessing the files.
Every process has a primary token that describes the security context of the user account associated with the process. In an ordinary application process, the user associated with the process is the human user who started the application. In a service process, however, services run under their own accounts and have identities in their own right.
System services installed with the operating system run under the Local System, local service, or Network Service account. Other services can be configured to run three different account types: Local System account, service accounts on the local system, or service accounts in Active Directory.
The primary token for a service is associated with the control thread in the service process and with all other threads acting on behalf of the service. It identifies the service’s account, group memberships, and privileges. The service uses this information during access checks when the service requests access to objects needed for its own housekeeping.
Then, when a service accepts a client, it creates a thread to do the work and associates the client’s access token with the worker thread. Once associated in this way, the client’s access token is an impersonation token that identifies the client, the client’s groups, and the client’s privileges. The impersonation token’s information is used during access checks when the thread requests access to resources on the client’s behalf. When impersonation is over, the thread reverts to using the primary token and returns to operating in the service’s security context instead of the client’s.
The Mechanism for Impersonation
.gif "The Mechanism for Impersonation")
Impersonation Levels
A client process can control to what extent a service is able to act as the client by selecting an impersonation level when it connects to the service. By choosing an impersonation level, the client tells the service to what extent it can impersonate the client. In other words, the impersonation levels described in the table below define to what extent the client agrees to let the service “be” the client.
Users cannot select an impersonation level. One is specified as Security Quality of Service (SQoS) information in the code for client/server applications. There are four impersonation levels: anonymous, identify, impersonate, and delegate. The anonymous level has never been supported. Prior to Windows 2000, only the identify and impersonate levels were supported. Windows 2000 added support for the delegate level.
Impersonation Levels
| Impersonation Level | Description |
|---|---|
Anonymous |
The client is anonymous to the service. The service can impersonate the client but the impersonation token does not contain any information about the client. |
Identify |
The service can get the identity of the client and can use this information in its own security mechanism, but it cannot impersonate the client. |
Impersonate |
The service can impersonate the client. If the service is on the same computer as the client process, it can access network resources as the client. If the service is on a remote computer, it can impersonate the client only when accessing resources on the service’s computer. |
Delegate |
The service can impersonate the client not only when it accesses resources on the service’s computer but also when it accesses resources on other computers. This level is supported only in Windows 2000 and later versions of the Windows operating system. |
Configuring Clients and Services for Delegation
Impersonation works at the delegate level only under the following conditions:
The computers hosting the client process, the service process, and processes for any backend services must all be running Windows 2000 or later in a Windows 2000 or later domain. This is because delegation requires the Kerberos authentication protocol.
The client’s user account must be enabled for delegation.
The service’s account must be enabled for delegation.
The way you configure the service account depends on whether the service runs under the Local System account on a computer or under its own domain user account.
If the service is configured to run under the Local System account, the computer where the service runs must be trusted for delegation. (Note that when you trust a computer for delegation, you enable delegation for all services that run under the Local System account on the computer. If an unwary administrator installs an untrusted service on the computer and configures it to run as Local System, it too can access network resources while impersonating other user’s. A better practice is to configure services that use delegation to run under their own domain user accounts managed by domain administrators.)
If the service is configured to run under its own domain user account, the service’s user account must be enabled to act as a delegate.
Restricted Tokens
A restricted token is a primary or impersonation access token that has been modified by the CreateRestrictedToken function. A process or impersonating thread running in the security context of a restricted token is restricted in its ability to access securable objects or perform privileged operations. In Windows 2000 and later, an application can start a child process in a restricted security context so that code executing in the child process has more limited access to resources than the application’s user has. For example, when you use Internet-browsing software to display a Web page in an untrusted security zone, code associated with the Web page can execute with fewer privileges on your computer than you have. (This feature is not used by Microsoft Internet Explorer version 5.0 and earlier.)
Applications can create restricted security contexts for child processes and impersonation threads by creating a restricted token and assigning it to the child process or the impersonating thread. Restricted tokens are created by removing privileges, by applying the deny-only attribute to SIDs, or by adding a list of restricting SIDs to the original access token.
When a restricted process or thread tries to access a securable object, the system performs two access checks by:
Reading the token’s enabled and deny-only SIDs.
Reading the list of restricting SIDs.
Access is granted only if both access checks allow the requested access rights.
For more information about restricted tokens, see Access Control in the Microsoft Platform SDK on MSDN.
Related Information
The following resource contains additional information that is relevant to this subject.