Server Access Programmer's Guide:
Using Access Control and User Context

This topic discusses the eRoom access control model and how it is exposed through SAAPI. It also explains how user contexts are established by SAAPI programs.

Community Membership vs. Room Membership Rights

Members of a Community have no rights within a particular eRoom unless they are specifically listed as a member of that eRoom. Administrators, who are described later in this section, are the only exception to this rule. At the Community level, users are allowed to:

• See the Community member list

• Modify their own User object

• Get a list of the eRooms that are visible to them (an eRoom is visible to a user if it is listed, or if it is unlisted but the user a member of it).

A user who is not a member of a visible eRoom can access some high-level information about it, such as its name and its logo graphic, but cannot access any object inside it.

Room Membership Roles

Users have access rights to objects within an eRoom based on their member roles in the eRoom. A member can have one of these three types of roles:

Community and Site Administrators

eRoom has two kinds of Administrators: Site administrators and Community administrators. Site administrators have effective Coordinator roles in all eRooms in all communities. Whereas Observer, Participant, and Coordinator roles only apply to a member within the context of a single eRoom, administrator privileges apply to a member within the context of the whole community or site. Administrators have Coordinator-level privileges in all the eRooms in the community or site, regardless of whether they are designated as members of those eRooms. Only administrators and users with sufficient rights can perform tasks at the community level, such as modifying the community member list, or creating facilities, or creating eRooms.

The Built-in Administrator Account

There is a built-in account available to SAAPI-S programmers that has site administrator rights. The following is an example of how you might access an eRoom as this user:
’r;# IERUApplication::LoginUser()
Dim app, uc
Set app=Server.CreateObject(”r;eRoom.Application”)
Set uc=app.LoginUser(erUserSiteAdministrator,erParamTypeID)

’r;# IERUUserContext::ImpersontateUser
Dim uc
Set uc=Server.CreateObject(”r;eRoom.UserContext”)
uc.ImpersonateUser erUserSiteAdministrator,erParamTypeID

Accessing eRooms in this way can be convenient because it doesn't require specific login information to be stored in the SAAPI program, but keep in mind that actions taken while in this user context will be attributed to this built-in user. Also, there is essentially no access control being enforced while in this user context, so it should used with caution when exposing functionality to remote users (e.g. in Active Server Pages). When writing programs that act on behalf of eRoom users, it is preferable to access Facilities as those users.

Primary Roles, Group Roles, and Effective Roles

If a member is part of an eRoom both because a Coordinator specifically added him as a member and because he is part of a Group that is a member of the eRoom, his effective role within the eRoom is whichever of the following has greater access rights:

• The role specifically assigned to the member, that is, the primary role.

• The highest role assigned to the set of Groups that contain the member, that is, the group role.

Members of the Community who are not members of a particular eRoom have neither a primary role nor Group role within that eRoom.

Setting primary and group roles

The following table describes the methods that get and set member roles within an eRoom.

Item Access Control

Each eRoom Item has two access control lists: One for members who can open the Item and one for those who can edit it.

Can Open and Can Edit Access

Users can control access to Items in a variety of ways. The two most common ways of controlling access to Items is through their "Can Edit" and "Can Open" access control lists. These are lists of members who have privileges to edit or open the Item. By default, when an Item is created, the "Can Edit" lists contains only the creator, and the "Can Open" list is set to "any member who can get to it".

The "Can Edit" and "Can Open" lists for Items can be used to constrain the privileges assigned to users via their role in the eRoom, on an Item-by-Item basis. For example, a user with Observer or Participant rights could be prevented from viewing an Item if he were excluded from an Item's "Can Open" list. However, these access lists cannot be used to give users more rights than those indicated by their roles. For example, users with Observer rights cannot be given edit rights to an Item by adding them to the Item's "Can Edit" list. "Can Edit" and "Can Open" lists have no effect on users with Coordinator or Site and Community Administrator rights; these users can always edit or open any Item in the eRoom.

Access Modes, Access Scopes, and Access Lists

In SAAPI, the "Can Edit" and "Can Open" rights are exposed by the IERUAccessControl interface. The "Can Edit" rights and the "Can Open" rights are called access modes, and are expressed by the values of the ERUAccessMode enumeration (either erAccessOpen or erAccessEdit). For a particular access mode, each object has an access scope. The access scope describes who has the rights corresponding to the access mode. Access scopes are described by the ERUAccessScope enumeration. The following table describes the possible values for this enumeration:

Access Control Lists

