Developing Authorization Manager Applications
Applies To: Windows Server 2003 with SP1
Server applications use Authorization Manager runtime interfaces to manage connections to the authorization policy store and validate client requests
Initialization
When the application runs, it initializes the Authorization Manager policy store using the IAzAuthorizationStore::Initialize interface. The application should have Read access to the authorization store, but does not need Write access. After connecting to the store, the application calls IAzApplication::Initialize to initialize an interface to its specific application within the policy store.
Client connection
When a client connects to the application, an Authorization Manager context must be created for the user. To do this, use the IAzApplication::IntiializeClientContextFromToken, IAzApplication::AzInitializeClientContextFromStringSID, or the IAzApplication::InitializeClientContextFromName method. Generally, if a token is available, you should use a token when creating a context. A token is usually the result of a Windows logon and will contain logon information, such as whether it was an interactive or a network logon. Context creation from a token is usually faster because it does not have to query a domain controller for group information. In rare cases, it is possible that role assignment may have been given depending on these logon properties, so when possible, use the FromToken form of InitializeClientContext APIs. For example, when a user logs on to the network interactively, the NT AUTHORITY\INTERACTIVE group is added to the resulting token. Using the InitializeClientContextFromName (or SID) method, an IAzClientContext object is created by looking up the users group assignments in Active Directory. Since the user has not logged on, the context will not contain groups such as the NT AUTHORITY\INTERACTIVE group that identifies the logon type. In this case, if membership in a group or role is given to the interactive group, a user context that is created using InitializeClientContextFromName does not receive the membership. It is recommended that you do not use these logon property groups to secure resources or specify memberships in groups or roles, in which case InitializeClientContextFromName and InitializeClientContextFromSID can be used.
The AzInitializeClientContextFromStringSID method creates an Authorization Manager context from a given SID in textual form. This behaves in a similar manner as the InitializeClientContextFromName method. When the AZ_CLIENT_CONTEXT_SKIP_GROUP flag is used, the AzInitializeClientContextFromStringSID method does not attempt to determine the group memberships of the given SID. The resulting client context only contains the specified SID. If the IAzAccessCheck method is called from this client context instance, role membership is only granted if the specified SID is used as a member of a role or group assigned to a role.
Roles query and authorization
After a client context is created, applications have the option of querying role information about the user in order to present a user interface based on the users role memberships. For example a Web-based application may render a Manager user interface for people in the Manager role, and an employee role for everyone else. The IAzClientContext::GetRoles method enumerates the users role memberships. The set of roles that is returned from GetRoles is based only on explicit membership assignment; GetRoles does not evaluate BizRules.
When the user makes a request, the application maps the request to the required operations and determines the scope in which the user is making the request. Then the application calls AccessCheck sending the scope, requested operations, BizRule parameters, and object name. The scope determines the users role membership, which determines whether or not access is granted to the user.