WindowsPrincipal.IsInRole Method

Definition

Namespace:

System.Security.Principal

Assembly:

System.Security.Principal.Windows.dll

Determines whether the current principal belongs to a specified Windows user group.

Overloads

IsInRole(Int32)	Determines whether the current principal belongs to the Windows user group with the specified relative identifier (RID).
IsInRole(SecurityIdentifier)	Determines whether the current principal belongs to the Windows user group with the specified security identifier (SID).
IsInRole(WindowsBuiltInRole)	Determines whether the current principal belongs to the Windows user group with the specified WindowsBuiltInRole.
IsInRole(String)	Determines whether the current principal belongs to the Windows user group with the specified name.

Remarks

There are four overloads for this method. For performance reasons, the IsInRole(SecurityIdentifier) overload is strongly recommended.

IsInRole(Int32)

Determines whether the current principal belongs to the Windows user group with the specified relative identifier (RID).

public:
 virtual bool IsInRole(int rid);

public virtual bool IsInRole (int rid);

override this.IsInRole : int -> bool

Public Overridable Function IsInRole (rid As Integer) As Boolean

Parameters

rid

Int32

The RID of the Windows user group in which to check for the principal's membership status.

Returns

Boolean

true if the current principal is a member of the specified Windows user group, that is, in a particular role; otherwise, false.

Examples

The following code example demonstrates the use of the IsInRole methods. The WindowsBuiltInRole enumeration is used as the source for the RIDs that identify the built-in roles. The RIDs are used to determine the roles of the current principal.

public:
   static void DemonstrateWindowsBuiltInRoleEnum()
   {
      AppDomain^ myDomain = Thread::GetDomain();

      myDomain->SetPrincipalPolicy( PrincipalPolicy::WindowsPrincipal );
      WindowsPrincipal^ myPrincipal = dynamic_cast<WindowsPrincipal^>(Thread::CurrentPrincipal);

      Console::WriteLine( "{0} belongs to: ", myPrincipal->Identity->Name );

      Array^ wbirFields = Enum::GetValues( WindowsBuiltInRole::typeid );

      for each ( Object^ roleName in wbirFields )
      {
         try
         {
            Console::WriteLine( "{0}? {1}.", roleName,
               myPrincipal->IsInRole(  *dynamic_cast<WindowsBuiltInRole^>(roleName) ) );
         }
         catch ( Exception^ ) 
         {
            Console::WriteLine( "{0}: Could not obtain role for this RID.",
               roleName );
         }
      }
   }

using System;
using System.Threading;
using System.Security.Permissions;
using System.Security.Principal;

class SecurityPrincipalDemo
{
    public static void DemonstrateWindowsBuiltInRoleEnum()
    {
        AppDomain myDomain = Thread.GetDomain();

        myDomain.SetPrincipalPolicy(PrincipalPolicy.WindowsPrincipal);
        WindowsPrincipal myPrincipal = (WindowsPrincipal)Thread.CurrentPrincipal;
        Console.WriteLine("{0} belongs to: ", myPrincipal.Identity.Name.ToString());
        Array wbirFields = Enum.GetValues(typeof(WindowsBuiltInRole));
        foreach (object roleName in wbirFields)
        {
            try
            {
                // Cast the role name to a RID represented by the WindowsBuildInRole value.
                Console.WriteLine("{0}? {1}.", roleName,
                    myPrincipal.IsInRole((WindowsBuiltInRole)roleName));
                Console.WriteLine("The RID for this role is: " + ((int)roleName).ToString());
            }
            catch (Exception)
            {
                Console.WriteLine("{0}: Could not obtain role for this RID.",
                    roleName);
            }
        }
        // Get the role using the string value of the role.
        Console.WriteLine("{0}? {1}.", "Administrators",
            myPrincipal.IsInRole("BUILTIN\\" + "Administrators"));
        Console.WriteLine("{0}? {1}.", "Users",
            myPrincipal.IsInRole("BUILTIN\\" + "Users"));
        // Get the role using the WindowsBuiltInRole enumeration value.
        Console.WriteLine("{0}? {1}.", WindowsBuiltInRole.Administrator,
           myPrincipal.IsInRole(WindowsBuiltInRole.Administrator));
        // Get the role using the WellKnownSidType.
        SecurityIdentifier sid = new SecurityIdentifier(WellKnownSidType.BuiltinAdministratorsSid, null);
        Console.WriteLine("WellKnownSidType BuiltinAdministratorsSid  {0}? {1}.", sid.Value, myPrincipal.IsInRole(sid));
    }

    public static void Main()
    {
        DemonstrateWindowsBuiltInRoleEnum();
    }
}

Imports System.Threading
Imports System.Security.Permissions
Imports System.Security.Principal

