Windows Authorization Manager

Article
10/15/2014

AzMan is available for use in the following versions of Windows: Windows Server 2012, Windows 8, Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, or Windows XP. It is deprecated as of Windows Server 2012 R2 and may be removed in subsequent versions.

This article starts with a brief overview of Windows Authorization Manager (AzMan), a list of the benefits to using AzMan, and a list of what's new in AzMan for Windows Server 2008. The article then focuses on the code that a developer must incorporate into a federation-aware Web application in order to use AzMan for making authorization decisions.

Overview

AzMan is a role-based access control (RBAC) framework that provides an administrative tool to manage authorization policy and a runtime that allows applications to perform access checks against that policy. The AzMan administration tool (AzMan.msc) is supplied as a Microsoft Management Console (MMC) snap-in.

Role-based authorization policy specifies access in terms of user roles that reflect an application's authorization requirements. Users are assigned to roles based on their job functions and these roles are granted permissions to perform related tasks.

Authorization policy is managed separately from an application’s code. The application designer defines the set of low-level operations that are considered security sensitive and then defines a set of tasks that map onto those operations. The tasks, but not the operations, are designed to be understandable by administrators and business analysts.

Administrators use the AzMan snap-in to manage which roles should have access to which tasks. As the business evolves and roles need to be modified, the administrator makes changes to the authorization policy; the underlying business application does not need to be changed. Federation-aware applications employ AzMan for access control decisions by mapping federation claims to AzMan roles.

For in-depth discussions of AzMan, see the following articles:

Developing Applications Using Windows Authorization Manager

How To: Use Authorization Manager (AzMan) with ASP.NET 2.0

Use Role-Based Security in Your Middle Tier .NET Apps with Authorization Manager

Getting Started With AzMan

Major Benefits

The following is a brief list of the major benefits to using AzMan:

Reduced software development and maintenance costs

Developers avoid the expense and trade-offs of custom access control. AzMan does the expensive work of a full-featured authorization solution, including a complete RBAC model, policy storage (Active Directory, SQL, or XML), an MMC user interface, built-in application group support, rule and query support, integrated system auditing, and performance optimizations such as caching and late-binding.
Enhanced security

Platform technologies are rigorously tested, broadly used, and continually refined. A common RBAC model leverages administrators' existing knowledge, resulting in fewer access control mistakes.
Platform integration and alignment

AzMan supports platform features such as Active Directory (AD) groups, Windows security auditing, and MMC. AzMan assures the proper integration of system access control objects such as the NT access token and better alignment for future Windows access control features such as provisioning and entitlement engines.
Common RBAC administration

AzMan provides an easy-to-use role-based administrative experience; administrators learn fewer authorization models and require less training.
Role-based development framework

AzMan provides a framework that is easy to integrate with native or managed applications and provides broad RBAC management and enforcement functionality.
Flexible authorization rules

AzMan can define membership through dynamic Lightweight Directory Access Protocol (LDAP) queries or custom business rules (BizRules).
Centralized administration

Multiple applications can be managed centrally and leverage common application groups.
Flexible storage options

New and Improved Features

AzMan was first released in Windows Server 2003. It has been updated with the following new and improved features for Windows Server 2008:

Improvements to the Authorization Application Programming Interface (API)

These improvements include new simpler methods to perform common tasks, such as access checks (AccessCheck2) and role checks (IsInRoleAssignment).
SQL Server database stores

Previously, AzMan stores could be created only in Active Directory Domain Services (AD DS), Active Directory Lightweight Directory Services (AD LDS), and XML files.
Support for business rule groups

These are groups where membership is determined at run time by a script
Support for custom object pickers in a custom AzMan User Interface UI

This feature allows extension of the AzMan MMC Snap-in to support applications that use AD LDS or SQL user accounts.
LDAP queries are not limited to only user objects
Additional events are recorded in the log if auditing is active
Business rules are disabled by default; previously business rules were enabled by default

Definitions

Authorization Store
The repository for authorization policy.
Application
Defines a namespace for roles, tasks, and operations.
Scope
A collection of resources in which each resource of similar type has the same authorization policy. A scope is a virtual subdivision within an application that can be used to prevent unintended resource sharing and to support auditing and delegation.

A scope can represent a folder, a container in AD DS or AD LDS, a masked collection of files (for example, *.doc), a URL, or any item that can be accessed by the application and its underlying authorization store. If there are groups, role assignments, role definitions, or task definitions that should not be applied to an entire application, create them at the scope level.
Role
Usually corresponds to a job category or responsibility (for example, purchaser or hiring manager) and is a collection of tasks that a user must have to do that job. Users and groups are assigned to roles.
Task
A collection of operations and sometimes other tasks. Well-designed tasks represent recognizable work items (for example, "submit purchase order" or "submit expense").
Operation
A set of permissions that are associated with system-level or API-level security procedures such as WriteAttributes or ReadAttributes. Operations are building blocks for tasks.
Business Rule
A script that is associated with a task. A rule allows access decisions to be based on any run-time condition that a script can test.

Using AzMan in Federation-Aware Applications

AzMan Stores

An AzMan (authorization policy) store must be created, either programmatically or through developer mode in the AzMan snap-in, before AzMan is used to control resource access. AzMan stores can be created in the following repositories:

XML files
AD DS
AD LDS
Microsoft SQL Server (new for Windows Vista and Windows Server 2008)

For a discussion of using AD DS versus AD LDS for the store, see AD or ADAM? For information and code samples on programmatically creating an authorization store, see the following topics:

The following example shows a portion of an XML-based AzMan store.

<?xml version="1.0" encoding="utf-8"?>
<AzAdminManager MajorVersion="1" MinorVersion="0">
  <AzApplication Guid="383721cc-4255-4973-9b76-156408e55b41" 
                 Name="Trey Ordering">
    <AzApplicationGroup Guid="eb0a0fa6-dc03-41e8-a8b6-0fc95aca2b15" Name="A Datum">
      <Member>S-1-5-21-3485267726-1923982029-1388670439-1014</Member>
    </AzApplicationGroup>
    <AzRole Guid="6666830f-5848-4e4e-a297-2555cd22c3c7" 
            Name="Purchaser">
      <AppMemberLink>eb0a0fa6-dc03-41e8-a8b6-0fc95aca2b15</AppMemberLink>
      <TaskLink>816f5a8c-8475-4b78-bcc0-b256aec32703</TaskLink>
    </AzRole>
    <AzTask Guid="816f5a8c-8475-4b78-bcc0-b256aec32703" 
            Name="Purchaser" 
            Description="" BizRuleImportedPath="" RoleDefinition="True">
      <TaskLink>b70bd774-834f-4202-8a4c-b1f5c3a3c243</TaskLink>
    </AzTask>
    <AzTask Guid="b70bd774-834f-4202-8a4c-b1f5c3a3c243" 
            Name="Order Parts" Description="" BizRuleImportedPath="">
      <OperationLink>4b8c32a6-1782-43f9-8c9f-0ecf43667c0f</OperationLink>
      <OperationLink>64457c88-2f67-49c1-9de9-82a5c806443a</OperationLink>
    </AzTask>
    <AzOperation Guid="4b8c32a6-1782-43f9-8c9f-0ecf43667c0f" 
                 Name="Submit Order" Description="">
      <OperationID>57</OperationID>
    </AzOperation>
    <AzOperation Guid="64457c88-2f67-49c1-9de9-82a5c806443a" 
                 Name="Query Order Status" Description="">
      <OperationID>58</OperationID>
    </AzOperation>
    <!-- ... -->
  </AzApplication>
</AzAdminManager>

Step-by-Step Example

The following code example shows the steps necessary for a Web application to connect to an AzMan store and use it to make authorization decisions about the current user.

A reference to the Microsoft.Interop.Security.AzRoles primary interop assembly (PIA) is required. The AzMan PIA contains wrapper methods for the Authorization API. This example makes use of version 2.0 of the AzMan PIA, which is new for Windows Server 2008.

The development tasks are:

Connect to the AzMan store and obtain the IAzApplication2 object that corresponds to the application
Create a client context for the user
Make authorization decisions

Step 1: Connect to the AzMan Store and Obtain IAzApplication2

The following code example shows how to connect to the AzMan store and obtain the IAzApplication2 object that represents an application's authorization policy in the AzMan store. Usually, the connection string for the store is retrieved from the Web.config file.

// See the following table for other sample connection strings.
string connectionString = @"msxml://c:\AuthPolicy\AzStore.xml";

AzAuthorizationStoreClass azStore = new AzAuthorizationStoreClass();
azStore.Initialize(0, connectionString, null);

