13.13 Determine if the Current User Is a Member of a Specific Windows Group

Problem

You need to determine if the current user of your application is a member of a specific Windows user group.

Solution

Obtain a System.Security.Principal.WindowsIdentity object representing the current Windows user by calling the static method WindowsIdentity.GetCurrent . Then pass the returned WindowsIdentity object to the constructor of the System.Security.Principal.WindowsPrincipal class to obtain a WindowsPrincipal object. Finally, call the method IsInRole of the WindowsPrincipal object to determine if the user is in a specific Windows group.

Discussion

The RBS mechanism of the .NET Framework abstracts the user-based security features of the underlying operating system through the following two key interfaces:

System.Security.Principal.IIdentity
System.Security.Principal.IPrincipal

The IIdentity interface represents the entity on whose behalf code is running, for example a user or service account. The IPrincipal interface represents the entity's IIdentity and the set of roles to which the entity belongs. A role is simply a categorization used to group entities with similar security capabilities, such as a Windows user group.

To integrate RBS with Windows user security, the .NET Framework provides the following two Windows-specific classes that implement the IIdentity and IPrincipal interfaces:

System.Security.Principal.WindowsIdentity
System.Security.Principal.WindowsPrincipal

The WindowsIdentity class implements the IIdentity interface and represents a Windows user. The WindowsPrincipal class implements IPrincipal and represents the set of Windows groups to which the user belongs. Because .NET RBS is a generic solution designed to be platform independent, you have no access to the features and capabilities of the Windows user account through the IIdentity and IPrincipal interfaces, and you must frequently use the WindowsIdentity and WindowsPrincipal objects directly.

To determine if the current user is a member of a specific Windows group, you must first call the static method WindowsIdentity.GetCurrent . The GetCurrent method returns a WindowsIdentity object that represents the Windows user on whose behalf the current thread is running. Next instantiate a new WindowsPrincipal object and pass the WindowsIdentity object as an argument to the constructor. Finally, call the IsInRole method of the WindowsPrincipal object to test if the user is in a specific group (role). IsInRole returns true if the user is a member of the specified group, otherwise false .

Note

You might be able to obtain an IPrincipal reference to a WindowsPrincipal object that represents the current user by getting the static property CurrentPrincipal of the class System.Threading.Thread . However, this technique depends on the principal policy configuration of the current application domain; recipe 13.14 discusses this in more detail.

The IsInRole method provides three overloads. The first overload takes a string containing the name of the group for which you want to test. The group name must be of the form [DomainName]\[GroupName] for domain-based groups and [MachineName]\[GroupName] for locally defined groups. If you want to test for membership of a standard Windows group, use the form BUILTIN\[GroupName]. IsInRole performs a case-insensitive test for the specified group name.

The second IsInRole overload accepts an int , which specifies a Windows Role Identifier (RID). RIDs provide a mechanism to identify groups that is independent of language and localization. The third IsInRole overload accepts a member of the System.Security.Principal.WindowsBuiltInRole enumeration. The WindowsBuiltInRole enumeration defines a set of members that represent each of the built-in Windows groups. Table 13.3 lists the name, RID, and WindowsBuiltInRole value for each of the standard Windows groups.

Table 13.3: Windows Built-In Account Names and Identifiers
Account Name	RID (Hex)	WindowsBuiltInRole Value
BUILTIN\Account Operators	0x224	AccountOperator
BUILTIN\Administrators	0x220	Administrator
BUILTIN\Backup Operators	0x227	BackupOperator
BUILTIN\Guests	0x222	Guest
BUILTIN\Power Users	0x223	PowerUser
BUILTIN\Print Operators	0x226	PrintOperator
BUILTIN\Replicators	0x228	Replicator
BUILTIN\Server Operators	0x225	SystemOperator
BUILTIN\Users	0x221	User

Note

The WindowsIdentity class provides overloaded constructors that when running on Microsoft Windows Server 2003 or later platforms allow you to obtain a WindowsIdentity object representing a named user. You can use this WindowsIdentity object and the process described in this recipe to determine if that user is a member of a specific Windows group.

If you try to use one of these constructors when running on an earlier version of Windows, the WindowsIdentity constructor will throw the exception System.ArgumentException . On Windows platforms preceding Windows Server 2003, you must use native code to obtain a Windows access token representing the desired user. You can then use this access token to instantiate a WindowsIdentity object; recipe 13.15 explains how to obtain Windows access tokens for specific users.

The WindowsGroupExample application shown here demonstrates how to test whether the current user is a member of a set of named Windows groups. You specify the groups that you want to test for as command-line arguments; remember to prefix the group name with the machine or domain name, or BUILTIN for standard Windows groups.

 using System; using System.Security.Principal; public class WindowsGroupExample {     public static void Main (string[] args) {              // Obtain a WindowsIdentity object representing the currently         // logged on Windows user.         WindowsIdentity identity = WindowsIdentity.GetCurrent();                  // Create a WindowsPrincipal object that represents the security         // capabilities of the specified WindowsIdentity, in this case         // the Windows groups to which the current user belongs.         WindowsPrincipal principal = new WindowsPrincipal(identity);                  // Iterate through the group names specified as command-line          // arguments and test to see if the current user is a member of          // each one.         foreach (string role in args) {                      Console.WriteLine("Is {0} a member of {1}? = {2}",                  identity.Name, role, principal.IsInRole(role));         }     } }

If you run this example as a user named Darryl on a computer named MACHINE using the command WindowsGroupExample BUILTIN\Administrators BUILTIN\Users MACHINE\Accountants , you will see console output similar to the following.

 Is MACHINE\Darryl a member of BUILTIN\Administrators? = False Is MACHINE\Darryl a member of BUILTIN\Users? = True Is MACHINE\Darryl a member of MACHINE\Accountants? = True