This documentation is archived and is not being maintained.

WindowsIdentity.Impersonate Method

Updated: December 2010

Impersonates the user represented by the WindowsIdentity object.

Namespace:  System.Security.Principal
Assembly:  mscorlib (in mscorlib.dll)

'Declaration
Public Overridable Function Impersonate As WindowsImpersonationContext
'Usage
Dim instance As WindowsIdentity 
Dim returnValue As WindowsImpersonationContext 

returnValue = instance.Impersonate()

Return Value

Type: System.Security.Principal.WindowsImpersonationContext
A WindowsImpersonationContext object that represents the Windows user prior to impersonation; this can be used to revert to the original user's context.

ExceptionCondition
InvalidOperationException

An anonymous identity attempted to perform an impersonation.

SecurityException

A Win32 error occurred.

On Windows NT platforms, the current user must have sufficient rights to allow impersonation.

Notes to Implementers:

Because Microsoft Windows 98 and Windows Millennium Edition (Windows Me) platforms do not have user tokens, impersonation cannot take place on those platforms.

Notes to Callers:

After using Impersonate, it is important to call the Undo method to end the impersonation.

The following example demonstrates how to obtain a Windows account token by calling the unmanaged Win32 LogonUser function, and how to use that token to impersonate another user and then revert to the original identity.

' 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.   
' The sample is intended to be executed in a .NET Framework 1.1 environment.  To execute 
' this code in a 1.0 environment you will need to use a duplicate token in the call to the 
' WindowsIdentity constructor.  See KB article Q319615 for more information. 

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 

        ' 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

                tokenHandle = 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)
                    Throw New System.ComponentModel.Win32Exception(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))

                ' Use the token handle returned by LogonUser. 
                Dim newId As New WindowsIdentity(tokenHandle)
                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 

            Catch ex As Exception
                Console.WriteLine(("Exception occurred. " + ex.Message))
            End Try 
        End Sub 'Main 
    End Class 'Class1
End Module

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

Date

History

Reason

December 2010

Replaced the example.

Customer feedback.

Show: