Defining policies

There are many instances where it is necessary to define a new access group.

About this task

For example:

You have created a new role. New policies are then necessary to grant users with this new role to run certain commands.
You have created a new controller command and want to assign users with particular roles to access these commands.

The WC_installdir/xml/policies/xml/defaultAccessControlPolicies.xml file defines the default access control policies that are shipped out-of-the-box. It follows the DTD specified by: WC_installdir/xml/policies/dtd/accesscontrolpolicies.dtd.

The following is the template of a policy element:


<Policy Name="value"
        OwnerId="value"
        UserGroup="value"
        UserGroupOwner="value"
        ActionGroupName="value"
        ResourceGroupName="value"
        PolicyType="value"
        RelationName="value"
        RelationGroupName="value"
        RelationGroupOwner="value"
</Policy>

where:

Name

The name of the policy. This is loaded into the POLICYNAME column of the ACPOLICY table. The Name and OwnerID together must be unique.

OwnerID

The member ID of the organizational entity that owns the policy. This will be loaded into the member_id column of the ACPOLICY table. The OwnerID and Name together must be unique. There are two special values that are recognized by the transformer tool, these are the

RootOrganization:
-2001

, and DefaultOrganization: -2000

UserGroup

The name of the access group specified in the MBRGRPNAME column of the MBRGRP table. This is loaded into the mbrgrp_id column of the ACPOLICY table. The default access groups are defined in the WC_installdir/xml/policies/xml/ACUserGroups_language.xml file.

UserGroupOwner

The member ID of the member that owns the Access Group. This is needed when the access group is owned by a member other than the policy owner. If this is not specified, it is assumed that the access group is owned by the member that is specified by the OwnerID attribute.

ActionGroupName

The name of the action group specified in GROUPNAME column of ACACTGRP table. It is used to get the corresponding action group ID ( ACACTGRP_ID) that will be stored in the ACPOLICY table. Role-based policies for controller commands have ActionGroupName set to ExecuteCommandActionGroup. Policies for data beans have ActionGroupName set to DisplayDatabeanActionGroup.

ResourceGroupName

The name of the Resource Group, specified in the GRPNAME column of the ACRESGRP table. It is used to get the corresponding resource group ID ( ACRESGRP_ID) that is stored in the ACPOLICY table. Role-based policies for views have ResoureGroupName set to ViewCommandResourceGroup.

PolicyType

The type of policy. Valid values are groupableStandard and groupableTemplate. For backward compatibility, the values standard and template are also supported. If this attribute is unspecified when loading a new policy, the value null will be used. If this attribute is unspecified when updating an existing policy, the value will remain unchanged. The following table displays the mapping of string values to database values stored in the POLICYTYPE column of ACPOLICY table.

Mapping of string values to database values
String	ACPOLICY.POLICYTYPE	Usage
groupableTemplate	3	Used when the UserGroup of the policy contains a dynamic element that needs to be evaluated at runtime. For example, in the following UserGroup definition, it contains the qualifier of `OrgAndAncestorOrgs`: `<simpleCondition> <variable name="role"/> <operator name="="/> <value data="Marketing Manager"/> <qualifier name="org" data="OrgAndAncestorOrgs"/> </simpleCondition>` When this policy is evaluated at runtime, the access control framework will check to see if the user has the role in the organization that owns the resource, or any of its ancestor organizations.
groupableStandard	2	Used when the UserGroup of the policy does not contain any dynamic elements that need to be evaluated at runtime. For example, in the following UserGroup definitions, there is no qualifier. It simply evaluates true if the user has the role of Marketing Manager in any organization: `<simpleCondition> <variable name="role"/> <operator name="="/> <value data="Marketing Manager"/> </simpleCondition>` The `AllUsers` UserGroup is an example of a member group that does not have any dynamic conditions. It simply evaluates to true: `<profile> <trueCondition> </trueCondition> </profile>`
template	1	deprecated
standard	0 or null	deprecated

RelationName (optional)

The name of the Relationship, as specified in the RELATIONNAME column of the ACRELATION table. If it is specified, it is used to get the corresponding relationship ID ( ACRELATION_ID) that is stored in the ACPOLICY table.

RelationGroupName (optional)

The name of the Relationship Group, as specified in the GRPNAME column of the ACRELGRP table. If this attribute is specified, RelationName should not be specified, since Relationship Group takes precedence.

RelationGroupOwner

