Using Dynamic Business Rules in Windows Server 2003 Authorization Manager

  • Article

 

Mohan Rao Cavale
Microsoft Corporation

January 2003

Applies to:
   Microsoft® Windows Server™ 2003

Summary: An overview of the dynamic business rules capability of the new access control interface, Authorization Manager, introduced in Windows Server 2003. (9 printed pages.)

Contents

Introduction
Object-Based Access Control
Role-Based Access Control in Authorization Manager
BizRule Elements
Adding BizRules to Your Application
Conclusion

Introduction

Before Windows Server 2003, the authorization model was object-centric. Control was provided via access control lists (ACLs), with each object having an associated list of trustees (user account, group account, or logon session) with specific sets of rights for that object. The ACL-based access control works well for some types of applications. Resource managers that have well-defined persistent objects, such as the Windows NT® System Registry, work well with ACLs. The ACL can be attached to the object and access decisions can be made based on group membership in a token and the contents of the ACL. In these types of applications there is little need for any business rule logic such as time of day or other run-time variables that are relevant in the access decision.

A distinct authorization problem exists for Line of Business Web applications, such as an expense reporting application or a Web-based shopping application. For these applications, the authorization decisions are often not determining access to well-defined persistent objects, but are instead verifying a work flow, or verifying a set of multiple distinct operations, such as querying a database and sending e-mail. The access decisions are often made not just based on token group membership, but also on business logic, such as the amount submitted in an expense application, or verification of workflow completion. Applications that do not have well-defined persistent objects have no place to put an ACL. With Windows Server 2003, these dynamic access decisions are now readily available in the form of dynamic business rules ** ("BizRules") ** supplied by the Authorization Manager.

Object-Based Access Control

Traditionally, Windows server applications request access to resource objects on behalf of clients by impersonating the client in the resource request. That is, each application request for resources is passed to the resource using the security token belonging to the particular client connected to the application. Requests are granted or denied by the Resource Manager (RM) for the requested resource based on the ACL maintained for the resource.

Figure 1. User access permissions

When a client request comes in to the application requiring access to a resource protected by an RM, the RM impersonates the client and makes a call to the AccessCheck API. In turn, the AccessCheck API looks at the client security token, the desired access to the object and the security descriptor on the object. The AccessCheck API returns to the RM, responding "yes" or "no", providing the RM the ability to determine whether the client should be allowed to access the object. The attributes of the security descriptor of the object as well as the client security token have all been established prior to the client making the request. For example, the administrator has set the privileges on a file. There is no ability to dynamically affect the results of the access check based upon external factors such as time of day or requested dollar amount.

In addition, as server applications and environments have grown in complexity, the ACL-based access control scheme has become more complex to administer. For example, to support server applications, operating system resource ACLs must be continually maintained to grant application requests for the potentially broad and ever-changing groups of application clients. Both the application developer and system administrator must be adept at translating business logic into specific access control for all application required system objects.

Role-Based Access Control in Authorization Manager

Windows Server 2003, introduces a new role-based access control interface, Authorization Manager. The following are the goals of the Authorization Manager:

  • Simplify application access control administration.
  • Provide a simplified and natural development model.
  • Enable flexible and dynamic authorization decisions.

Applications using the Authorization Manager interface are organized internally to assume various roles pertinent to the tasks to be performed and to make access requests while impersonating these roles.

Figure 2. Authorization Manager user permissions

Under this system, logical roles and tasks are defined and maintained according to each application's needs. By representing the security model according to an organizational structure, access control administration becomes simpler. In addition, task and role definitions are conducive to modeling application workflows, giving developers a natural application-centric environment when utilizing Authorization Manager.

Authorization Manager has the additional ability of dynamically qualifying the permissions granted at run time. This allows for the access control decision to take into account run time data, such as the dollar amount of an expense requested or the inventory of a requested item, when granting access. This is achieved through an association of a BizRule (a VBScript or Jscript® routine) with a task. When access permissions are checked as the application is running, BizRules are executed. If the BizRules succeed, the user receives the results of the requested operations that were associated with the task; if the BizRules fail, the operations associated with the task are not performed.

Authorization Manager Application Components

An Authorization Manager application is built from or uses the following objects:

  • Authorization Store: Collection of role definitions, assignments of users and groups to roles, tasks and operations.
  • Tasks: Collections of operations (or other tasks) required to do some unit of work that is meaningful to administrators.
  • Scopes: Collections of tasks or resources with a distinct authorization policy; that is, all tasks and resources within a scope share the same access requirements.
  • Roles: The set of permissions necessary for a user to perform his or her job. The role is applied to a set of objects and has semantics for users assigned to the role.
  • Basic and Dynamic Groups: Lists of Active Directory Users or Groups or other Application Groups, with an additional list for non-members. Basic Groups are static lists. Dynamic Groups are determined at run time by performing LDAP queries against the client's Active Directory account attributes.
  • BizRules (or Authorization Scripts): Scripts attached to task objects. At most, one BizRule script can be attached to a task object and it runs at the time of an access request to the task. The BizRule qualifies the authorization decision with information only available at run time, such as time of day or dollar amount requested.

