Export (0) Print
Expand All

WindowsIdentity.Impersonate Method

Allows code to impersonate a different Windows user.

Overload List

Impersonates the user represented by the WindowsIdentity object.

[Visual Basic] Overloads Public Overridable Function Impersonate() As WindowsImpersonationContext
[C#] public virtual WindowsImpersonationContext Impersonate();
[C++] public: virtual WindowsImpersonationContext* Impersonate();
[JScript] public function Impersonate() : WindowsImpersonationContext;

Impersonates the user represented by the specified user token.

[Visual Basic] Overloads Public Shared Function Impersonate(IntPtr) As WindowsImpersonationContext
[C#] public static WindowsImpersonationContext Impersonate(IntPtr);
[C++] public: static WindowsImpersonationContext* Impersonate(IntPtr);
[JScript] public static function Impersonate(IntPtr) : WindowsImpersonationContext;

Example

[Visual Basic, C#, C++] The following example demonstrates how to impersonate a user and then revert to the original identity.

[Visual Basic, C#, C++] Note   This example shows how to use one of the overloaded versions of Impersonate. For other examples that might be available, see the individual overload topics.
[Visual Basic] 
' This sample demonstrates the use of the WindowsIdentity class to impersonate a user.
' IMPORTANT NOTES: 
' This sample can be run only on Windows XP.  The default Windows 2000 security policy 
' prevents this sample from executing properly, and changing the policy to allow
' proper execution presents a security risk. 
' This sample requests the user to enter a password on the console screen.
' Because the console window does not support methods allowing the password to be masked, 
' it will be visible to anyone viewing the screen.  

Imports System
Imports System.Runtime.InteropServices
Imports System.Security.Principal
Imports System.Security.Permissions
Imports Microsoft.VisualBasic
<Assembly: SecurityPermissionAttribute(SecurityAction.RequestMinimum, UnmanagedCode:=True), _
 Assembly: PermissionSetAttribute(SecurityAction.RequestMinimum, Name:="FullTrust")> 
Module Module1

    Public Class ImpersonationDemo

        Private Declare Auto Function LogonUser Lib "advapi32.dll" (ByVal lpszUsername As [String], _
            ByVal lpszDomain As [String], ByVal lpszPassword As [String], _
            ByVal dwLogonType As Integer, ByVal dwLogonProvider As Integer, _
            ByRef phToken As IntPtr) As Boolean

        <DllImport("kernel32.dll")> _
        Public Shared Function FormatMessage(ByVal dwFlags As Integer, ByRef lpSource As IntPtr, _
            ByVal dwMessageId As Integer, ByVal dwLanguageId As Integer, ByRef lpBuffer As [String], _
            ByVal nSize As Integer, ByRef Arguments As IntPtr) As Integer

        End Function

        Public Declare Auto Function CloseHandle Lib "kernel32.dll" (ByVal handle As IntPtr) As Boolean


        Public Declare Auto Function DuplicateToken Lib "advapi32.dll" (ByVal ExistingTokenHandle As IntPtr, _
                ByVal SECURITY_IMPERSONATION_LEVEL As Integer, _
                ByRef DuplicateTokenHandle As IntPtr) As Boolean

        'GetErrorMessage formats and returns an error message
        'corresponding to the input errorCode.
        Public Shared Function GetErrorMessage(ByVal errorCode As Integer) As String
            Dim FORMAT_MESSAGE_ALLOCATE_BUFFER As Integer = &H100
            Dim FORMAT_MESSAGE_IGNORE_INSERTS As Integer = &H200
            Dim FORMAT_MESSAGE_FROM_SYSTEM As Integer = &H1000

            Dim messageSize As Integer = 255
            Dim lpMsgBuf As String
            Dim dwFlags As Integer = FORMAT_MESSAGE_ALLOCATE_BUFFER Or FORMAT_MESSAGE_FROM_SYSTEM Or FORMAT_MESSAGE_IGNORE_INSERTS

            Dim ptrlpSource As IntPtr = IntPtr.Zero
            Dim prtArguments As IntPtr = IntPtr.Zero

            Dim retVal As Integer = FormatMessage(dwFlags, ptrlpSource, errorCode, 0, lpMsgBuf, _
                messageSize, prtArguments)
            If 0 = retVal Then
                Throw New Exception("Failed to format message for error code " + errorCode.ToString() + ". ")
            End If

            Return lpMsgBuf
        End Function 'GetErrorMessage
        ' Test harness.
        ' If you incorporate this code into a DLL, be sure to demand FullTrust.
        <PermissionSetAttribute(SecurityAction.Demand, Name:="FullTrust")> _
        Public Overloads Shared Sub Main(ByVal args() As String)

            Dim tokenHandle As New IntPtr(0)
            Dim dupeTokenHandle As New IntPtr(0)
            Try


                Dim userName, domainName As String

                ' Get the user token for the specified user, domain, and password using the 
                ' unmanaged LogonUser method.  
                ' The local machine name can be used for the domain name to impersonate a user on this machine.
                Console.Write("Enter the name of a domain on which to log on: ")
                domainName = Console.ReadLine()

                Console.Write("Enter the login of a user on {0} that you wish to impersonate: ", domainName)
                userName = Console.ReadLine()

                Console.Write("Enter the password for {0}: ", userName)

                Const LOGON32_PROVIDER_DEFAULT As Integer = 0
                'This parameter causes LogonUser to create a primary token.
                Const LOGON32_LOGON_INTERACTIVE As Integer = 2
                Const SecurityImpersonation As Integer = 2

                tokenHandle = IntPtr.Zero
                dupeTokenHandle = IntPtr.Zero

                ' Call LogonUser to obtain a handle to an access token.
                Dim returnValue As Boolean = LogonUser(userName, domainName, Console.ReadLine(), LOGON32_LOGON_INTERACTIVE, LOGON32_PROVIDER_DEFAULT, tokenHandle)

                Console.WriteLine("LogonUser called.")

                If False = returnValue Then
                    Dim ret As Integer = Marshal.GetLastWin32Error()
                    Console.WriteLine("LogonUser failed with error code : {0}", ret)
                    Console.WriteLine(ControlChars.Cr + "Error: [{0}] {1}" + ControlChars.Cr, ret, GetErrorMessage(ret))

                    Return
                End If

                Dim success As String
                If returnValue Then success = "Yes" Else success = "No"
                Console.WriteLine(("Did LogonUser succeed? " + success))
                Console.WriteLine(("Value of Windows NT token: " + tokenHandle.ToString()))

                ' Check the identity.
                Console.WriteLine(("Before impersonation: " + WindowsIdentity.GetCurrent().Name))

                Dim retVal As Boolean = DuplicateToken(tokenHandle, SecurityImpersonation, dupeTokenHandle)
                If False = retVal Then
                    CloseHandle(tokenHandle)
                    Console.WriteLine("Exception thrown in trying to duplicate token.")
                    Return
                End If

                ' TThe token that is passed to the following constructor must 
                ' be a primary token in order to use it for impersonation.
                Dim newId As New WindowsIdentity(dupeTokenHandle)
                Dim impersonatedUser As WindowsImpersonationContext = newId.Impersonate()

                ' Check the identity.
                Console.WriteLine(("After impersonation: " + WindowsIdentity.GetCurrent().Name))

                ' Stop impersonating the user.
                impersonatedUser.Undo()

                ' Check the identity.
                Console.WriteLine(("After Undo: " + WindowsIdentity.GetCurrent().Name))

                ' Free the tokens.
                If Not System.IntPtr.op_Equality(tokenHandle, IntPtr.Zero) Then
                    CloseHandle(tokenHandle)
                End If
                If Not System.IntPtr.op_Equality(dupeTokenHandle, IntPtr.Zero) Then
                    CloseHandle(dupeTokenHandle)
                End If
            Catch ex As Exception
                Console.WriteLine(("Exception occurred. " + ex.Message))
            End Try
        End Sub 'Main 
    End Class 'Class1


[C#] 
// This sample demonstrates the use of the WindowsIdentity class to impersonate a user.
// IMPORTANT NOTES: 
// This sample can be run only on Windows XP.  The default Windows 2000 security policy 
// prevents this sample from executing properly, and changing the policy to allow
// proper execution presents a security risk. 
// This sample requests the user to enter a password on the console screen.
// Because the console window does not support methods allowing the password to be masked, 
// it will be visible to anyone viewing the screen.

using System;
using System.Runtime.InteropServices;
using System.Security.Principal;
using System.Security.Permissions;

[assembly:SecurityPermissionAttribute(SecurityAction.RequestMinimum, UnmanagedCode=true)]
[assembly:PermissionSetAttribute(SecurityAction.RequestMinimum, Name = "FullTrust")]
public class ImpersonationDemo
{
    [DllImport("advapi32.dll", SetLastError=true)]
    public static extern bool LogonUser(String lpszUsername, String lpszDomain, String lpszPassword, 
        int dwLogonType, int dwLogonProvider, ref IntPtr phToken);

    [DllImport("kernel32.dll", CharSet=System.Runtime.InteropServices.CharSet.Auto)]
    private unsafe static extern int FormatMessage(int dwFlags, ref IntPtr lpSource, 
        int dwMessageId, int dwLanguageId, ref String lpBuffer, int nSize, IntPtr *Arguments);

    [DllImport("kernel32.dll", CharSet=CharSet.Auto)]
    public extern static bool CloseHandle(IntPtr handle);

    [DllImport("advapi32.dll", CharSet=CharSet.Auto, SetLastError=true)]
    public extern static bool DuplicateToken(IntPtr ExistingTokenHandle, 
        int SECURITY_IMPERSONATION_LEVEL, ref IntPtr DuplicateTokenHandle);


    // GetErrorMessage formats and returns an error message
    // corresponding to the input errorCode.
    public unsafe static string GetErrorMessage(int errorCode)
    {
        int FORMAT_MESSAGE_ALLOCATE_BUFFER = 0x00000100;
        int FORMAT_MESSAGE_IGNORE_INSERTS = 0x00000200;
        int FORMAT_MESSAGE_FROM_SYSTEM  = 0x00001000;

        //int errorCode = 0x5; //ERROR_ACCESS_DENIED
        //throw new System.ComponentModel.Win32Exception(errorCode);

        int messageSize = 255;
        String lpMsgBuf = "";
        int dwFlags = FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS;

        IntPtr ptrlpSource = IntPtr.Zero;
        IntPtr prtArguments = IntPtr.Zero;
        
        int retVal = FormatMessage(dwFlags, ref ptrlpSource, errorCode, 0, ref lpMsgBuf, messageSize, &prtArguments);
        if (0 == retVal)
        {
            throw new Exception("Failed to format message for error code " + errorCode + ". ");
        }

        return lpMsgBuf;
    }

    // Test harness.
    // If you incorporate this code into a DLL, be sure to demand FullTrust.
    [PermissionSetAttribute(SecurityAction.Demand, Name = "FullTrust")]
    public static void Main(string[] args)
    {    
        IntPtr tokenHandle = new IntPtr(0);
        IntPtr dupeTokenHandle = new IntPtr(0);
        try
        {
            string userName, domainName;
            // Get the user token for the specified user, domain, and password using the 
            // unmanaged LogonUser method.  
            // The local machine name can be used for the domain name to impersonate a user on this machine.
            Console.Write("Enter the name of the domain on which to log on: ");
            domainName = Console.ReadLine();

            Console.Write("Enter the login of a user on {0} that you wish to impersonate: ", domainName);
            userName = Console.ReadLine();

            Console.Write("Enter the password for {0}: ", userName);
            
            const int LOGON32_PROVIDER_DEFAULT = 0;
            //This parameter causes LogonUser to create a primary token.
            const int LOGON32_LOGON_INTERACTIVE = 2;
            const int SecurityImpersonation = 2;

            tokenHandle = IntPtr.Zero;
            dupeTokenHandle = IntPtr.Zero;

            // Call LogonUser to obtain a handle to an access token.
            bool returnValue = LogonUser(userName, domainName, Console.ReadLine(), 
                LOGON32_LOGON_INTERACTIVE, LOGON32_PROVIDER_DEFAULT,
                ref tokenHandle);
                    
            Console.WriteLine("LogonUser called.");
                
            if (false == returnValue)
            {
                int ret = Marshal.GetLastWin32Error();
                Console.WriteLine("LogonUser failed with error code : {0}", ret);
                Console.WriteLine("\nError: [{0}] {1}\n", ret, GetErrorMessage(ret));
                int errorCode = 0x5; //ERROR_ACCESS_DENIED
                throw new System.ComponentModel.Win32Exception(errorCode);
            }

            Console.WriteLine("Did LogonUser Succeed? " + (returnValue? "Yes" : "No"));
            Console.WriteLine("Value of Windows NT token: " + tokenHandle);

            // Check the identity.
            Console.WriteLine("Before impersonation: "
                + WindowsIdentity.GetCurrent().Name);

            bool retVal = DuplicateToken(tokenHandle, SecurityImpersonation, ref dupeTokenHandle);
            if (false == retVal)
            {
                CloseHandle(tokenHandle);
                Console.WriteLine("Exception thrown in trying to duplicate token.");        
                return;
            }
            
            // The token that is passed to the following constructor must 
            // be a primary token in order to use it for impersonation.
            WindowsIdentity newId = new WindowsIdentity(dupeTokenHandle);
            WindowsImpersonationContext impersonatedUser = newId.Impersonate();

            // Check the identity.
            Console.WriteLine("After impersonation: "
                + WindowsIdentity.GetCurrent().Name);
        
            // Stop impersonating the user.
            impersonatedUser.Undo();

            // Check the identity.
            Console.WriteLine("After Undo: " + WindowsIdentity.GetCurrent().Name);
            
            // Free the tokens.
            if (tokenHandle != IntPtr.Zero)
                CloseHandle(tokenHandle);
            if (dupeTokenHandle != IntPtr.Zero) 
                CloseHandle(dupeTokenHandle);
        }
        catch(Exception ex)
        {
            Console.WriteLine("Exception occurred. " + ex.Message);
        }

    }
}


[C++] 
// This sample demonstrates the use of the WindowsIdentity class to impersonate a user.
// IMPORTANT NOTES: 
// This sample can be run only on Windows XP.  The default Windows 2000 security policy 
// prevents this sample from executing properly, and changing the policy to allow
// proper execution presents a security risk. 
// This sample requests the user to enter a password on the console screen.
// Because the console window does not support methods allowing the password to be masked, 
// it will be visible to anyone viewing the screen.

#using <mscorlib.dll>
#using <System.dll>
using namespace System;
using namespace System::Runtime::InteropServices;
using namespace System::Security::Principal;
using namespace System::Security::Permissions;

[assembly:SecurityPermissionAttribute(SecurityAction::RequestMinimum, UnmanagedCode=true)]
[assembly:PermissionSetAttribute(SecurityAction::RequestMinimum, Name = S"FullTrust")];


[DllImport(S"advapi32.dll", SetLastError=true)]
bool LogonUser(String* lpszUsername, String* lpszDomain, String* lpszPassword, 
               int dwLogonType, int dwLogonProvider, IntPtr* phToken);

[DllImport(S"kernel32.dll", CharSet=System::Runtime::InteropServices::CharSet::Auto)]
int FormatMessage(int dwFlags, IntPtr* lpSource, 
                  int dwMessageId, int dwLanguageId, String** lpBuffer, int nSize, IntPtr *Arguments);

[DllImport(S"kernel32.dll", CharSet=CharSet::Auto)]
bool CloseHandle(IntPtr handle);

[DllImport(S"advapi32.dll", CharSet=CharSet::Auto, SetLastError=true)]
bool DuplicateToken(IntPtr ExistingTokenHandle, 
                    int SECURITY_IMPERSONATION_LEVEL, IntPtr* DuplicateTokenHandle);


// GetErrorMessage formats and returns an error message
// corresponding to the input errorCode.
String* GetErrorMessage(int errorCode)
{
    int FORMAT_MESSAGE_ALLOCATE_BUFFER = 0x00000100;
    int FORMAT_MESSAGE_IGNORE_INSERTS = 0x00000200;
    int FORMAT_MESSAGE_FROM_SYSTEM  = 0x00001000;

    //int errorCode = 0x5; //ERROR_ACCESS_DENIED
    //throw new System.ComponentModel.Win32Exception(errorCode);

    int messageSize = 255;
    String* lpMsgBuf = S"";
    int dwFlags = FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS;

    IntPtr ptrlpSource = IntPtr::Zero;
    IntPtr prtArguments = IntPtr::Zero;

    int retVal = FormatMessage(dwFlags, &ptrlpSource, errorCode, 0, &lpMsgBuf, messageSize, &prtArguments);
    if (0 == retVal)
    {
        throw new Exception(String::Format( S"Failed to format message for error code {0}. ", __box(errorCode)));
    }

    return lpMsgBuf;
}

// Test harness.
// If you incorporate this code into a DLL, be sure to demand FullTrust.
[PermissionSetAttribute(SecurityAction::Demand, Name = S"FullTrust")]
int main()
{    
    IntPtr tokenHandle = IntPtr(0);
    IntPtr dupeTokenHandle = IntPtr(0);
    try
    {
        String* userName;
        String* domainName;

        // Get the user token for the specified user, domain, and password using the 
        // unmanaged LogonUser method.  
        // The local machine name can be used for the domain name to impersonate a user on this machine.
        Console::Write(S"Enter the name of the domain on which to log on: ");
        domainName = Console::ReadLine();

        Console::Write(S"Enter the login of a user on {0} that you wish to impersonate: ", domainName);
        userName = Console::ReadLine();

        Console::Write(S"Enter the password for {0}: ", userName);

        const int LOGON32_PROVIDER_DEFAULT = 0;
        //This parameter causes LogonUser to create a primary token.
        const int LOGON32_LOGON_INTERACTIVE = 2;
        const int SecurityImpersonation = 2;

        tokenHandle = IntPtr::Zero;
        dupeTokenHandle = IntPtr::Zero;

        // Call LogonUser to obtain a handle to an access token.
        bool returnValue = LogonUser(userName, domainName, Console::ReadLine(), 
            LOGON32_LOGON_INTERACTIVE, LOGON32_PROVIDER_DEFAULT,
            &tokenHandle);

        Console::WriteLine(S"LogonUser called.");

        if (false == returnValue)
        {
            int ret = Marshal::GetLastWin32Error();
            Console::WriteLine(S"LogonUser failed with error code : {0}", __box(ret));
            Console::WriteLine(S"\nError: [{0}] {1}\n", __box(ret), GetErrorMessage(ret));
            int errorCode = 0x5; //ERROR_ACCESS_DENIED
            throw new System::ComponentModel::Win32Exception(errorCode);
        }

        Console::WriteLine(S"Did LogonUser Succeed? {0}", (returnValue?S"Yes":S"No"));
        Console::WriteLine(S"Value of Windows NT token: {0}", __box(tokenHandle));

        // Check the identity.
        Console::WriteLine(S"Before impersonation: {0}", WindowsIdentity::GetCurrent()->Name);

        bool retVal = DuplicateToken(tokenHandle, SecurityImpersonation, &dupeTokenHandle);
        if (false == retVal)
        {
            CloseHandle(tokenHandle);
            Console::WriteLine(S"Exception thrown in trying to duplicate token.");        
            return -1;
        }

        // The token that is passed to the following constructor must 
        // be a primary token in order to use it for impersonation.
        WindowsIdentity* newId = new WindowsIdentity(dupeTokenHandle);
        WindowsImpersonationContext* impersonatedUser = newId->Impersonate();

        // Check the identity.
        Console::WriteLine(S"After impersonation: {0}", WindowsIdentity::GetCurrent()->Name);

        // Stop impersonating the user.
        impersonatedUser->Undo();

        // Check the identity.
        Console::WriteLine(S"After Undo: {0}", WindowsIdentity::GetCurrent()->Name);

        // Free the tokens.
        if (tokenHandle != IntPtr::Zero)
            CloseHandle(tokenHandle);
        if (dupeTokenHandle != IntPtr::Zero) 
            CloseHandle(dupeTokenHandle);
    }
    catch(Exception* ex)
    {
        Console::WriteLine(S"Exception occurred. {0}", ex->Message);
    }

}

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

See Also

WindowsIdentity Class | WindowsIdentity Members | System.Security.Principal Namespace

Show:
© 2014 Microsoft