The member ID that owns the Relation Group. This attribute is necessary only if the RelationGroupName attribute is specified and if the value of the OwnerID attribute is not RootOrganization; in this case, RelationGroupOwner must be specified as RootOrganization (-2001).

Policy examples

Role-based policies

For controller commands

In this example, users belonging to the AllUsers access group can execute controller commands that are part of the AllUserCmdResourceGroup resource group.


<Policy Name="AllUsersExceuteAllUserCmdResourceGroup"
                        OwnerID="RootOrganization"
                        UserGroup="AllUsers"
                        ActionGroupName="ExecuteCommandActionGroup"
                        ResourceGroupName="AllUserCmdResourceGroup"
                        PolicyType="groupableStandard">
</Policy>

For views

In this example, users belonging to the MarketingManagers access group can execute the views belonging to MarketingManagersViews action group.


<Policy Name="MarketingManagersExecuteMarketingManagersViews"
                        OwnerID="RootOrganization"
                        UserGroup="MarketingManagers"
                        ActionGroupName="MarketingManagersViews"
                       
ResourceGroupName="ViewCommandResourceGroup"
                        PolicyType="groupableStandard">
</Policy>

Resource-level policies

For commands

In this example, users belonging to AllUsers access group can perform the actions specified by the CouponRedemption action group on resources specified by the CouponWalletResourceGroup, as long as the users fulfill the creator relationship with respect to the resource.


<Policy
Name="AllUsersExecuteCouponRedemptionCommandsOnCouponWalletResource"
                        OwnerID="RootOrganization"
                        UserGroup="AllUsers"
                        ActionGroupName="CouponRedemption"
                       
ResourceGroupName="CouponWalletResourceGroup"
                        RelationName="creator"
                        PolicyType="groupableStandard">
</Policy>

For data beans

In this example, users belonging to the AllUsers access group can Display data beans specified by the UserDatabeanResourceGroup resource group, as long as the users fulfill the owner relationship with respect to the resource.


<Policy Name="AllUsersDisplayUserDatabeanResourceGroup"
                        OwnerID="RootOrganization"
                        UserGroup="AllUsers"
                       
ActionGroupName="DisplayDatabeanActionGroup"
                       
ResourceGroupName="UserDatabeanResourceGroup"
                        RelationName="owner"
                        PolicyType="groupableStandard">
</Policy>

Groupable template policies

In this example, users belonging to the OrgAdminConsoleMembershipAdministratorsForOrg access group, can perform the actions specified by the ApproveGroupUpdate action group on resources specified by the OrganizationDataResourceGroup.


<Policy
Name="OrgAdminConsoleMembershipAdministratorsForOrgExecuteApprove
GroupUpdateCommandsOnOrganizationResource"
                        OwnerID="RootOrganization"
                       
UserGroup="OrgAdminConsoleMembershipAdministratorsForOrg"
                        ActionGroupName="ApproveGroupUpdate"
                       
ResourceGroupName="OrganizationDataResourceGroup"
                        PolicyType="groupableTemplate">
</Policy>

Examining the definition of the OrgAdminConsoleMembershipAdministratorsForOrg access group would reveal the following condition for membership:


<UserCondition>                      
        <profile>
                                <orListCondition>
                                        <simpleCondition>
                                                <variablename="role"/>
                                                <operatorname="="/>
                                                <valuedata="Buyer Administrator"/>
                                                <qualifiername="org" data="OrgAndAncestorOrgs"/>
                                        </simpleCondition>
                                        <simpleCondition>
                                                <variablename="role"/>
                                                <operatorname="="/>
                                                <valuedata="Seller Administrator"/>
                                                <qualifiername="org" data="OrgAndAncestorOrgs"/>
                                        </simpleCondition>
                                        <simpleCondition>
                                                <variablename="role"/>
                                                <operatorname="="/>
                                                <valuedata="Channel Manager"/>
                                                <qualifiername="org" data="OrgAndAncestorOrgs"/>
                                        </simpleCondition>
                                </orListCondition>
                        </profile>
                UserCondition>

Note: The simpleCondition of role is qualified by

org =
OrgAndAncestorOrgs

. OrgAndAncestorOrgs is a keyword that is only available in groupable template policies. It dynamically scopes the role to the context of the current resource's owner. In this example, the user must have one of the specified roles in the organization that owns the resource, or any of the organization's ancestors.

Defining policy groups

