Web Storage System Security Roles

Updated : June 14, 2001

Sanjay Anand

Microsoft Corporation

Summary: Microsoft Exchange 2000 Server uses Windows 2000 security data structures natively in the Microsoft Web Storage System. In addition to the basic read/write/create/delete rights at the folder and item (or message) levels, Exchange 2000 also supports property-level access control and the concept of application-scoped roles (referred to as Roles). To provide support for these features on the Windows 95 and Windows 98 platforms, a new XML format has been defined for getting and setting security descriptors on folders and items. This document describes the purpose of roles and their design, and details how roles can be defined and subsequently used in setting security descriptors using XML. Please refer to the articles found in the Exchange 2000 SDK for a detailed description of the XML format for security descriptors and how application developers can use XML to get and set security descriptors in Exchange 2000. (13 pages)

Click here to copy the code sample roles.exe (47 KB) for use with this document

On This Page

Overview

Overview

Microsoft® Exchange 2000 implements access control by supporting Windows® 2000 security descriptors natively in the Web Storage System. This means that each folder (and possibly each item) in Exchange has a security descriptor associated with it as a retrievable and settable property. Each folder has a security descriptor associated with it that encapsulates not only the rights specific to that folder, but also the default rights associated with all the items in that folder. If an item in a folder has no specific security descriptor, the default rights specified in the parent folder apply to the item.

A security descriptor is a data structure that consists of, among other things, an owner, a discretionary access control list (DACL), and a system access control list (SACL). The owner field contains the security identifier (SID) of the owner of the object with which the security descriptor is associated, the DACL specifies who has access to the object, and the SACL specifies what actions are auditable by the system. For the purpose of this discussion, we will confine ourselves to the DACL and refer to it as the access control list (ACL) of the object.

An ACL consists of one or more access control entries (ACE); each ACE specifies access rights for a security principal. A security principal in Windows 2000 can be either a user or a group of users, where these users and groups reside in Active Directory™ and where a unique SID specifies each user or group. Exchange 2000 makes it possible to define a new security principal, called a role. A role is a named collection of security principals (users or groups) that can be referred to within an ACE in an ACL. The key difference between roles and Windows 2000 groups is that Exchange security roles are defined and stored on the object itself; they can be created and populated with members without requiring a privileged directory service operation.

This feature is important for applications that do not require that specific Windows 2000 groups exist prior to deployment. Security roles are created and persisted in the Web Storage System independent of the Windows 2000 directory service, with two distinct advantages for application developers.

• Because these roles exist only in the Web Storage System, creation of roles does not require privileged Active Directory operations—a key requirement for departmental scenarios.

• Because roles are scoped to particular folders (or to applications that are also scoped to folder hierarchies), their names are required to be unique only within the scope of the folder. Therefore, two applications deployed on a single computer running Exchange Server do not require unique role names and memberships.

Roles act as placeholders in applications because they are only referred to in the application at design time. They are evaluated at run time, so application developers can defer the population of these roles until the application is deployed. This means that application developers need not recompile their applications for each deployment instance. As noted above, roles can be used anywhere in the Web Storage System where an ACL can be set, that is, on folders and items.

Functionality

Roles provide an extensible way for application developers to define a set of roles to be used by an application. The application installer determines the role membership at deployment time, without modifying the application itself and with no need for Windows 2000 directory service administration. Thus, roles can be referred to at design time in applications and scripts without needing to know the actual names of users or groups from the directory service where the application will be deployed. When the application is deployed, the folder owner has to populate the role with actual users or groups.

Role membership can be nested (that is, a member of a role can be another role), and can be defined at the folder or item level; for example, an item can contain role definitions used for that item or for its properties. Role membership cannot, however, be defined at the property level. In other words, a property of an item cannot have a separate role defined for use only with that property. Instead, that role would have to be defined at the item level.

Security roles are implemented by populating a user-defined "role membership" property on an item or folder (object or parent object) with a list of security principals (users, groups, or roles). In particular, the list consists of security identifiers (SIDs) where these SIDs represent the security principals and form the membership list for a given role. To make use of the role membership property, a "role ACE" is added to the appropriate ACL (either item or folder). This role ACE contains a special "role SID" that, among other things, identifies the role membership property. Before the AccessCheck function is called, the Web Storage System evaluates this special role ACE and replaces it with a new set of ACEs. The new ACEs are based on the rights assigned in the role ACE combined with each SID defined in the role membership property; that is, one ACE is added per member of the role membership list. See Figure 1 for an example.

