Share via


Creating WindowsIdentity and WindowsPrincipal Objects

The WindowsIdentity object encapsulates information about Windows accounts. You use the WindowsIdentity object if you want to make authorization decisions based on a user's Windows account information. For example, using WindowsIdentity and WindowsPrincipal objects, you can write an application that requires all users to be currently validated by a Windows NT or Windows 2000 domain. You can also allow certain domain accounts to access your application while denying access to others.

There are two ways to create WindowsPrincipal objects, depending on whether code must repeatedly perform role-based validation or only needs to perform it once.

Creating WindowsPrincipal Objects for Repeated Validation

If code must repeatedly perform role-based validation, the following method produces less overhead.

  1. First, call the SetPrincipalPolicy method on the System.AppDomain object, passing it a PrincipalPolicy enumeration value that indicates what the new policy should be. Supported values are NoPrincipal, UnauthenticatedPrincipal, and WindowsPrincipal. The following code demonstrates this call.

    AppDomain.CurrentDomain.SetPrincipalPolicy(PrincipalPolicy.WindowsPrincipal);
    [Visual Basic]
    AppDomain.CurrentDomain.SetPrincipalPolicy(PrincipalPolicy.WindowsPrincipal)
    
  2. With the policy set, use the Thread.CurrentPrincipal property to retrieve the principal that encapsulates the current Windows user. The following code initializes a new WindowsPrincipal object to the value of the principal associated with the current thread.

    WindowsPrincipal MyPrincipal = (WindowsPrincipal) Thread.CurrentPrincipal
    [Visual Basic]
    Dim MyPrincipal As WindowsPrincipal = CType(Thread.CurrentPrincipal, WindowsPrincipal)
    

Creating WindowsPrincipal Objects for One Validation

When code only needs to make role-based validations once, you can create a WindowsPrincipal object by performing the following tasks.

  1. Initialize a new instance of the WindowsIdentity class by calling the WindowsIdentity.GetCurrent method, which queries the current Windows account and places information about that account into the newly created identity object. The following code creates a new instance of the class and initializes it to the current authenticated user.

    WindowsIdentity MyIdentity = WindowsIdentity.GetCurrent();
    [Visual Basic]
    Dim MyIdentity As WindowsIdentity = WindowsIdentity.GetCurrent()
    
  2. Create a new instance of the Principal class and pass it the value of a WindowsIdentity object. The following code demonstrates the creation of a new WindowsPrincipal object initialized with the previously created WindowsIdentity object.

    WindowsPrincipal MyPrincipal = new WindowsPrincipal(MyIdentity);
    [Visual Basic]
    Dim MyPrincipal As New WindowsPrincipal(MyIdentity)
    
  3. When the principal object has been created, you can use one of several methods to validate it. For more information, see Role-Based Security Checks.

The following code example creates a WindowsIdentity object and a WindowsPrincipal object and displays the information to the console. You can use this code to query the values of the WindowsIdentity and WindowsPrincipal that are produced by your network environment.

    using System;
    using System.Threading;
    using System.Security.Principal;
    public class Class1
    {

        public static int Main(string[] args)
        {
         //Get the current identity and put it into an identity object.
         WindowsIdentity MyIdentity = WindowsIdentity.GetCurrent();

         //Put the previous identity into a principal object.
         WindowsPrincipal MyPrincipal = new WindowsPrincipal(MyIdentity);

         //Principal values.
         string Name = MyPrincipal.Identity.Name;
         string Type = MyPrincipal.Identity.AuthenticationType;
         string Auth = MyPrincipal.Identity.IsAuthenticated.ToString();

         //Identity values.
         string IdentName = MyIdentity.Name;
         string IdentType = MyIdentity.AuthenticationType;
         string IdentIsAuth = MyIdentity.IsAuthenticated.ToString();
         string ISAnon = MyIdentity.IsAnonymous.ToString();
         string IsG = MyIdentity.IsGuest.ToString();
         string IsSys = MyIdentity.IsSystem.ToString();
         string Token = MyIdentity.Token.ToString();

         //Print the values.
         Console.WriteLine("Principal Values for current thread:");
         Console.WriteLine("\n\nPrincipal Name: {0}", Name);
         Console.WriteLine("Principal Type: {0}", Type);
         Console.WriteLine("Principal IsAuthenticated: {0}", Auth);

         Console.WriteLine("\n\nIdentity Values for current thread:");
         Console.WriteLine("Identity Name: {0}", IdentName);
         Console.WriteLine("Identity Type: {0}", IdentType);
         Console.WriteLine("Identity IsAuthenticated: {0}", IdentIsAuth);
         Console.WriteLine("\n\nIdentity IsAnonymous: {0}", ISAnon);
         Console.WriteLine("Identity IsGuest: {0}", IsG);
         Console.WriteLine("Identity IsSystem: {0}", IsSys);
         Console.WriteLine("Identity Token: {0}", Token);
         return 0;
        }
    }