Policy groups are created to group policies, based on business and access control requirements. Some default policy groups are created out of the box; for more information see, . Other policy groups are created, as needed, while publishing a store or a business model. In most cases you can simply add any new policies you create to existing policy groups. If you need to create a new policy group, you should define it in an XML file, similar to defaultAccessControlPolicies.xml, and then load it to the database. Here is a sample definition:


<PolicyGroup Name="aValue" OwnerID="aValue">
        </PolicyGroup>

where:

Name: The name of the policy group.
OwnerID: The member ID of the organizational entity that owns the policy group. This will be loaded into the member_id column of the ACPOLGRP table. The OwnerID and Name together must be unique. There are two special values that are recognized by the transformer tool, these are the RootOrganization: -2001, and DefaultOrganization: -2000.

Associating policies with policy groups

Policies can belong to multiple policy groups. However, to ease administration of policies, it is recommended that a policy belong to only one policy group. This association should be defined in an XML file, similar to defaultAccessControlPolicies.xml, and then loaded to the database. Here is a sample definition:


<PolicyGroup Name="aValue" OwnerID="aValue">
                <PolicyGroupPolicy   Name="aValue"
PolicyOwnerID="aValue" />
</PolicyGroup>

where:

PolicyGroupPolicy Name: The name of the policy, previously defined, to be associated with the specified policy group. This policy must have one of the following policy types: groupableStandard or groupableTemplate.
PolicyGroupPolicy PolicyOwnerID (optional): The member ID of the organizational entity that owns the specified policy. If this parameter is not specified, the default value is OwnerID of the policy group. There are two special values that are recognized by the transformer tool, these are the RootOrganization: -2001, and DefaultOrganization: -2000.

Subscribing to policy groups

The resources of an organization are protected by the policies in the policy groups to which that organization subscribes. If that organization does not subscribe to any policy groups, then the policy groups to which that organization's closest ancestor subscribes will apply.

Policy group subscription can be done in the Organization Administration Console, but can also be defined in an XML file, similar to defaultAccessControlPolicies.xml, and then loaded to the database. Here is a sample definition:


<PolicyGroup Name="aValue" OwnerID="aValue">
                <PolicyGroupSubscription
OrganizationID="aValue"/>
        </PolicyGroup>

where:

OrganizationID: The member ID of the organizational entity that is subscribing to this policy group. There are two special values that are recognized by the transformer tool, these are the RootOrganization: -2001, and DefaultOrganization: -2000.

Translatable policy data

The following is a template of a customized policy file that can be used to define translatable policy data:


 <?xml version="1.0" encoding="ISO-8859-1" standalone="no" ?>
        <!--The following TRANSLATABLE access control elements should be defined in this file: 
        <Attribute_nls>
        <Action_nls> 
        <Relation_nls>
        <ResourceCategory_nls>
        <ActionGroup_nls>
        <ResourceGroup_nls> 
        <Policy_nls>
        <PolicyGroup_nls>-->
<!DOCTYPE PoliciesNLS SYSTEM
"../dtd/accesscontrolpoliciesnls.dtd">

<PoliciesNLS LanguageID="value">

 
 <!--Insert access control element definitions here --> 
 </PoliciesNLS>

The LanguageID attribute is a string corresponding to the language of the locale-specific data. Valid values of the LanguageID are:

de_DE
en_US
es_ES
fr_FR
it_IT
ja_JP
ko_KR
pt_BR
zh_CN
zh_TW

Non-translatable policy data

The following is a template of a customized policy file containing non-translatable data:


   <?xml version="1.0" encoding="ISO-8859-1" standalone="no"
?> 

<!DOCTYPE Policies SYSTEM "../dtd/accesscontrolpolicies.dtd">
 
        <!--The following NON-TRANSLATABLE access control
elements
 should be defined in this file:

        <Attribute>
        <Action>
        <ResourceCategory>
        <Relation>
        <RelationGroup>
        <ActionGroup>
        <ResourceGroup>
        <Policy>
        <PolicyGroup>-->
<Policies>

 <!--Insert access control element definitions here-->
 </Policies>

Locale-specific data

The following optional locale-specific data can be loaded to give additional description to the access control elements already defined in the non-translatable XML file. The default locale-specific data can be found at the following address:


WC_installdir\xml\policies\xml\defaultAccessControlPolicies_locale.xml

For example, defaultAccessControlPolicies_en_US.xml.

Attribute

The following example defines additional attribute element information:


<Atrribute_nls AttributeName="Status"
DisplayName_nls="Status attribute"
Description_nls="Resource status attribute"
/>

where:

