Basics of .NET Framework User Operations
The .NET Framework provides a role-based security implementation in the System.Security.Principal namespace, which you can use for authorizing and authenticating users in your application. This topic discusses how to work with application authorization in the .NET Framework and create IIdentity and IPrincipal objects to represent users.
An IIdentity encapsulates an authenticated user. An IPrincipal is a combination of the identity of the user and any roles he or she has. You can use the predefined identity and principal classes in the System.Security.Principal namespace or you can add custom authentication by creating classes that implement the interfaces.
To use these interfaces, you must fully qualify the interface names or import the appropriate namespaces by including the Imports statement(s) at the beginning of the affected source code file. For more information, see Imports Statement (.NET Namespace and Type).
Using Role-Based Security in .NET Framework Applications
Each application thread can have an associated principal object (accessible through the CurrentPrincipal property) that represents the security context of the user on whose behalf the code is running. A principal object encapsulates a user's user security context (or identity) object. Using two objects allows for a separation of authentication (in the identity object) and authorization (in the principal).
An identity object must implement the IIdentity interface. An identity object represents a particular user and exposes the following properties as required by the IIdentity interface: Name, IsAuthenticated, and AuthenticationType. Identity objects typically have additional private members that perform the user authentication.
A principal object must implement the IPrincipal interface. A principal object encapsulates the user's security context by exposing the following members as required by the IPrincipal interface: the IsInRole method, which performs authorization, and the Identity property, which provides access to the user's identity object.
Working with Identities
The .NET Framework provides four classes that implement the IIdentity interface:
Each class enables you to work with different kinds of user identities. To access the current WindowsIdentity object for an application that uses Windows authentication, use the static GetCurrent method of the WindowsIdentity class. You can also set the current thread's principal by calling the My.User.InitializeWithWindowsUser Method.
You can also create custom identity classes by implementing the IIdentity interface in your own custom class. For more information about creating custom identities, see Walkthrough: Implementing Custom Authentication and Authorization.
Working with Principals
The .NET Framework provides the IPrincipal interface to link user roles and identities. If your application performs authorization, it should use an object that implements IPrincipal. For example, the WindowsIdentity and GenericIdentity classes provide built-in implementations of IPrincipal. Alternatively, you can create your own custom principal classes based on IPrincipal.
You can link the current thread to an IPrincipal object by assigning the object to the thread's CurrentPrincipal property or the My.User.CurrentPrincipal Property. You can then perform an authorization check by testing whether the user is a member of a particular role. You do so by using the principal's IsInRole method.
ASP.NET applications handle IPrincipal objects differently than do other .NET Framework applications. ASP.NET creates the appearance of a session over the stateless HTTP protocol. As a part of this session, the IPrincipal object representing the user is available from the User property of the HttpContext object for all code executing the user's request. The common language runtime automatically updates CurrentPrincipal with the User value after the OnAuthenticate event of the Global.asax file. ASP.NET applications often use the User property to perform authorization checks.
Note
Manually changing User automatically updates the CurrentPrincipal property for all threads executing within the same HTTP context. However, changing CurrentPrincipal does not affect the User property. It affects only the chosen thread for the remainder of the request.
In ASP.NET applications, the My.User.CurrentPrincipal Property updates the User property.
For more information about creating your own IPrincipal types, see Walkthrough: Implementing Custom Authentication and Authorization.
Granting Permissions to Work with IIdentity and IPrincipal Objects
Care should be used when granting permissions to work with IIdentity objects, because these objects make sensitive user-related information available. You should protect the application's current IPrincipal object from changes because the application's authorization capability is based on its current principal.
The .NET Framework provides this protection by requiring that these operations have code-access security permission. Grant the SecurityPermissionAttribute.ControlPrincipal permission to applications that need to manipulate these objects by using Code Access Security Policy Tool (Caspol.exe).
By default, all locally installed applications have this permission because they run under the FullTrust permission set.
Executing the following methods requires the ControlPrincipal permission:
See Also
Tasks
Walkthrough: Implementing Custom Authentication and Authorization
Reference
Other Resources
Authentication and Authorization in the .NET Framework with Visual Basic