Example: Examining an access control policy

In this section, you look at one of the default policies in detail, using a series of different examples. The policy you will study is the following:

AuctionAdministratorsForOrgExecuteAuctionManageCommandsOnAuctionResource

Note: This policy is a resource-level policy. The policy type is groupable template.

The first example shows how to read the policy using the Organization Administration Console, identify its parts, and understand what the policy means. The second example will look at the policy in XML, to help you understand what the same information looks like in the code.

The third example goes a step further in understanding how one policy is related to other policies. Understanding dependencies between policies is an important prerequisite for making changes to access control policies, or creating new ones.

Example 1: Reading a policy

In this example, you use the Organization Administration Console to look up a policy and identify the parts that define it. You also use these parts to form a general description of the policy.

Looking up the policy in the Organization Administration Console

Log in to the Organization Administration Console. From the Access Management menu, select Policies.
Select Root Organization from the list box, since Root Organization owns most of the default access control policies.
On the Policies page, scroll through the list of policies and locate the following policy: AuctionAdministratorsForOrgExecuteAuctionManageCommandsOnAuctionResource
Notice that you can scroll through the list of policies by using the scroll bar as well as using the First, Previous, Next and Last links.

Viewing the parts of the policy

Select the policy by clicking the box next to it and click Show Action Group.
On the Action Group page, you will see the action group, AuctionManage. This is the action group associated with the policy. Select AuctionManage and click Show Actions.
On the next page, you will see the following list of actions, or commands, included in the AuctionManage action group:
- com.ibm.commerce.negotiation.commands.CloseBiddingCmd
- com.ibm.commerce.negotiation.commands.DeleteAuctionCmd
- com.ibm.commerce.negotiation.commands.ModifyAuctionCmd
Here, AuctionManage includes closing an auction (CloseBiddingCmd), deleting an auction, (DeleteAuctionCmd), and modifying an auction (ModifyAuctionCmd)

Notice that you can also access the same list of actions from the Policies page by clicking Show Actions.
To return to the policies page, select any of the actions, and click Show Policies.
Select the policy again, but now click Show Member Group to see the member (access) group that is used in this policy.
Make a note of the member (access) group name. In this case, the member (access) group is AuctionAdministratorsForOrg.
From the Access Management menu, select Access Groups.
Find AuctionAdministratorsForOrg. Select it and click Change.
Click Criteria. On the Criteria page, look under Selected roles and organizations. You should see the following roles:
- Seller-For organization
- Product Manager-For organization
- Buyer (sell-side)-For organization
- Category Manager-For organization
Any user assigned one of these roles for the organization that owns the auction resource, is part of the AuctionAdministratorsForOrg access group.
Leave the Criteria page without making any changes. From the Access Management menu, select Policies again. Locate the following policy:
```
AuctionAdministratorsForOrgExecuteAuctionManageCommandsOnAuctionResource
```
Select the policy and Click Show Resources. On the Resources page, you will see the com.ibm.commerce.negotiation.objects.Auction resource. This is the resource on which the actions listed in the action group act. In this case, the resource is an auction. Notice that you can access this same list from the Policies page by clicking Show Resource Group and drilling down to the individual resources.
Now select Policies from the Access Management menu, and locate the following policy:
```
AuctionAdministratorsForOrgExecuteAuctionManageCommandsOnAuctionResource
```
Select the policy and click Change. On the Change Policy page, look at the drop-down menu under Relationship. Note that the relationship is set to none. This means that the policy does not have a relationship.
Click Cancel and OK to the dialog box.

Understanding what the policy means

Now that you have identified the individual parts of this policy, you can start to piece them together to understand what the policy does. First, you know that the policy applies to all users belonging to the AuctionAdministratorsForOrg group. You learned this by clicking Show Member Group. From there you used the Access Management menu to go to the Access Group page, and saw that the access group included the following roles: seller, product manager, buyer (for the sell-side), and the category manager. Collectively, users with one of these four roles can be referred to as an Auction Administrator.

You also know that the action group contains the commands for modifying, retracting, and closing an auction, and that the resource group includes only the auction resource that is being managed. Again, you know this by clicking Show Actions and Show Resources from the Policies page and drilling to the detail level. Lastly, you can tell that the policy does not include a relationship between the access group and the resources.

Putting everything together, you can conclude that this policy permits Auction Administrators to perform all the activities associated with managing auctions on an auction resource, such as modifying, retracting, and closing an auction, as long as the administrator plays the role for the organization that owns the auction.

You can get a sense of what a policy means by looking at its name. In this example, the policy starts with the name of the designated group of users, AuctionAdministratorForOrg. The notation, ForOrg, indicates that this is a groupable template policy. AuctionManageCommands describes the action group, and AuctionResource describes the resource group.

Example 2: Reading a policy in XML

The default access control policies are stored in an XML file that is loaded into your database during instance creation. When you look at a policy in the Organization Administration Console, you are using the interface to view and make changes to the information stored in the database. The information in the database is used by the Policy Manager to evaluate access control. If the database information is more recent than the XML file, you can use the Extractor tool to extract the access control policy information from the database into an XML file.

This is what a policy looks like in the XML file:


<!-- AuctionAdministrators manage Auctions (Retract/delete auction, Modify auction, Close Auction)-->
<Policy Name="AuctionAdministratorsForOrgExecuteAuctionManageCommandsOnAuctionResource"
        OwnerID="RootOrganization"
        UserGroup="AuctionAdministratorsForOrg"
        ActionGroupName="AuctionManage"
        ResourceGroupName="AuctionDataResourceGroup"
        PolicyType="groupableTemplate">
</Policy>

Here, the policy is defined by the following:

Name: The name of the policy.
OwnerID: The organization for which the policy applies.
UserGroup: The access group.
ActionGroupName: The action group.
ResourceGroupName: The resource group.
PolicyType: The type of policy, such as groupable standard or groupable template.

The file that contains all of the default access control policies is called defaultAccessControlPolicies.xml and is located in the following directory:

WC_installdir\xml\policies\xml.

Note: The descriptions for each default access control file are contained in the defaultAccessControlPolicies_locale.xml file, which can be found in the same directory. A change made to a default access control policy in the default access control file, needs to have its corresponding description updated in defaultAccessControlPolicies_en_US.xml. It is strongly recommended that any changes made to the XML files be reserved for advanced users.

Example 3: Identifying other policies associated with your policy

In this last example, you will take a look at how an access control policy can have dependencies on other policies.

Policies that define the commands (actions) that a group of users (an access group) can perform on a resource are called resource-level policies. For example, the policy you have been looking at in detail:

AuctionAdministratorsForOrgExecuteAuctionManageCommandsOnAuctionResource is an example of a resource-level policy.

However, the actions permitted by a resource-level policy are also dependent on the actions permitted for each role belonging to the policy's access group. Policies that describe what actions are permitted for a particular role are called role-based policies.

To identify the role-based policies associated with a resource-level policy, do the following:

Looking up the roles associated with the policy

Open the Organization Administration Console and locate the resource-level policy on the Policies page. Using the same example, you know the policy you want is the following:
```
AuctionAdministratorsForOrgExecuteAuctionManageCommandsOnAuctionResource
```
Identify the access group associated with the policy. In this case, you already know that the access group is AuctionAdministratorsForOrg.
Look up the roles associated with the access group. For AuctionAdministratorsForOrg, you know from the previous examples that the roles are: Buyers (sell-side), Category Managers, Product Manager, and Sellers.

Looking up the role-based policies for each role

Locate each role-based policy associated with a role.
Find the Buyers(sell-side)ExecuteBuyers(sell-side)CommandsResourceGroup policy. This policy is associated with the Buyers (sell-side) role. You know this because of the Buyers(sell-side) prefix to the policy.
Find the rest of the role-based policies associated with Buyers (sell-side), Category Manager, Product Manager, and Sellers roles, using their prefixes to identify the right policies. You should come up with the following list:
- Buyers(sell-side)ExecuteBuyers(sell-side)CommandsResourceGroup
- Buyers(sell-side)ExecuteBuyers(sell-side)Views
- CategoryManagersExecuteCategoryManagersCmdResourceGroup
- CategoryManagersExecuteCategoryManagersViews
- ProductManagersExecuteProductManagersCmdResourceGroup
- ProductManagersExecuteProductManagersViews
- SellersExecuteSellersCmdResourceGroup
- SellersExecuteSellersViews
Each role-based policy permits users with that role to carry out particular controller commands or views. To see what actions and resources are associated with a role-based policy, look up the policy on the Policies page from the Organization Administration Console, using the same procedure from Example 1.

Why identifying dependencies between policies is important

Understanding which role-based policies are associated with a resource-level policy is often a prerequisite for customizing your policies, and for creating new ones.