AttributeName: The name of the attribute. This value is stored in the ATTRNAME column of the ACATTR table.
DisplayName_nls: The display name of the attribute. This value is stored in the DISPLAYNAME column of the ACATTRDESC table.
Description_nls: An optional description of the attribute. This value is stored in the DESCRIPTION column of the ACATTRDESC table.

Action

The following example defines additional action element information:


<Action_nls ActionName="OrderAdjustmentButton"
DisplayName_nls="Order Adjustment Button View"
Description_nls="The view for loading buttons in the order adjustment page when placing an order from Commerce Acclerator"
/>

where:

ActionName: The name of the action. This value is stored in the ACTION column of the ACACTION table.
DisplayName_nls: The display name of the action. This value is stored in the DISPLAYNAME column of the ACACTDESC table.
Description_nls: An optional description of the action. This value is stored in the DESCRIPTION column of the ACACTDESC table.

Relation

The following example defines additional relation element information:


<Relation_nls RelationName="creator"
DisplayName_nls="creator"
Description_nls="creator"
/>

where:

RelationName: The name of the relationship. This value is stored in the RELATIONNAME column of the ACRELATION table.
DisplayName_nls: The display name of the relationship. This value is stored in the DISPLAYNAME column of the ACRELDESC table.
Description_nls: An optional description of the relationship. This value is stored in the DESCRIPTION column of the ACRELDESC table.

Resource Category

The following example defines additional resource category information:


<ResourceCategory_nls ResourceCategoryName="com.ibm.commerce.
catalog.objects."InterestItemList"
DisplayName_nls="Interest Item List"
Description_nls="Interest Item List command"
/>

where:

ResourceCategoryName: The name of the resource category. This value is stored in the RESCLASSNAME column of the ACRESCGRY table.
DisplayName_nls: The display name of the resource category. This value is stored in the DISPLAYNAME column of the ACRSCGDES table.
Description_nls: An optional description of the resource category. This value is stored in the DESCRIPTION column of the ACRSCGDES table.

Action Group

The following example defines additional action group information:


<ActionGroup_nls ActionGroupName="DoEverything"
DisplayName_nls="Do Everything"
Description_nls="Permits access to all Actions"
/>

where:

ActionGroupName: The name of the action group. This value is stored in the GROUPNAME column of the ACACTGRP table.
DisplayName_nls: The display name of the action group. This value is stored in the DISPLAYNAME column of the ACACGPDESC table.
Description_nls: An optional description of the action group. This value is stored in the DESCRIPTION column of the ACACGPDESC table.

Resource Group

The following example defines additional resource group information:


<ResourceGroup_nls ResourceGroupName="AllResourceGroup"
DisplayName_nls="All Resources Group"
Description_nls="All Resources"
/>

where:

ResourceGroupName: The name of the resource group. This value is stored in the GRPNAME column of the ACRESGRP table.
DisplayName_nls: The display name of the resource group. This value is stored in the DISPLAYNAME column of the ACRESGPDES table.
Description_nls: An optional description of the resource group. This value is stored in the DESCRIPTION column of the ACRESGPDES table.

Policy

The following example defines additional policy information:


<Policy_nls PolicyName="SiteAdministratorsCanDoEverything"
OwnerID="RootOrganization"
DisplayName_nls="Site Administrators Can Do Everything"
Description_nls="Policy that allows Site Administrators to do everything"
/>

where:

PolicyName: The name of the access control policy. This value is stored in the POLICYNAME column of the ACPOLICY table.
OwnerID: The member ID of the organizational entity that owns this policy.
DisplayName_nls: The display name of the policy. This value is stored in the DISPLAYNAME column of the ACPOLDESC table.
Description_nls: An optional description of the policy. This value is stored in the DESCRIPTION column of the ACPOLDESC table.

Policy group

The following example defines additional policy group information:


<PolicyGroup_nls PolicyGroupName="B2CPolicyGroup"
OwnerID="RootOrganization"
                DisplayName_nls="B2C Policy Group"
                Description_nls="This policy group contains all the B2C specific policies."
        />

where:

PolicyGroupName: The name of the access control policy group to which additional information is being added. This value is found in the NAME column of the ACPOLGRP table.
OwnerID: The member ID of the organizational entity that owns this policy group.
DisplayName_nls: The display name of the policy group. This value is stored in the DISPLAYNAME column of the ACPLGPDESC table.
Description_nls: An optional description of the policy group. This value is stored in the DESCRIPTION column of the ACPLGPDESC table.