Class SecurityPrincipalDemo

    Public Shared Sub DemonstrateWindowsBuiltInRoleEnum()
        Dim myDomain As AppDomain = Thread.GetDomain()

        myDomain.SetPrincipalPolicy(PrincipalPolicy.WindowsPrincipal)
        Dim myPrincipal As WindowsPrincipal = CType(Thread.CurrentPrincipal, WindowsPrincipal)
        Console.WriteLine("{0} belongs to: ", myPrincipal.Identity.Name.ToString())
        Dim wbirFields As Array = [Enum].GetValues(GetType(WindowsBuiltInRole))
        Dim roleName As Object
        For Each roleName In wbirFields
            Try
                ' Cast the role name to a RID represented by the WindowsBuildInRole value.
                Console.WriteLine("{0}? {1}.", roleName, myPrincipal.IsInRole(CType(roleName, WindowsBuiltInRole)))
                Console.WriteLine("The RID for this role is: " + Fix(roleName).ToString())

            Catch
                Console.WriteLine("{0}: Could not obtain role for this RID.", roleName)
            End Try
        Next roleName
        ' Get the role using the string value of the role.
        Console.WriteLine("{0}? {1}.", "Administrators", myPrincipal.IsInRole("BUILTIN\" + "Administrators"))
        Console.WriteLine("{0}? {1}.", "Users", myPrincipal.IsInRole("BUILTIN\" + "Users"))
        ' Get the role using the WindowsBuiltInRole enumeration value.
        Console.WriteLine("{0}? {1}.", WindowsBuiltInRole.Administrator, myPrincipal.IsInRole(WindowsBuiltInRole.Administrator))
        ' Get the role using the WellKnownSidType.
        Dim sid As New SecurityIdentifier(WellKnownSidType.BuiltinAdministratorsSid, Nothing)
        Console.WriteLine("WellKnownSidType BuiltinAdministratorsSid  {0}? {1}.", sid.Value, myPrincipal.IsInRole(sid))

    End Sub

    Public Shared Sub Main()
        DemonstrateWindowsBuiltInRoleEnum()

    End Sub
End Class

Remarks

When testing for newly created role information, such as a new user or a new group, it is important to log out and log in to force the propagation of role information within the domain. Not doing so can cause the IsInRole test to return false.

For performance reasons, the IsInRole(SecurityIdentifier) overload is recommended as the preferable overload for determining the user's role.

Note

In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the IsInRole method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator.

Relative identifiers (RIDs) are components of a Windows user group's security identifier (SID) and are supported to help prevent cross-platform localization issues. Many user accounts, local groups, and global groups have a default RID value that is constant across all versions of Windows.

For example, the RID for the BUILTIN\Administrators role is 0x220. Using 0x220 as the input parameter for the IsInRole method results in true being returned if the current principal is an administrator.

The following tables list the default RID values.

Built-in users	RID
DOMAINNAME\Administrator	0x1F4
DOMAINNAME\Guest	0x1F5

Built-in global groups	RID
DOMAINNAME\Domain Admins	0x200
DOMAINNAME\Domain Users	0x201
DOMAINNAME\Domain Guests	0x202

Built-in local groups	RID
BUILTIN\Administrators	0x220
BUILTIN\Users	0x221
BUILTIN\Guests	0x222
BUILTIN\Account Operators	0x224
BUILTIN\Server Operators	0x225
BUILTIN\Print Operators	0x226
BUILTIN\Backup Operators	0x227
BUILTIN\Replicator	0x228

IsInRole(SecurityIdentifier)

Determines whether the current principal belongs to the Windows user group with the specified security identifier (SID).

public:
 virtual bool IsInRole(System::Security::Principal::SecurityIdentifier ^ sid);

public virtual bool IsInRole (System.Security.Principal.SecurityIdentifier sid);

override this.IsInRole : System.Security.Principal.SecurityIdentifier -> bool

Public Overridable Function IsInRole (sid As SecurityIdentifier) As Boolean

Parameters

sid

SecurityIdentifier

A SecurityIdentifier that uniquely identifies a Windows user group.

Returns

Boolean

true if the current principal is a member of the specified Windows user group; otherwise, false.

Exceptions

ArgumentNullException

sid is null.

SecurityException

Windows returned a Win32 error.

Examples

The following code example demonstrates the use of the WindowsPrincipal.IsInRole(SecurityIdentifier) method. The BuiltinAdministratorsSid enumeration value is used to determine whether the current principal is an administrator. For the full code example, see the WindowsPrincipal.IsInRole(Int32) method.

// Get the role using the WellKnownSidType.
SecurityIdentifier sid = new SecurityIdentifier(WellKnownSidType.BuiltinAdministratorsSid, null);
Console.WriteLine("WellKnownSidType BuiltinAdministratorsSid  {0}? {1}.", sid.Value, myPrincipal.IsInRole(sid));

    ' Get the role using the WellKnownSidType.
    Dim sid As New SecurityIdentifier(WellKnownSidType.BuiltinAdministratorsSid, Nothing)
    Console.WriteLine("WellKnownSidType BuiltinAdministratorsSid  {0}? {1}.", sid.Value, myPrincipal.IsInRole(sid))

End Sub

Remarks

The SecurityIdentifier uniquely identifies a user or group on Windows. When testing for newly created role information, such as a new user or a new group, it is important to log out and log in to force the propagation of role information within the domain. Not doing so can cause the IsInRole test to return false.

Note

In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the IsInRole method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator.

For performance reasons, this is the preferable overload to determine a user's role.

IsInRole(WindowsBuiltInRole)

Determines whether the current principal belongs to the Windows user group with the specified WindowsBuiltInRole.

public:
 virtual bool IsInRole(System::Security::Principal::WindowsBuiltInRole role);

public virtual bool IsInRole (System.Security.Principal.WindowsBuiltInRole role);

override this.IsInRole : System.Security.Principal.WindowsBuiltInRole -> bool

Public Overridable Function IsInRole (role As WindowsBuiltInRole) As Boolean

Parameters

role

WindowsBuiltInRole

One of the WindowsBuiltInRole values.

Returns

Boolean

true if the current principal is a member of the specified Windows user group; otherwise, false.

Exceptions

ArgumentException

role is not a valid WindowsBuiltInRole value.

Examples

The following example uses the WindowsBuiltInRole enumeration is used to determine whether the current principal is an Administrator. For the full code example, see the WindowsPrincipal.IsInRole(Int32) method.

// Get the role using the WindowsBuiltInRole enumeration value.
Console.WriteLine("{0}? {1}.", WindowsBuiltInRole.Administrator,
   myPrincipal.IsInRole(WindowsBuiltInRole.Administrator));

' Get the role using the WindowsBuiltInRole enumeration value.
Console.WriteLine("{0}? {1}.", WindowsBuiltInRole.Administrator, myPrincipal.IsInRole(WindowsBuiltInRole.Administrator))

Remarks

When testing for newly created role information, such as a new user or a new group, it is important to log out and log in to force the propagation of role information within the domain. Not doing so can cause the IsInRole test to return false.

For performance reasons, the IsInRole(SecurityIdentifier) overload is recommended as the preferable overload for determining the user's role.

Note

In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the IsInRole method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator.

IsInRole(String)

Determines whether the current principal belongs to the Windows user group with the specified name.

public:
 override bool IsInRole(System::String ^ role);

public override bool IsInRole (string role);

override this.IsInRole : string -> bool

Public Overrides Function IsInRole (role As String) As Boolean

Parameters

role

String

The name of the Windows user group for which to check membership.

Returns

Boolean

true if the current principal is a member of the specified Windows user group; otherwise, false.

Examples

The following code example demonstrates the use of the WindowsPrincipal.IsInRole(String) method.

The strings BUILTIN\Administrators and BUILTIN\Users are used to determine whether the current principal is an administrator or a user. For the full code example, see the WindowsPrincipal.IsInRole(Int32) method.

// Get the role using the string value of the role.
Console.WriteLine("{0}? {1}.", "Administrators",
    myPrincipal.IsInRole("BUILTIN\\" + "Administrators"));
Console.WriteLine("{0}? {1}.", "Users",
    myPrincipal.IsInRole("BUILTIN\\" + "Users"));

' Get the role using the string value of the role.
Console.WriteLine("{0}? {1}.", "Administrators", myPrincipal.IsInRole("BUILTIN\" + "Administrators"))
Console.WriteLine("{0}? {1}.", "Users", myPrincipal.IsInRole("BUILTIN\" + "Users"))

Remarks

When testing for newly created role information, such as a new user or a new group, it is important to log out and log in to force the propagation of role information within the domain. Not doing so can cause the IsInRole test to return false.

For performance reasons, the IsInRole(SecurityIdentifier) overload is recommended as the preferable overload for determining the user's role.

Note

In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the IsInRole method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator.

For built-in roles, the role string should be in the form "BUILTIN\RoleNameHere". For example, to test for membership in the Windows administrator role, the string representing the role should be "BUILTIN\Administrators". Note that the backslash might need to be escaped. The following table lists the built-in roles.

Note

The spelling for the BUILTIN roles in string format differs from the spelling used in the WindowsBuiltInRole enumeration. For example, the spelling for an administrator in the enumeration is "Administrator", not "Administrators". When using this overload, use the spelling for the role from the following table.

Built-in local groups
BUILTIN\Administrators
BUILTIN\Users
BUILTIN\Guests
BUILTIN\Account Operators
BUILTIN\Server Operators
BUILTIN\Print Operators
BUILTIN\Backup Operators
BUILTIN\Replicator

For machine-specific roles, the role string should be in the form "MachineName\RoleNameHere".

For domain-specific roles, the role string should be in the form "DomainName\RoleNameHere"; for example, "SomeDomain\Domain Users".

Note

In the .NET Framework version 1.0, the role parameter is case-sensitive. In the .NET Framework version 1.1 and later, the role parameter is case-insensitive.

See also

• WindowsBuiltInRole