NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Principal and Identity Objects

Managed code can discover the identity or the role of a principal through a Principal object, which contains a reference to an Identity object. The runtime attaches a Principal object to the call context when a new thread is created and flows the call context properties between threads as they are sequentially assigned to process a thread. Support for built-in, generic, and Windows principals are provided, as well as a framework for implementing custom Principal and Identity objects. In the discussion that follows, Principal object means an instance of a class that implements IPrincipal, and Identity object means an instance of a class that implements IPrincipal.

The following classes and interfaces are discussed briefly (for detailed reference information about a specific class or interface, click a link in the list):

The IPrincipal interface defines a property for accessing an associated Identity object as well as a method for determining whether the user identified by the Identity object is a member of a given role. All Principal classes implement the IPrincipal interface as well as any additional properties and methods that are necessary. For example, the runtime provides the WindowsPrincipal class, which implements additional functionality for mapping Windows NT or Windows 2000 group membership to roles. All Identity classes implement the IIdentity interface, which defines properties for accessing a name and an authentication type that indicates the authentication mechanism used to generate the identity information (such as Kerberos V5 or NTLM). There is no required relationship between an Identity object and the Windows NT process token under which a thread is currently executing. However, if the Identity object is a WindowsIdentity object, then the identity is assumed to represent a Windows NT token.

A Principal object is bound to a call context (CallContext) object within an application domain (AppDomain). A default call context is always created with each new AppDomain, so there is always a call context available to accept the Principal object. When a new thread is created, a CallContext object is created for the new thread. The Principal object reference is automatically copied from the creating thread to the new thread's CallContext. If it cannot be determined which Principal object belongs to the creator of the thread, the runtime follows the default policy for Principal and Identity object creation.

A configurable application domain-specific policy defines the rules for deciding which Principal object to associate with a thread of execution that is transitioning into a new application domain. If appropriate, the application domain security policy can be modified to specify that when the host is a highly trusted one (such as ASP+), the host provides the Principal and Identity objects to the runtime. In circumstances where security policy permits it, the runtime can create Principal and Identity objects that reflect the operating system token associated with the current thread of execution. But by default, the runtime uses Principal and Identity objects that represent unauthenticated users. The runtime does not create these default Principal and Identity objects until the code attempts to access them. Depending on policy settings, the runtime can also create special Principal and Identity objects that support interoperation with COM+ 1.0 security.

Principal objects are not transmitted between machines or between processes. Instead, the appropriate user credentials, as defined by the called application, are transmitted so that the correct Principal and Identity objects can be constructed for the caller's context. In some cases, the remoting infrastructure automatically determines the correct credentials to transmit. In others, a user interface requests credentials, such as name and password, certificate, etc. When transmitting a Principal object across application domains, but within the same process, the remoting infrastructure copies a reference to the Principal object associated with the caller's context to the callee's context.

You can neither modify nor destroy Principal and Identity objects after they have been constructed: garbage collection will destroy them when they are no longer referenced.