Bewerken

Share via


WindowsIdentity Constructors

Definition

Initializes a new instance of the WindowsIdentity class.

Overloads

WindowsIdentity(IntPtr)

Initializes a new instance of the WindowsIdentity class for the user represented by the specified Windows account token.

WindowsIdentity(WindowsIdentity)

Initializes a new instance of the WindowsIdentity class by using the specified WindowsIdentity object.

WindowsIdentity(String)

Initializes a new instance of the WindowsIdentity class for the user represented by the specified User Principal Name (UPN).

WindowsIdentity(IntPtr, String)

Initializes a new instance of the WindowsIdentity class for the user represented by the specified Windows account token and the specified authentication type.

WindowsIdentity(SerializationInfo, StreamingContext)
Obsolete.

Initializes a new instance of the WindowsIdentity class for the user represented by information in a SerializationInfo stream.

WindowsIdentity(String, String)

Initializes a new instance of the WindowsIdentity class for the user represented by the specified User Principal Name (UPN) and the specified authentication type.

WindowsIdentity(IntPtr, String, WindowsAccountType)

Initializes a new instance of the WindowsIdentity class for the user represented by the specified Windows account token, the specified authentication type, and the specified Windows account type.

WindowsIdentity(IntPtr, String, WindowsAccountType, Boolean)

Initializes a new instance of the WindowsIdentity class for the user represented by the specified Windows account token, the specified authentication type, the specified Windows account type, and the specified authentication status.

WindowsIdentity(IntPtr)

Initializes a new instance of the WindowsIdentity class for the user represented by the specified Windows account token.

public:
 WindowsIdentity(IntPtr userToken);
public WindowsIdentity (IntPtr userToken);
new System.Security.Principal.WindowsIdentity : nativeint -> System.Security.Principal.WindowsIdentity
Public Sub New (userToken As IntPtr)

Parameters

userToken
IntPtr

nativeint

The account token for the user on whose behalf the code is running.

Exceptions

userToken is 0.

-or-

userToken is duplicated and invalid for impersonation.

The caller does not have the correct permissions.

-or-

A Win32 error occurred.

Remarks

The following table shows initial property values for an instance of WindowsIdentity.

Property Initial value
AuthenticationType Negotiate
WindowsAccountType Normal
IsAuthenticated false

Note

You can retrieve the token represented by userToken by calling unmanaged code such as the Windows API LogonUser function. Always release userToken by calling the Windows API CloseHandle function. For more information on calling unmanaged code, see Consuming Unmanaged DLL Functions.

Applies to

WindowsIdentity(WindowsIdentity)

Initializes a new instance of the WindowsIdentity class by using the specified WindowsIdentity object.

protected:
 WindowsIdentity(System::Security::Principal::WindowsIdentity ^ identity);
protected WindowsIdentity (System.Security.Principal.WindowsIdentity identity);
new System.Security.Principal.WindowsIdentity : System.Security.Principal.WindowsIdentity -> System.Security.Principal.WindowsIdentity
Protected Sub New (identity As WindowsIdentity)

Parameters

identity
WindowsIdentity

The object from which to construct the new instance of WindowsIdentity.

Applies to

WindowsIdentity(String)

Initializes a new instance of the WindowsIdentity class for the user represented by the specified User Principal Name (UPN).

public:
 WindowsIdentity(System::String ^ sUserPrincipalName);
public WindowsIdentity (string sUserPrincipalName);
new System.Security.Principal.WindowsIdentity : string -> System.Security.Principal.WindowsIdentity
Public Sub New (sUserPrincipalName As String)

Parameters

sUserPrincipalName
String

The UPN for the user on whose behalf the code is running.

Exceptions

Windows returned the Windows NT status code STATUS_ACCESS_DENIED.

There is insufficient memory available.

The caller does not have the correct permissions.

-or-

The computer is not attached to a Windows 2003 or later domain.

-or-

The computer is not running Windows 2003 or later.

-or-

The user is not a member of the domain the computer is attached to.

Remarks

A UPN has the format username@domainname.com, in other words, an email address. The UPN identified in sUserPrincipalName is used to retrieve a token for that user through the Windows API LsaLogonUser function. In turn that token is used to identify the user. An exception might be returned due to the inability to log on using the supplied UPN.

Note

This constructor is intended for use only on computers joined to Windows Server 2003 or later domains. An exception is thrown for earlier domain types. This restriction is due to the fact that this constructor uses the KERB_S4U_LOGON structure, which was first introduced in Windows Server 2003. Also, this constructor requires read access to the token-groups-global-and-universal (TGGAU) attribute on the target user account.

Applies to

WindowsIdentity(IntPtr, String)