Application design requires careful definition of roles, tasks and scopes within an application. Authorization administrators design roles as collections of tasks supported by an application and assign users and groups to the role to grant them the ability to perform those tasks. For those tasks that require permissions to be determined at run time, BizRules are created and associated with appropriate tasks.

BizRule Elements

BizRules are scripts (VBScript or JScript) associated with a task. When access is requested for a task with an associated BizRule, the Window Scripting Engine is invoked to execute the script. Because each BizRule executed invokes the Windows Script Engine, BizRules should be computationally small tasks, such as comparing given parameters, or querying a database.

The following JScript BizRule sample demonstrates how the application grants access based upon the time of day; in this case it returns true if the time of day is between 9 AM and 5 PM:

AzBizRuleContext.BusinessRuleResult = false;
dt = new Date(); 
hour = dt.getHours();

if (hour > 9 && hour < 17)
{
   AzBizRuleContext.BusinessRuleResult = true;
}

To improve performance of frequently called BizRules, the results of the BizRule are cached for the life of a client context. Therefore, if BizRules are time sensitive (as in the previous example), the application caches client contexts for appropriately short amounts of time.

The following VBScript BizRule is used to verify that the supplied parameter is an amount greater than 25:

Dim Amount
AzBizRuleContext.BusinessRuleResult = FALSE
Amount = AzBizRuleContext.GetParameter("Age")
if Amount > 25 then AzBizRuleContext.BusinessRuleResult = TRUE

AzBizRuleContext.BusinessRuleResult = False
Dim Amount

Amount = AzBizRuleContext.GetParameter("ExpAmount")

' Do not accept approvals on Thursdays. When not Thursday, only allow
' approvals for amounts less than $500.
If ( Not ( Weekday( Now ) = 4 ) ) Then
   If ( Amount < 500 ) Then AzBizRuleContext.BusinessRuleResult = True
End If

As BizRules require some scripting knowledge, it is not appropriate for many administrators to create and modify them. Usually BizRules are developed and shipped with the application or provided by the application vendor, or other developer, later.

AzBizRuleContext

The AzBizRuleContext object is the means of communication between an application and BizRules. The AzBizRuleContext object is automatically created and available to all BizRule scripts. It has two properties: BusinessRuleResult and BusinessRuleString. BusinessRuleResult is used to indicate whether the BizRule allows the user to perform the requested task. The script returns true when the user is to be granted permission, and false when the user is to be denied access.

The first step in any BizRule script should be to immediately set the BusinessRuleResult value to FALSE if denying access is the desired behavior for unknown errors.

AzBizRuleContext.BusinessRuleResult = False

Otherwise, if the BizRule prematurely exits due to code error or an environment problem, it is possible that random data could cause the BusinessRuleResult to be a value of TRUE, thereby granting access.

The BusinessRuleString property is used to set or retrieve an application-specific string for the BizRule, whose format and content are defined by the application. One possible use of this property is to explain the reason that the BizRule denied access to the user.

AzBizRuleContext has one method, GetParameter, which is used to retrieve the values of any parameter passed into the BizRule from the application. The method takes one parameter, the name of the BizRule parameter, whose value is retrieved.

Amount = AzBizRuleContext.GetParameter("ExpAmount")
Service = AzBizRuleContext.GetParameter("YearsOfService")

For Version 1.0 of Authorization Manager, only VBScript and Jscript are supported. Such scripts cannot use managed objects. BizRules should be well tested before being placed in a task. It is often very difficult for application developers to locate and diagnose the cause of script run-time errors.

Adding BizRules to Your Application

The incorporation of BizRules within an application follows a common course:

  • At application development time, create your BizRule using the AzMan MMC snap-in.
  • At run time, your application initializes the Authorization Manager to connect to the authorization store and then establishes a connection to the section of the store specific to your application.
  • When a client connects to your application, it creates a client authorization context.
  • Utilize the AccessCheck API to invoke BizRules to determine privileges for the connected client.
  • At installation time, it calls the appropriate APIs to create an authorization store, operations and tasks (and possibly some initial roles required by the application).

Creating or Editing a BizRule Using AzMan

BizRules in an application can be added or changed by the application administrator after the application is deployed. This is done using the Authorization Manager MMC snap-in (AzMan.msc).

To add or edit a BizRule, run the AzMan snap-in and open the Authorization Store. Expand the appropriate application to Definitions, Task Definitions; right-click on the relevant task in the right-hand pane and click Properties. Then, click the Definition tab followed by Authorization Script.

The Authorization Rule dialog box appears as shown in the following figure.

Figure 3. Authorization Script