A role SID differs from a Windows 2000 SID in that Exchange Server is the security authority for it rather than Windows. Role SIDs are self-contained structures that do not contain any Windows 2000 security-specific information and hence can be used across domains. A role SID encodes two pieces of information.

• Property. A role property contains the list of SIDs to which the ACE applies. The SIDs in this list can be both Windows 2000 SIDs and role SIDs; recursive expansion is handled properly.

• Scope. This information indicates where to read the role property. If the value is OBJECT then it will read the property from the object itself. If the value is FOLDER and the object is an item, then it will read the role property from the parent folder.

The role membership definition stays with the object where it is defined, except in the case of an item that has a FOLDER-scoped role. Moving a folder or an item that has roles defined on it carries those roles with the folder or item. The same is true for replication of folders and items. However, if an item refers to the role property on its parent folder (that is, the scope of its role is FOLDER), then that property is not moved with the item on a move, copy, or replication operation. Also, the role property does not inherit from a parent object. Therefore, if items inherit a role ACE from a folder, the role property is not propagated automatically. It is expected that application developers will work around these limitations by trapping move or copy events and copying the FOLDER-scoped properties independently. In addition, inheritance of role properties needs to be handled by application developers.

Role ACE and Role SID

As noted above, the mechanism for using a role membership is to place a role ACE in the desired ACL. The role ACE in Figure 1 contains a special role SID (Role SIDa), which consists of the following elements encoded within the SID.

• An identifier for the role membership property (the Property Name). Role SIDa points to the property called "Role a".

• The Role Scope, specifying the location where the role membership is found as described above.

Figure 1: Correlation between the role SID and the role ACE within an ACL

Role Scope

Any application that needs to define a role can create a property on the appropriate object for the membership list, and then refer to that property from the role SID in the role ACE (described below). The object that receives the role membership property depends on the scope desired for that role. The following scopes are defined for roles.

• Item/Object. The role membership property is expanded on the current object (folder or item).

• Folder. The role membership property is expanded at the folder if the object is a folder and at the parent folder if the object is an item.

Figure 2: Scope of a role

Special Roles and General Application Roles

Two types of properties can be used for creating role SIDs.

• Special role property. Exchange assigns a special meaning to each of the special role properties. The value of a special role property is always a single Windows 2000 SID. Many of them are set by Exchange automatically and are read-only. Application developers may find that using a special role SID in their security descriptors quickly solves a property that otherwise would require complicated custom logic.

• General application role property. Application developers can use these properties for any purpose. Exchange assigns no special meaning to the properties, but they can only hold a list of SIDs. In Exchange 2000, 16 specific properties have been defined for general application use.

Special Role Properties

Exchange 2000 allows the use of a number of special SID-valued properties in security roles. These properties are binary valued with an Exchange 2000 SID as their value. The following table lists the special role properties.

Table 1 Special role properties

The following table lists new properties that correspond to those in the preceding table. These properties have been added to allow getting their values in XML format from MAPI.

Table 2 Properties that allow getting their values in XML format from MAPI

Using DAV or OLEDB, you can use the following property names:

https://schemas.Microsoft.com/exchange/security/creator https://schemas.Microsoft.com/exchange/security/lastmodifier
https://schemas.Microsoft.com/exchange/security/sender
https://schemas.Microsoft.com/exchange/security/sentrepresenting
https://schemas.Microsoft.com/exchange/security/originalsender
https://schemas.Microsoft.com/exchange/security/originalsentrepresenting
https://schemas.Microsoft.com/exchange/security/readreceiptfrom
https://schemas.Microsoft.com/exchange/security/reportfrom
https://schemas.Microsoft.com/exchange/security/originator
https://schemas.Microsoft.com/exchange/security/reportdestination
https://schemas.Microsoft.com/exchange/security/originalauthor
https://schemas.Microsoft.com/exchange/security/receivedby
https://schemas.Microsoft.com/exchange/security/receivedrepresenting

