IServerSecurity
A version of this page is also available for
4/8/2010
This interface is used by a server to help authenticate the client and to manage impersonation of the client.
When a client calls a server, the server can call CoGetCallContext to get a pointer to the IServerSecurity interface implemented on the call context object for the current method call. This pointer can be used to call an IServerSecurity method that allows the server to check the client's authentication or to impersonate the client.
The pointer to the instance of IServerSecurity returned by CoGetCallContext is automatically deleted when the server sends the reply back to the client. Therefore, the IServerSecurity object is valid only for the duration of the call. The IServerSecurity pointer must be released when it is no longer needed.
When to Implement
The stub management code in the system provides an implementation of IServerSecurity for objects by default as part of each incoming call, so typically you would not implement this interface.
You can choose to implement IServerSecurity on the custom stubs of objects that support custom marshaling to maintain a consistent programming model for their objects.
Before dispatching an arriving call, custom marshalers call CoSwitchCallContext, specifying a new context object (which must implement IServerSecurity). The original call context must be restored after the server object sends a reply.
When to Use
The methods of the IServerSecurity interface are called by a server object to examine the security settings of a particular call between a client and the server object (QueryBlanket) or to impersonate the client (ImpersonateClient and RevertToSelf).
A server impersonates a client by running in the client's security context, which allows the server to test the privilege level of the calling client and to access resources (such as files) as the client.
For more information about how impersonation works, see Impersonation and Cloaking.
The information obtained through IServerSecurity also allows an object to perform security checks in addition to the automatic ACL checks COM performs. For example, an application may want to allow time of day access to some objects or have a different ACL for each method on an object.
IServerSecurity methods can be called only before the remote procedure call completes.
Methods in Vtable Order
| IUnknown method | Description |
|---|---|
Returns pointers to supported interfaces. |
|
Increments the reference count. |
|
Decrements the reference count. |
| Method | Description |
|---|---|
Called by the server to find out about the client that invoked one of its methods. |
|
Allows a server to impersonate a client for the duration of a call. |
|
Restores the authentication information on a thread. |
|
Indicates whether the server is currently impersonating the client. |
Remarks
To determine whether the platform supports this interface, see Determining Supported COM APIs.
Requirements
| Header | objidl.h, objidl.idl |
| Library | ole32.lib, uuid.lib |
| Windows Embedded CE | Windows CE 3.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |