Using Security

Together with the PermissionValue collection, the following two properties determine access to a portal registry object:

• AuthorAccess

• PublicAccess

The AuthorAccess property determines whether the author of the object has access to the object.

The PublicAccess property determines whether the object is generally accessible or not. If this property is set to True, all users have access to the object.

These properties apply only to an object. They cannot be cascaded, that is, passed down to child objects.

The other object property used with security, the Authorized property, indicates whether a user is authorized to access an object. The value of this property depends on whether the user has access.

When you get a folder, content reference, content reference link, PageletCategory or Pagelet collection, only the items that the end-user is authorized to access are in the collection. Whether an object is contained in a collection is based on the following algorithm:

• If the object is marked as PublicAccess it is automatically accessible.

• If the object is marked as AuthorAccess and the current UserId is the Author it is accessible.

• If the current user is in a permission list (class) that is in the Permissions collection for that object.

• If the current user is in a permission list (class) that is in the CascadedPermissions collection for that object.

• If the current user has the Portal Administrator role.

When you access a content reference or folder using a valid name and one of the Find methods (FindCRefByURL, FindCRefByName, FindCRefForURL, or FindFolderByName) a content reference or folder is returned whether the user is authorized to it. When you use these methods, always check the Authorized property. This is the only property you can view from an object that an end-user isn't authorized to.

In addition, if you know the specific URL for a tab, you could specify that in the FindCRefByURL. The tab is returned whether the user is authorized to it, so you should always check the Authorized property.

To set non role-based permissions for a folder, content reference, content reference link, PageletCategory object, or Pagelet, you must access the PermissionValue collection for that object using the Permissions property. The PermissionValue objects refer to permission list values that already exist on the system, such as ALLPANLS, CUSTOMER, EMPLOYEE, and so on.

To set role-based permissions for a folder, content reference, or a content reference link that are not component or iScript, you must access the RolePermissionValue collection for that object using the RolePermissions property. The PermissionValue objects refer to role-based permission values that already exist on the system.

Both the PermissionValue collection and the RolePermissionValue collection return PermissionValue objects. Use the PermType property to determin if a particular PermissionValue is role-based or not.

For every PermissionValue object, you can chose whether all the child folders and content references of this folder have the same permissions. This is called cascading. You cascade permissions by setting the Cascade property to True.

There are two types of PermissionList collections you can access. One is returned by the Permissions and RolePermissions properties, the other by the CascadedPermissions and CascadedRolePermissions properties.

CascadedPermissions and CascadedRolePermissions

The CascadedPermissions and CascadedRolePermissions properties return the a collection for all the permissions for an object. It contains any permission list values set in any parent folder.

Note: You cannot add any PermissionValues to a collection returned by the CascadedPermissions or CascadedRolePermissions property. You can add values only to the collection returned by the Permissions or RolePermissions property.

You can add PermissionValues for a child folder, but you cannot delete any of the existing ones that are cascaded. Permissions are augmented, not overwritten, that is, the permissions are the sum of both the parent permissions and whatever is set at the current level.

Therefore, keep the following in mind when working with PermissionValues:

• Set permissions only at the level where they're needed.

• Cascade permissions only when necessary.

• Generally, don't set cascaded PermissionValues for the root folder.

• Only the values in a PermissionValue object cascade. Properties on the folder itself (such as PublicAccess or AuthorAccess) do not cascade.

For example, suppose your PortalRegistry had the following hierarchy:

Image: PortalRegistry hierarchy example

The following diagram illustrates PortalRegistry hierarchy example:

The following permission list values are assigned to the PermissionValue objects for the Employees folder, and both of them are cascaded:

• EMPLOYEE

• MANAGER

The Homepages and Benefits folders have the exact same permissions as the Employees folder, that is, all users associated with these two permission lists have access to these folders.

Suppose you decide that you don't want the permission list EMPLOYEE to access the Benefits folder. If you delete the EMPLOYEE PermissionValue from the Benefits PermissionValue collection, you have not altered the permissions. The permissions set at the parent folder, that is, at the Employees folder, can't be deleted, they can only be added to.

To make this change, you must:

• Change the Cascaded property for the EMPLOYEES PermissionValue in the Employees folder to False

• Add EMPLOYEES as a PermissionValue object to the Homepages folder.