WTSQueryUserToken function

Obtains the primary access token of the logged-on user specified by the session ID. To call this function successfully, the calling application must be running within the context of the LocalSystem account and have the SE_TCB_NAME privilege.

Caution  WTSQueryUserToken is intended for highly trusted services. Service providers must use caution that they do not leak user tokens when calling this function. Service providers must close token handles after they have finished using them.

Syntax


BOOL WTSQueryUserToken(
  _In_   ULONG SessionId,
  _Out_  PHANDLE phToken
);

Parameters

SessionId [in]

A Remote Desktop Services session identifier. Any program running in the context of a service will have a session identifier of zero (0). You can use the WTSEnumerateSessions function to retrieve the identifiers of all sessions on a specified RD Session Host server.

To be able to query information for another user's session, you need to have the Query Information permission. For more information, see Remote Desktop Services Permissions. To modify permissions on a session, use the Remote Desktop Services Configuration administrative tool.

phToken [out]

If the function succeeds, receives a pointer to the token handle for the logged-on user. Note that you must call the CloseHandle function to close this handle.

Return value

If the function succeeds, the return value is a nonzero value, and the phToken parameter points to the primary token of the user.

If the function fails, the return value is zero. To get extended error information, call GetLastError. Among other errors, GetLastError can return one of the following errors.

Return code/valueDescription
ERROR_PRIVILEGE_NOT_HELD
1314

The caller does not have the SE_TCB_NAME privilege.

ERROR_INVALID_PARAMETER
87

One of the parameters to the function was incorrect; for example, the phToken parameter was passed a NULL parameter.

ERROR_ACCESS_DENIED
5

The caller does not have the appropriate permissions to call this function. The caller must be running within the context of the LocalSystem account and have the SE_TCB_NAME privilege.

ERROR_FILE_NOT_FOUND
7022

The token query is for a session that does not exist.

ERROR_NO_TOKEN
1008

The token query is for a session in which no user is logged-on. This occurs, for example, when the session is in the idle state or SessionId is zero.

 

Remarks

For information about primary tokens, see Access Tokens. For more information about account privileges, see Remote Desktop Services Permissions and Authorization Constants.

See LocalSystem account for information about the privileges associated with that account.

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Header

Wtsapi32.h

Library

Wtsapi32.lib

DLL

Wtsapi32.dll

See also

WTSEnumerateSessions
CloseHandle

 

 

Show:
© 2014 Microsoft