To create a new BizRule, write the desired script into a file, then load the file through the Authorization Script dialog box by clicking Reload Rule into Store. Each time the file containing the BizRule is modified, it must be reloaded before it takes effect. For BizRules loaded script files to remain in effect, the file from which it was loaded must remain available at its specified path.

Initialize the Authorization Manager and Access the Store

Any application utilizing BizRules must perform the standard Authorization Manager initialization. When an AM server application is started, the application initializes an instance of the Authorization Store by calling IAzAuthorizationStore::Initialize. Once the store is initialized, it creates an instance of an interface to application data within the store by calling IAzAuthorizationStore::OpenApplication, and then waits for clients to connect.

'--------------- Create Authorization Store Object --------------
Set AzManStore = CreateObject("Azroles.AzAuthorizationStore")

'--------------- Load the desired store  --------------
AzManStore.Initialize 0, "msxml://C:\AzStore.xml"

'--------------- Open our application --------------
Set App = AzManStore.OpenApplication ("Expense")

Initializing Client Context upon Client Connection

When a client connects to the application a client context must be created for the user using one of:

  • IAzApplication::IntiializeClientContextFromToken
  • IAzApplication::AzInitializeClientContextFromStringSid
  • IAzApplication::InitializeClientContextFromName
'--------------- Create Client Context --------------
Set CCHandle = App.InitializeClientContextFromToken(0, 0)

Invoking BizRules

When a client makes a request or some other event triggers the application to perform a task, the application must first determine if execution of the task is authorized. It does so by calling IAzClientContext::AccessCheck. AccessCheck returns an array of decisions for each requested operation. A zero value of an individual decision (of the decision array) indicates that particular operation is authorized.

The following example of server code submits an expense for processing, but only if AccessCheck authorizes access to the Submit ** operation (id=55). The actual call to execute the associated code (DoSubmitExpense) is made within the application and not Authorization Manager (AccessCheck does not execute the task; it simply returns an indication of whether the user has permissions for that operation).

  ' prepare parameters passed to AccessCheck
  Scopes(0) = Empty   ' when Empty, the application default scope is used 
  Operations(0) = 55  ' operation ID for the Submit operation

  ' Name/Value pairs are passed by AccessCheck to BizRule(s), if any,
  ' associated with the operations in the Operations() array

  Names(0) = "DayOfWeek"
  Values(0) = "Friday" 
  Names(1) = "ExpAmount"
  Values(1) = Clng( ValueFromUI )

  '-------- AccessCheck -----------------------------------------
  ' Verify the current user is allowed to submit expenses.

  Results = CCHandle.AccessCheck( "Submit Expense", _
                                  Scopes, _
                                  Operations, _
                                  Names, _
                                  Values )

  If Results(0) = 0 Then  ' Zero = success!
    DoSubmitExpense( ValueFromUI )
  Else
    ReportToClient( "Access Denied" )
  End If

In the example code, name and value pairs are passed to AccessCheck. These parameters are passed to make run-time data available to any BizRule scripts associated with the members of the Operations() array. If no BizRules are associated with Operations(), then the Names() and Values() arrays are unused and could be empty (the Names() and Values() arrays are required parameters to AccessCheck, so they cannot be omitted).

Note that in the previous code, if you reverse the order of the first and second parameter, it does not work. The Names parameter (given to AccessCheck) must be alphabetically sorted (in ascending order). In this case, the name "ExpAmount" must be placed after "DayOfWeek" because "DayOfWeek" precedes "ExpAmount" alphabetically.

Creating a BizRule in an Installation Script

Developers wishing to include creation of BizRules at the application installation time can create BizRules programmatically. Authorization Manager includes a COM interface to allow applications access to the Authorization Store and to provide the ability to create roles, tasks and BizRules. The following code demonstrates the creation of a task with an associated BizRule.

Dim Task1
Set Task1 = App1.CreateTask("Submit Expense")
Task1.BizRuleLanguage = CStr("VBScript")
Task1.AddOperation CStr("Submit")
Task1.BizRule = "Dim Amount" & vbnewline  & _
                "AzBizRuleContext.BusinessRuleResult = FALSE" & vbnewline & _
                "Amount = AzBizRuleContext.GetParameter( " & Chr(34) & _
                              "ExpAmount" & Chr(34) & ")"  & vbNewLine & _
                "If Amount < 450 Then" & vbNewLine & _
               " AzBizRuleContext.BusinessRuleResult = TRUE" & vbNewLine _
               "End If" _


Task1.Submit

Dim Task2
Set Task2 = App1.CreateTask("Approve Expense")
Task2.BizRuleLanguage = CStr("VBScript")
Task2.AddOperation CStr("Approve")
Task2.BizRuleImportedPath = "C:\Approve.vbs"

Task2.Submit

Conclusion

Through BizRules, applications utilizing Authorization Manager offer a flexible and powerful mechanism for dynamically changing and fine-tuning the user roles within deployed applications. Additionally, authorization logic can be implemented without changing application code, thus reducing the risk of causing undesirable application side effects when changing authorization.