Initializes a new instance of the WindowsIdentity class for the user represented by the specified Windows account token and the specified authentication type.

public:
 WindowsIdentity(IntPtr userToken, System::String ^ type);
public WindowsIdentity (IntPtr userToken, string type);
new System.Security.Principal.WindowsIdentity : nativeint * string -> System.Security.Principal.WindowsIdentity
Public Sub New (userToken As IntPtr, type As String)

Parameters

userToken
IntPtr

nativeint

The account token for the user on whose behalf the code is running.

type
String

(Informational use only.) The type of authentication used to identify the user.

Exceptions

userToken is 0.

-or-

userToken is duplicated and invalid for impersonation.

The caller does not have the correct permissions.

-or-

A Win32 error occurred.

Examples

The following code shows the use of the WindowsIdentity constructor to create a new instance of the WindowsIdentity class for the user represented by the specified Windows account token and the specified authentication type. This code example is part of a larger example provided for the WindowsIdentity class.

void IntPtrStringConstructor( IntPtr logonToken )
{
   
   // Construct a WindowsIdentity object using the input account token 
   // and the specified authentication type.
   String^ authenticationType = "WindowsAuthentication";
   WindowsIdentity^ windowsIdentity = gcnew WindowsIdentity( logonToken,authenticationType );
   
   Console::WriteLine( "Created a Windows identity object named {0}.", windowsIdentity->Name );
}
private static void IntPtrStringConstructor(IntPtr logonToken)
{
    // Construct a WindowsIdentity object using the input account token 
    // and the specified authentication type.
    string authenticationType = "WindowsAuthentication";
    WindowsIdentity windowsIdentity =
                    new WindowsIdentity(logonToken, authenticationType);

    Console.WriteLine("Created a Windows identity object named " +
        windowsIdentity.Name + ".");
}
Private Sub IntPtrStringConstructor(ByVal logonToken As IntPtr)
    ' Construct a WindowsIdentity object using the input account token 
    ' and the specified authentication type
    Dim authenticationType = "WindowsAuthentication"
    Dim windowsIdentity As _
        New WindowsIdentity(logonToken, authenticationType)

    WriteLine("Created a Windows identity object named " + _
        windowsIdentity.Name + ".")
End Sub

Remarks

The following table shows initial property values for an instance of WindowsIdentity.

Property Initial value
WindowsAccountType Normal
IsAuthenticated false

The value of the type parameter is used to set the AuthenticationType parameter. If type is null, the security system sets AuthenticationType to Negotiate on Windows Vista and later versions of the Windows operating system, and to Kerberos on earlier versions of the Windows operating system. The security system does not use this value; it is for informational use only.

Note

You can retrieve the token represented by userToken by calling unmanaged code such as the Windows API LogonUser function. Always release userToken by calling the Windows API CloseHandle function. For more information on calling unmanaged code, see Consuming Unmanaged DLL Functions.

Applies to

WindowsIdentity(SerializationInfo, StreamingContext)

Caution

This API supports obsolete formatter-based serialization. It should not be called or extended by application code.

Initializes a new instance of the WindowsIdentity class for the user represented by information in a SerializationInfo stream.

public:
 WindowsIdentity(System::Runtime::Serialization::SerializationInfo ^ info, System::Runtime::Serialization::StreamingContext context);