General Application Role Properties

The following table lists the 16 special properties that are defined for use as application roles.

Table 3 Properties that are defined for use as application roles

Creating Role Memberships

The following procedure shows the high-level steps for creating role memberships.

To create a role membership property:

1. Define the scope of the role (folder, item, attachment).

2. Choose a property to use for the membership information (list of SIDs).

3. Store the membership information (list of SIDs) in the property. Optionally, if required, the application implements a calculated column (GetProps) callback on the chosen property so that the proper membership list can be returned to the store when required for access checks.

Format of a Role Property

The binary format for roles consists of two initial DWORD values followed by a concatenated SID list. The first DWORD is a version number. The version number should be set to 0 for the Exchange 2000 release. The second DWORD is the number of bytes in the concatenated SID list.

Table 4 Binary format for roles

The format is designed so that additional information can be added in the future if the need arises. The initial portion of the format, including the version, byte count, and concatenated SID list, will not change in future revisions. This means that applications that understand the "version 0" format will continue to work as long as they use the second DWORD to determine the length of the concatenated SID list.

Code Samples

Please refer to the Microsoft Visual Basic® and Microsoft Visual C++® code included with this article for samples of code that builds an ActiveX® DLL that can be used with Visual Basic to read and write the members of role properties.

In particular, this code creates the PR_XMT_SECURITY_ROLE_1 property (accessed as "https://schemas.microsoft.com/mapi/proptag/x3D250102") and populates it with role members (list of SIDs). Once this is done, you can use XML to set create a security descriptor as under the following:

'Set the Role property using OLEDB
'Use it in XML as under:
'   <S:role_sid>
'      <S:scope>[object/folder]</S:scope>
'      <S:property_name>[name of role property setup using the 
             c code]</S:property_name>
'   </S:role_sid>
' Add reference to "Microsoft ActiveX Data Objects 2.5 Library"
Option Explicit
Sub Main()
    Dim cn As New ADODB.Connection
    Dim rec As New ADODB.Record
    Dim fld As Field
    Dim strDomainName As String
    Dim strLocalPath As String
    Dim strURL As String
    Dim strXML As String
    'Create URL to folder
    strDomainName = "foobar.extest.microsoft.com"
    strLocalPath = "public folders/YourFolder"
    strURL = "file://./backofficestorage/" & strDomainName & "/" 
              & strLocalPath
    'Open it
    rec.Open strURL
    'Dump the SD as XML
    Set fld = rec.Fields("https://schemas.microsoft.com/exchange
                                /security/descriptor")
    Debug.Print "Security Descriptor for '" & strURL & "'"
    'Close it
    rec.Close
    'Open it again
    rec.Open strURL, , adModeReadWrite
    'Modify SD
    strXML = "<S:security_descriptor 
xmlns:S=""https://schemas.microsoft.com/security/"" 
xmlns:D=""urn:uuid:c2f41010-65b3-11d1-a29f-00aa00c14882/"" 
D:dt=""microsoft.security_descriptor"">"
    strXML = strXML + " <S:dacl>"
    strXML = strXML + "  <S:effective_aces>"
    strXML = strXML + "   <S:access_allowed_ace>"
    strXML = strXML + "    <S:access_mask>1fc9ff</S:access_mask>"
    strXML = strXML + "     <S:role_sid>"
    strXML = strXML + "      <S:scope>object</S:scope>"
    strXML = strXML + "       <S:property_name>http:
                               //schemas.microsoft.com/mapi/proptag
                               /x3D250102</S:property_name>"
    strXML = strXML + "     </S:role_sid>"
    strXML = strXML + "    </S:access_allowed_ace>"
    strXML = strXML + "   </S:effective_aces>"
    strXML = strXML + " </S:dacl>"
    strXML = strXML + "</S:security_descriptor>"
    rec.Fields.Append "https://schemas.microsoft.com/exchange/
                       security/descriptor", adBSTR, Len(strXML), ,
                       strXML
    rec.Fields.Update
    'Close it
    rec.Close
End Sub

Conclusion

This document gives an overview of Web Storage System security roles, their properties, and their functionality. The focus of this discussion is to describe the purpose of roles and their design, and to detail how roles can be defined and then subsequently used in setting security descriptors using XML.