An Access List is the list of members specifically designated to have "can edit" or "can open" access to an Item. An Item's access list is empty unless the access scope is erScopeList. This list of members can be fetched with the GetAccessList method, and can be modified with the AddAccess and RemoveAccess methods. To determine if a particular member has access to an Item, without having to check the access scope and potentially iterate through the access list, use the CanAccess method. This method just requires a member and access mode as input, and returns a boolean value indicating if the member has the desired access privileges.

Edit Reservations and Read Only

In addition to changing the "Can Edit" list for an Item, a user with edit rights can limit the edit rights of others in two other ways:

• By taking out an edit reservation on the Item

• By marking the Item as read only.

These techniques override the "Can Edit" list in different ways.

A user with "Can Edit" rights to an Item can get an edit reservation on the Item. A user with an edit reservation is the only user on the "Can Edit" list who can modify the Item until the reservation is released. Only users with Coordinator privileges can "break" another user's edit reservation. While an Item is reserved for editing, other users can see who has it reserved and when it was reserved.

To get an edit reservation through SAAPI, call the GetReservation method. To release it, call ReleaseReservation. You can determine if an Item is reserved by checking its ReservedBy property. If the Item is reserved, the value of this property is the member who has the reservation. If the Item is not reserved, the value of ReservedBy is NULL (C++) or Nothing (scripting languages). If the Item is reserved, you can also determine when it was reserved by accessing the WhenReserved property.

A user with "Can Edit" rights to an Item can mark it read only. While an Item is marked read only, no one on the "Can Edit" list can modify it in any way, except to turn off the read only setting. You cannot get an edit reservation on a read only Item, and you cannot mark a reserved Item read only. The main differences between a reserved Item and a read only Item are:

• The reservation is attributed to a user, while read only mode is not

• A reserved Item can by modified by the user that reserved it, while a read only Item cannot by modified by anybody, except to turn off read only.

Establishing User Context

Virtually all SAAPI calls execute under a particular user context. As of eRoom version 7, user context is per-thread. A user context object is used to represent an actual eRoom user context. When this object is destroyed, you return to the previous user context.

You establish a user context by calling the ERUApplication::LoginUser() or the ERUUserContext::ImpersonateUser() method. Once a user context has been established for a thread, the ERUUserContext (”r;eRoom.UserContext”) object can be used to establish a different user context.

User Context and Built-in Users

eRoom has several built-in users that are used for special purposes by the eRoom server. These accounts are exposed for use by SAAPI programmers and can be identified by their member IDs. The ERUBuiltInUserID enum defines the following special users:

erUserSiteAdministrator (1)
The built-in site administrator account has the full rights of a site administrator and can access all communities and all data in all eRooms. This user cannot access user sessions or validate passwords.

erUserSiteAuthenticator (2)
The built-in site authenticator user has rights to manipulate user sessions and validate user passwords. This user does not have rights in communities or any eRooms.

erUserSiteRestricted (5)
This built-in user has no rights in any community or eRoom. In most cases, this user is used when providing access via a Ticket to restrict access to only a specific target page, such as account recovery or self-set password pages.

Any of these special user’s member IDs can be used with methods that take a member ID such as GetMember(), ImpersonateUser(), LoginUser().

’r;# ASP Example: IERUUserContext::ImpersontateUser
Dim uc
Set uc=Server.CreateObject(”r;eRoom.UserContext”)
uc.ImpersonateUser erUserSiteAdministrator,erParamTypeID

How to determine the current user context

To determine which user context is in use, get the LoggedInMember property from the IERUApplication, IERUUserContext, IERUCustomContext, or IERUFacility interface.

How to change the current user context

If your SAAPI program needs to change user context once already established, you can use IERUUserContext::ImpersonateUser().  By creating a new user context object and calling ImpersonateUser(), you are establishing a new user context for the current thread.  This user context will remain in use until the object is destroyed or another user context is established.

’r;ASP Extension Example: A custom command already has a user context’r;   
'of the loggedin user.'

Sub Main(Context)    
   Response.write ”r;Context::LoggedinMember=” + Context.LoggedinMember.DisplayName    
   Dim uc    
   Set uc=Server.CreateObject(”r;eRoom.UserContext”)    
   uc.ImpersontateUser erUserSiteAuthenticator, erParamTypeID
’r;’’ do something as authenticator    
   Response.write ”r;UC::LoggedinMember=”
+uc.LoggedinMember.DispayName’r;   
   Additional user context could be established as needed&ldots;    
   set uc=NOTHING    
   Response.write ”r;Context::LoggedinMember=” +Context.LoggedinMember.DisplayName
’r; After release of user context, we’re back to pref. user.
End Sub