[Visual Basic]
Imports System
Imports System.Threading
Imports System.Security.Principal
Imports Microsoft.VisualBasic

Public Class Class1
    
    Public Shared Sub Main()
        'Get the current identity and put it into an identity object.
        Dim MyIdentity As WindowsIdentity = WindowsIdentity.GetCurrent()
        
        'Put the previous identity into a principal object.
        Dim MyPrincipal As New WindowsPrincipal(MyIdentity)
        
        'Principal values.
        Dim PrincipalName As String = MyPrincipal.Identity.Name
        Dim PrincipalType As String = MyPrincipal.Identity.AuthenticationType
        Dim PrincipalAuth As String = MyPrincipal.Identity.IsAuthenticated.ToString()
        
        'Identity values.
        Dim IdentName As String = MyIdentity.Name
        Dim IdentType As String = MyIdentity.AuthenticationType
        Dim IdentIsAuth As String = MyIdentity.IsAuthenticated.ToString()
        Dim ISAnon As String = MyIdentity.IsAnonymous.ToString()
        Dim IsG As String = MyIdentity.IsGuest.ToString()
        Dim IsSys As String = MyIdentity.IsSystem.ToString()
        Dim Token As String = MyIdentity.Token.ToString()
        
        'Print the values.
        Console.WriteLine("Principal Values for current thread:")
        Console.WriteLine(ControlChars.CrLf + ControlChars.CrLf + "Principal Name: {0}", PrincipalName)
        Console.WriteLine("Principal Type: {0}", PrincipalType)
        Console.WriteLine("Principal IsAuthenticated: {0}", PrincipalAuth)
        
        Console.WriteLine(ControlChars.CrLf + ControlChars.CrLf + "Identity Values for current thread:")
        Console.WriteLine("Identity Name: {0}", IdentName)
        Console.WriteLine("Identity Type: {0}", IdentType)
        Console.WriteLine("Identity IsAuthenticated: {0}", IdentIsAuth)
        Console.WriteLine(ControlChars.CrLf + ControlChars.CrLf + "Identity IsAnonymous: {0}", ISAnon)
        Console.WriteLine("Identity IsGuest: {0}", IsG)
        Console.WriteLine("Identity IsSystem: {0}", IsSys)
        Console.WriteLine("Identity Token: {0}", Token)
    End Sub
    
End Class

When compiled and executed, the previous code displays output similar to the following (the actual values will vary from one network environment to another). Note that the Name, Type, and IsAuthenticated values will always be the same for the WindowsPrincipal and WindowsIdentity objects.

Principal Values for current thread:

Principal Name: MYDOMAIN\myuseraccount
Principal Type: NTLM
Principal IsAuthenticated: True

Identity Values for current thread:

Identity Name: MYDOMAIN\myuseraccount
Identity Type: NTLM
Identity IsAuthenticated: True

Identity IsAnonymous: False
Identity IsGuest: False
Identity IsSystem: False
Identity Token: 276

See Also

WindowsIdentity | WindowsPrincipal | Role-Based Security Checks | Principal and Identity Objects