public WindowsIdentity (System.Runtime.Serialization.SerializationInfo info, System.Runtime.Serialization.StreamingContext context);
[System.Obsolete("This API supports obsolete formatter-based serialization. It should not be called or extended by application code.", DiagnosticId="SYSLIB0051", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
public WindowsIdentity (System.Runtime.Serialization.SerializationInfo info, System.Runtime.Serialization.StreamingContext context);
new System.Security.Principal.WindowsIdentity : System.Runtime.Serialization.SerializationInfo * System.Runtime.Serialization.StreamingContext -> System.Security.Principal.WindowsIdentity
[<System.Obsolete("This API supports obsolete formatter-based serialization. It should not be called or extended by application code.", DiagnosticId="SYSLIB0051", UrlFormat="https://aka.ms/dotnet-warnings/{0}")>]
new System.Security.Principal.WindowsIdentity : System.Runtime.Serialization.SerializationInfo * System.Runtime.Serialization.StreamingContext -> System.Security.Principal.WindowsIdentity
Public Sub New (info As SerializationInfo, context As StreamingContext)

Parameters

info
SerializationInfo

The object containing the account information for the user.

context
StreamingContext

An object that indicates the stream characteristics.

Attributes

Exceptions

A WindowsIdentity cannot be serialized across processes.

The caller does not have the correct permissions.

-or-

A Win32 error occurred.

Remarks

Important

Calling this method with untrusted data is a security risk. Call this method only with trusted data. For more information, see Validate All Inputs.

Applies to

WindowsIdentity(String, String)

Initializes a new instance of the WindowsIdentity class for the user represented by the specified User Principal Name (UPN) and the specified authentication type.

public:
 WindowsIdentity(System::String ^ sUserPrincipalName, System::String ^ type);
public WindowsIdentity (string sUserPrincipalName, string type);
new System.Security.Principal.WindowsIdentity : string * string -> System.Security.Principal.WindowsIdentity
Public Sub New (sUserPrincipalName As String, type As String)

Parameters

sUserPrincipalName
String

The UPN for the user on whose behalf the code is running.

type
String

(Informational use only.) The type of authentication used to identify the user.

Exceptions

Windows returned the Windows NT status code STATUS_ACCESS_DENIED.

There is insufficient memory available.

The caller does not have the correct permissions.

-or-

The computer is not attached to a Windows 2003 or later domain.

-or-

The computer is not running Windows 2003 or later.

-or-

The user is not a member of the domain the computer is attached to.

Remarks

The value of the type parameter is used to set the AuthenticationType parameter. If type is null, the security system sets AuthenticationType to Negotiate on Windows Vista and later versions of the Windows operating system, and to Kerberos on earlier versions of the Windows operating system. The security system does not use this value; it is for informational use only.

The UPN identified in sUserPrincipalName is used to retrieve a token for that user through the Windows API LsaLogonUser function. In turn that token is used to identify the user. An exception might be returned due to the inability to log on using the supplied UPN.

Note

This constructor is intended for use only on computers joined to Windows Server 2003 or later domains. An exception is thrown for earlier domain types. This restriction is due to the fact that this constructor uses the KERB_S4U_LOGON structure, which was first introduced in Windows Server 2003. Also, this constructor requires read access to the token-groups-global-and-universal (TGGAU) attribute on the target user account.

Applies to

WindowsIdentity(IntPtr, String, WindowsAccountType)

Initializes a new instance of the WindowsIdentity class for the user represented by the specified Windows account token, the specified authentication type, and the specified Windows account type.

public:
 WindowsIdentity(IntPtr userToken, System::String ^ type, System::Security::Principal::WindowsAccountType acctType);
public WindowsIdentity (IntPtr userToken, string type, System.Security.Principal.WindowsAccountType acctType);
new System.Security.Principal.WindowsIdentity : nativeint * string * System.Security.Principal.WindowsAccountType -> System.Security.Principal.WindowsIdentity
Public Sub New (userToken As IntPtr, type As String, acctType As WindowsAccountType)

Parameters

userToken
IntPtr

nativeint

The account token for the user on whose behalf the code is running.

type
String

(Informational use only.) The type of authentication used to identify the user.

acctType
WindowsAccountType

One of the enumeration values.

Exceptions

userToken is 0.

-or-

userToken is duplicated and invalid for impersonation.

The caller does not have the correct permissions.

-or-

A Win32 error occurred.

Examples

The following code shows the use of the WindowsIdentity constructor to create a new instance of the WindowsIdentity class for the user represented by the specified Windows account token, the specified authentication type, and the specified Windows account type. This code example is part of a larger example provided for the WindowsIdentity class.

void IntPtrStringTypeConstructor( IntPtr logonToken )
{
   
   // Construct a WindowsIdentity object using the input account token,
   // and the specified authentication type and Windows account type.
   String^ authenticationType = "WindowsAuthentication";
   WindowsAccountType guestAccount = WindowsAccountType::Guest;
   WindowsIdentity^ windowsIdentity = gcnew WindowsIdentity( logonToken,authenticationType,guestAccount );
   
   Console::WriteLine( "Created a Windows identity object named {0}.", windowsIdentity->Name );
}
private static void IntPtrStringTypeConstructor(IntPtr logonToken)
{
    // Construct a WindowsIdentity object using the input account token,
    // and the specified authentication type, and Windows account type.
    string authenticationType = "WindowsAuthentication";
    WindowsAccountType guestAccount = WindowsAccountType.Guest;
    WindowsIdentity windowsIdentity =
        new WindowsIdentity(logonToken, authenticationType, guestAccount);

    Console.WriteLine("Created a Windows identity object named " +
        windowsIdentity.Name + ".");
}
Private Sub IntPtrStringTypeConstructor(ByVal logonToken As IntPtr)
    ' Construct a WindowsIdentity object using the input account token,
    ' and the specified authentication type and Windows account type.
    Dim authenticationType As String = "WindowsAuthentication"
    Dim guestAccount As WindowsAccountType = WindowsAccountType.Guest
    Dim windowsIdentity As _
        New WindowsIdentity(logonToken, authenticationType, guestAccount)

    WriteLine("Created a Windows identity object named " + _
        windowsIdentity.Name + ".")
End Sub

Remarks

The following table shows initial property values for an instance of WindowsIdentity.

Property Initial Value
IsAuthenticated false

The value of the type parameter is used to set the AuthenticationType parameter. If type is null, the security system sets AuthenticationType to Negotiate on Windows Vista and later versions of the Windows operating system, and to Kerberos on earlier versions of the Windows operating system. The security system does not use this value; it is for informational use only.

Note

You can retrieve the token represented by userToken by calling unmanaged code such as the Windows API LogonUser function. Always release userToken by calling the Windows API CloseHandle function. For more information on calling unmanaged code, see Consuming Unmanaged DLL Functions.

Applies to

WindowsIdentity(IntPtr, String, WindowsAccountType, Boolean)

Initializes a new instance of the WindowsIdentity class for the user represented by the specified Windows account token, the specified authentication type, the specified Windows account type, and the specified authentication status.

public:
 WindowsIdentity(IntPtr userToken, System::String ^ type, System::Security::Principal::WindowsAccountType acctType, bool isAuthenticated);
public WindowsIdentity (IntPtr userToken, string type, System.Security.Principal.WindowsAccountType acctType, bool isAuthenticated);
new System.Security.Principal.WindowsIdentity : nativeint * string * System.Security.Principal.WindowsAccountType * bool -> System.Security.Principal.WindowsIdentity
Public Sub New (userToken As IntPtr, type As String, acctType As WindowsAccountType, isAuthenticated As Boolean)

Parameters

userToken
IntPtr

nativeint

The account token for the user on whose behalf the code is running.

type
String

(Informational use only.) The type of authentication used to identify the user.

acctType
WindowsAccountType

One of the enumeration values.

isAuthenticated
Boolean

true to indicate that the user is authenticated; otherwise, false.

Exceptions

userToken is 0.

-or-

userToken is duplicated and invalid for impersonation.

The caller does not have the correct permissions.

-or-

A Win32 error occurred.

Examples

The following code shows the use of the WindowsIdentity constructor to create a new instance of the WindowsIdentity class for the user represented by the specified Windows account token, the specified authentication type, the specified Windows account type, and the specified authentication status. This code example is part of a larger example provided for the WindowsIdentity class.

void IntPrtStringTypeBoolConstructor( IntPtr logonToken )
{
   
   // Construct a WindowsIdentity object using the input account token,
   // and the specified authentication type, Windows account type, and
   // authentication flag.
   String^ authenticationType = "WindowsAuthentication";
   WindowsAccountType guestAccount = WindowsAccountType::Guest;
   bool isAuthenticated = true;
   WindowsIdentity^ windowsIdentity = gcnew WindowsIdentity( logonToken,authenticationType,guestAccount,isAuthenticated );
   
   Console::WriteLine( "Created a Windows identity object named {0}.", windowsIdentity->Name );
}
private static void IntPrtStringTypeBoolConstructor(IntPtr logonToken)
{
    // Construct a WindowsIdentity object using the input account token,
    // and the specified authentication type, Windows account type, and
    // authentication flag.
    string authenticationType = "WindowsAuthentication";
    WindowsAccountType guestAccount = WindowsAccountType.Guest;
    bool isAuthenticated = true;
    WindowsIdentity windowsIdentity = new WindowsIdentity(
        logonToken, authenticationType, guestAccount, isAuthenticated);

    Console.WriteLine("Created a Windows identity object named " +
        windowsIdentity.Name + ".");
}
Private Sub IntPrtStringTypeBoolConstructor(ByVal logonToken As IntPtr)
    ' Construct a WindowsIdentity object using the input account token,
    ' and the specified authentication type, Windows account type, and
    ' authentication flag.
    Dim authenticationType As String = "WindowsAuthentication"
    Dim guestAccount As WindowsAccountType = WindowsAccountType.Guest
    Dim isAuthenticated As Boolean = True
    Dim windowsIdentity As New WindowsIdentity( _
        logonToken, authenticationType, guestAccount, isAuthenticated)

    WriteLine("Created a Windows identity object named " + _
        windowsIdentity.Name + ".")
End Sub

Remarks

The value of the type parameter is used to set the AuthenticationType parameter. If type is null, the security system sets AuthenticationType to Negotiate on Windows Vista and later versions of the Windows operating system, and to Kerberos on earlier versions of the Windows operating system. The security system does not use this value; it is for informational use only.

You can retrieve the token represented by userToken by calling unmanaged code such as the Windows API LogonUser function. Always release userToken by calling the Windows API CloseHandle function. For more information on calling unmanaged code, see Consuming Unmanaged DLL Functions.

Applies to