IAzApplication2 azApplication = 
    azStore.OpenApplication2(Trey Ordering", null);

The following table lists sample connection strings for the different stores available to AzMan.

Store	Sample connection string
XML file	msxml://c:\AuthPolicy\AzStore.xml
AD DS	msldap://cn=AzStore,cn=AuthPolicy,dc=MyOrg,dc=com
AD LDS	msldap://AzServer:port/cn=AzStore,cn=AuthPolicy,dc=MyOrg,dc=com
SQL	mssql://Driver={SQL Server};Server={AzServer};/AzDB/AzStore

Step 2: Create the Client Context

The IAzApplication2 object contains multiple methods to create a client context. The first three methods below, listed in decreasing order of preference, initialize a client context with information about the user. The method to use depends on whether the user comes with a security token, a security identifier (SID), or simply a name. The fastest and most authoritative way is through the use of a security token. The fourth method, InitializeClientContext2, is used by federation-aware applications and creates an empty client context. The context is then populated from group claims associated with the user.

Method	Description
InitializeClientContextFromToken	Uses the Windows logon token of the user. All security IDs are in the token; therefore, this method is the fastest and preferred way to initialize the client context because population of group SIDs from the domain controller is not required.
InitializeClientContextFromStringSid	Use when only the client SID of the user is available. AzMan queries the domain controller for the group SIDs associated with the client SID. Since these lookups are required, this mechanism is slower than InitializeClientContextFromToken.
InitializeClientContextFromName	Use when only the name of the user is available. AzMan queries the domain controller for the SIDs associated with the name. Names can be in the form of username, domain\username, or UPN. Using username alone (without a domain specified) can result in an incorrect client context if the same username is used in a trusted domain. Since these lookups are required, this mechanism is slower than InitializeClientContextFromToken.
InitializeClientContextFromToken2	Use for manual population scenarios such as AD FS and AD LDS. After initializing the empty context, the application adds the SIDs, roles, or groups to the context. AD FS applications typically populate roles from group claims associated with the user. AD LDS applications typically populate SIDs.

The following code example shows the creation of a client context from the Windows logon token of the user.

IAzClientContext3 clientContext = 
    (IAzClientContext3)azApplication.InitializeClientContextFromToken(
        (ulong)WindowsIdentity.GetCurrent().Token, null);

The following code example shows the creation of an empty client context. For a code example showing how to population the context from federated group claims, see the step-by-step example in the companion topic Active Directory Federation Services.

IAzClientContext3 clientContext = 
    (IAzClientContext3)azApplication.InitializeClientContext2("Trey Ordering", null);

Note that the IAzClientContext3 interface is new for Windows Server 2008.

Step 3: Make Authorization Decisions

The IAzClientContext3 interface contains multiple methods for making access decisions. Role checks are used to determine if the user belongs to a particular AzMan role. Access checks are more granular and can determine whether the user is allowed to perform a specified set of operations.

Role Checks

One of the easiest ways to regulate access is to base decisions on what roles the user belongs to as specified in the AzMan store. The following code example allows access for users in the Purchaser role.

// Use the default application scope.
string[] roles = (string[])clientContext.GetRoles("");
foreach (string role in roles)
{
    if (role == "Purchaser")
    {
        // Allow access for Purchaser role.
    }
}

The new IAzClientContext3.IsInRoleAssignment method provides a simpler way to accomplish this goal.

if (clientContext.IsInRoleAssignment("", "Purchaser") )
{
    // Allow access for Purchaser role.
}

Access Checks

An access check determines whether the user is authorized to perform specified operations. The signature for the managed IAzClientContext.AccessCheck wrapper method is:

object AccessCheck(
    string bstrObjectName,
    object varScopeNames, 
    object varOperations, 
    object varParameterNames, 
    object varParameterValues, 
    object varInterfaceNames, 
    object varInterfaceFlags, 
    object varInterfaces)

The last five parameters are used only with custom business rules. In other cases, only the first three parameters are specified.

Parameter	Description
bstrObjectName	A string used for run-time auditing.
varScopeNames	An object array where each element contains the string name of a scope as defined in the AzMan store. To use the default application-level scope, set the first element in the array to an empty string. In previous versions the array could contain only one element.
varOperations	The operations that are checked for access permission. This object array contains integers that represents the OperationIDs as defined in the AzMan store and available through the OperationID property of the IAzOperation object contained in the IazApplication2 object.

The AccessCheck method returns an array of objects (integers) where each element corresponds to the same element in the varOperations array. If access to a particular operation is allowed, the corresponding returned element contains the number zero.

The following code example checks for permission to perform operations #57 (Submit Order) and #58 (Query Order Status). Permission would be granted for both operations for any user in the Purchaser role because this role is allowed the Order Parts task, which contains the Submit Order and Query Order Status operations. To view these relations, see the previous AzMan store example.

// Use the default application scope.
object[] scope = new object[1] { (object)"" };

// Corresponds to OperationIDs defined in AzMan store.
object[] operations = new object[2] { 57, 58 };

int[] results = (int[])clientContext.AccessCheck("Order #123", 
    (object)scope, (object)operations, null, null, null, null, null);

if (results[0] == 0)
{
    // Allow access for operation #57.
}

if (results[1] == 0)
{
    // Allow access for operation #58.
}

If the access check is for a single scope and a single operation, the new IAzClientContext3.AccessCheck2 method simplifies the previous procedure greatly, as shown in the following code example.

if (clientContext.AccessCheck2("Order #123", "", 57) == 0)
{
    // Allow access for operation #57.
}