WindowsPrincipal.IsInRole Method
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Determines whether the current principal belongs to a specified Windows user group.
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. |
There are four overloads for this method. For performance reasons, the IsInRole(SecurityIdentifier) overload is strongly recommended.
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
abstract member IsInRole : int -> bool
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
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 |
Applies to
.NET 9 and other versions
Product | Versions |
---|---|
.NET | Core 1.0, Core 1.1, 6, 7, 8, 9 |
.NET Framework | 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1 |
.NET Standard | 2.0 (package-provided) |
Windows Desktop | 3.0, 3.1, 5 |
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);
[System.Runtime.InteropServices.ComVisible(false)]
public virtual bool IsInRole (System.Security.Principal.SecurityIdentifier sid);
override this.IsInRole : System.Security.Principal.SecurityIdentifier -> bool
[<System.Runtime.InteropServices.ComVisible(false)>]
abstract member IsInRole : System.Security.Principal.SecurityIdentifier -> bool
override this.IsInRole : System.Security.Principal.SecurityIdentifier -> bool
[<System.Runtime.InteropServices.ComVisible(false)>]
override this.IsInRole : System.Security.Principal.SecurityIdentifier -> bool
Public Overridable Function IsInRole (sid As SecurityIdentifier) As Boolean
Parameters
A SecurityIdentifier that uniquely identifies a Windows user group.
Returns
true
if the current principal is a member of the specified Windows user group; otherwise, false
.
- Attributes
Exceptions
sid
is null
.
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.
Applies to
.NET 9 and other versions
Product | Versions |
---|---|
.NET | Core 1.0, Core 1.1, 6, 7, 8, 9 |
.NET Framework | 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1 |
.NET Standard | 2.0 (package-provided) |
Windows Desktop | 3.0, 3.1, 5 |
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
abstract member IsInRole : System.Security.Principal.WindowsBuiltInRole -> bool
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
true
if the current principal is a member of the specified Windows user group; otherwise, false
.
Exceptions
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.
Applies to
.NET 9 and other versions
Product | Versions |
---|---|
.NET | Core 1.0, Core 1.1, 6, 7, 8, 9 |
.NET Framework | 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1 |
.NET Standard | 2.0 (package-provided) |
Windows Desktop | 3.0, 3.1, 5 |
Determines whether the current principal belongs to the Windows user group with the specified name.
public:
override bool IsInRole(System::String ^ role);
public:
virtual bool IsInRole(System::String ^ role);
public override bool IsInRole (string role);
public virtual bool IsInRole (string role);
override this.IsInRole : string -> bool
abstract member IsInRole : string -> bool
override this.IsInRole : string -> bool
Public Overrides Function IsInRole (role As String) As Boolean
Public Overridable Function IsInRole (role As String) As Boolean
Parameters
- role
- String
The name of the Windows user group for which to check membership.
Returns
true
if the current principal is a member of the specified Windows user group; otherwise, false
.
Implements
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
Applies to
.NET 9 and other versions
Product | Versions |
---|---|
.NET | Core 1.0, Core 1.1, 6, 7, 8, 9 |
.NET Framework | 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1 |
.NET Standard | 2.0 (package-provided) |
Windows Desktop | 3.0, 3.1, 5 |
.NET feedback
.NET is an open source project. Select a link to provide feedback: