Configuring Authorization for a Commerce Entity

Authorization is used to control access to services, operations, and data based on the identity of the shopper, business user, or application making the request. In order to configure authorization security for a commerce entity, you perform the following tasks:

1. Adding Authorization Rules to a Commerce Entity

2. Adding the Authorization Sequence Component to an Operation Sequence

3. Adding A New Scope to an Authorization Policy

4. Adding Identities to the Authorization Policy of the Commerce Entity

5. Adding the CommerceAuthorization Attributes in ChannelConfiguration.config

The following topic uses a hypothetical example to show how to apply authorization. In our example, a business user wants to send notifications or user alerts to customers through a rich Internet application (RIA). This scenario uses a delegated security model in which the routing service acts on the behalf of business users and shoppers. For more information about the flow of identity, see Understanding the Flow of Identity.

Adding Authorization Rules to a Commerce Entity

Operations are performed on a commerce entity. When you want to control the people or services that are allowed to perform operations on a commerce entity, you must add authorization rules to the commerce entity in MetadataDefinitions.xml.

To add authorization rules in MetadataDefinitions.xml, you must do the following

• If you are creating a new claimset, see Create ClaimsetDefinitions in Metadata

• Add Authorization Rules to the Commerce Entity

Create ClaimsetDefinitions in Metadata

A ClaimsetDefinition is a single or collection of claims used to assert authorization on a commerce entity. If a ClaimsetDefinition contains more than one claim, then the person or service must have all the claims within the ClaimsetDefinition to have authorization to proceed with a request.

In MetadataDefinitions.xml, ClaimsetDefinitions appear under the Channel element or DefaultChannel element for which you want to add ClaimsetDefinitions. Under the Channel element or DefaultChannel element, you add the ClaimsetDefinitions element.

Under the ClaimsetDefinitions element, specify the following attributes for each ClaimsetDefinition you want to add:

Element Name	Attribute	Description	Data Type
ClaimsetDefinition	name	Specifies the name of the single or collection of claims	String
Claim	name	Identifies the value of the claim to be included in the ClaimsetDefinition	String
Claim	claimType	Specifies the uniform resource identifier (URI) for the type of claim For example, the Role claim type is defined as https://schemas.microsoft.com/ws/2008/06/identity/claims/role	String
Claim	issuer	Specifies the name of the authority or identity provider that issues the claim. Note: By setting this attribute, you specify that the user's claims must originate from the specified issuer to satisfy this ClaimsetDefinition. You may want to set this attribute if all claims come from a specific security token service (STS). If you do not specify this attribute, claims from any issuer can be used to satisfy this ClaimsetDefinition.	String

For more information, see Security Services Authorization Schema.

In the following configuration example below, we created four new ClaimsetDefinitions:

• QueryUserAlert:This ClaimsetDefinition contains the CommerceQueryOperation role for the scope called UserAlert.

• UpdateUserAlert: This ClaimsetDefinition contains the CommerceUpdateOperation role for the scope called UserAlert.

• DeleteUserAlert: This ClaimsetDefinition contains the CommerceDeleteOperation role for the scope called UserAlert.

• CreateUserAlert: This ClaimsetDefinition contains the CommerceCreateOperation role for the scope called UserAlert.

The business user must belong to the role specified within the ClaimsetDefinition to have authorization to proceed with a request.

<DefaultChannel>
  <ClaimsetDefinitions>
      <ClaimsetDefinition name="QueryUserAlert">
        <Claim name="CommerceQueryOperation:UserAlert" claimType="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" />
      </ClaimsetDefinition>
      <ClaimsetDefinition name="UpdateUserAlert">
        <Claim name="CommerceUpdateOperation:UserAlert" claimType="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" />
      </ClaimsetDefinition>
      <ClaimsetDefinition name="DeleteUserAlert">
        <Claim name="CommerceDeleteOperation:UserAlert" claimType="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" />
      </ClaimsetDefinition>
      <ClaimsetDefinition name="CreateUserAlert">
        <Claim name="CommerceCreateOperation:UserAlert" claimType="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" />
      </ClaimsetDefinition>
…
</DefaultChannel>

Add Authorization Rules to the Commerce Entity in Metadata

In MetadataDefinitions.xml, you add authorization rules to a commerce entity by adding the Authorization element to the commerce entity. Authorization rules can be a claimset and/or a UserScope rule. The claimset authorization rule limits the business user based on his or her role(s), while the UserScope authorization rule limits the shopper to only his or her data.

Under the Authorization element, you specify the following attributes for each operation that requires authorization rules:

Element Name	Attribute Name	Description	Data Type
Operation	name	Specifies the name of the operation to which the UserScope or Claimset authorization rules apply	String
UserScope	propertyName	Specifies the name of the property used to restrict the current identity's access to data, operations, or services For example, if you specified the UserID property, then the user could only see data associated with his or her UserID.	String
Claimset	name	Specifies the name of the ClaimsetDefinition used to restrict access to data, operations, or services Note: A user must have ALL the claims specified within the ClaimsetDefinition to have authorization to proceed with a request.	String

When the Operation element has both UserScope and Claimset rules asserted, a user must have either the UserScope claim OR all the claims specified in the ClaimsetDefinition.

For more information, see Security Services Authorization Schema.

The following configuration example establishes permissions for the following operations on the UserAlert entity:

• Query: For this operation, there are two sets of authorization rules:

  • UserScope: This rule allows a shopper to view his or her user alerts only (where UserAlert.UserID = the shopper's user ID).

  • Claimset: This rule allows members of the CommerceQueryOperation:UserAlert role to query for any user alerts.

  The shopper's user ID must match the UserAlert.UserID or the business user must belong to the CommerceQueryOperation:UserAlert role (the only claim specified in the QueryUserAlert ClaimsetDefinition).

• Update: For this operation, only members of the CommerceUpdateOperation:UserAlert role (the only claim specified in the UpdateUserAlert ClaimsetDefinition) can modify user alerts.

• Delete: For this operation, there are two sets of authorization rules:

  • UserScope: This rule allows a shopper to delete his or her user alerts only (where UserAlert.UserID = the shopper's user ID).

  • Claimset: This rule allows members of the CommerceDeleteOperation:UserAlert role to delete any user alerts.

  The shopper's user ID must match the UserAlert.UserID or the business user must belong to the CommerceDeleteOperation:UserAlert role (the only claim specified in the DeleteUserAlert ClaimsetDefinition).

• Create: For this operation, only members of the CommerceCreateOperation:UserAlert role (the only claim specified in the CreateUserAlert ClaimsetDefinition) can create new user alerts.

<CommerceEntity name="UserAlert">
        <DisplayName value="User Alert" />
        <Authorization>
          <Operation name="Query">
            <UserScope propertyName="UserId">
              <Claimset name="QueryUserAlert"/>
            </UserScope>
          </Operation>
          <Operation name="Update">
            <Claimset name="UpdateUserAlert"/>
          </Operation>
          <Operation name="Delete">
            <UserScope propertyName="UserId">
              <Claimset name="DeleteUserAlert"/>
            </UserScope>
          </Operation>
          <Operation name="Create">
            <Claimset name="CreateUserAlert"/>
          </Operation>
        </Authorization>
        <Properties>
          <Property name="Id" dataType="String" />
          <Property name="UserId" dataType="String" />
          <Property name="Subject" dataType="String" />
          <Property name="Body" dataType="String" />
          <Property name="DateCreated" dataType="DateTime" />
        </Properties>
      </CommerceEntity>

Adding the Authorization Sequence Component to an Operation Sequence

Authorization is defined for a commerce entity in the MetadataDefinitions.xml file where the commerce entity model is described. Authorization is enforced at the operation sequence component level.

For authorization to work in Commerce Server 2009 R2, you must add the Authorization component to every message handler that acts on the commerce entity. 

A MessageHandler contains the operation sequence that consists of one or more components defined in a sequential order. When you create an operation sequence, you must order your components by the sequence component interface it implements and the order in which you want each component executed. For more information, see Commerce Foundation Operation Sequences and Operation Service Interpretation of the Operation Sequence.

In the following example for the UserAlert, we create four message handlers: CommerceCreateOperation_UserAlert, CommerceDeleteOperation_UserAlert, CommerceQueryOperation_UserAlert, and CommerceQueryOperation_UserAlert. For each message handler, we add the Authorization component and the other components that make up the operation sequence.

<MessageHandler name="CommerceQueryOperation_UserAlert"
  responseType="Microsoft.Commerce.CommerceQueryOperationResponse, Microsoft.Commerce, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
        <OperationSequence>
          <Component name="Authorization" type="Microsoft.Commerce.SequenceComponents.Components.AuthorizationSequenceComponent, Microsoft.Commerce.SequenceComponents, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35"/>
…
       </OperationSequence>
      </MessageHandler>

Adding a New Scope to an Authorization Policy

When you create a new commerce entity, as we did when we created UserAlert in our hypothetical example, you must do the following in the authorization policy using Authorization Manager (Azman):

• Create a new scope. The scope must share the same name as the commerce entity.

  In the hypothetical example, the scope name and commerce entity name is UserAlert.

• Create new role definitions. The role definition name must be named as it appears in the Claim name excluding the scope name of the ClaimsetDefinition.

  For example, if the Claim name is CommerceCreateOperation:UserAlert, the role definition name is CommerceCreateOperation. The scope name is UserAlert.

• Create new role assignments. You must assign the roles to the commerce entity that are required for authorization.

In the following procedure, we do the following in the CommerceEntityAuthorizationStore.xml authorization policy using Authorization Manager: create the UserAlert scope; create the CommerceCreateOperation, CommerceDeleteOperation CommerceQueryOperation, and CommerceUpdateOperation role definitions; and assign the newly created role definitions to the UserAlert commerce entity.

To add a commerce entity to an authorization policy

In a command prompt, type azman.msc. In the left pane of Authorization Manager, right-click Authorization Manager, and then click Options. From the Options dialog box, click Developer Mode. Note: Before proceeding, ensure the CommerceEntityAuthorizationStore.xml file is writable. In Window Explorer, right-click CommerceEntityAuthorizationStore.xml, and then click Properties. Ensure the Read-only box is unchecked. In the left pane of Authorization Manager, expand CommerceEntityAuthorizationStore.xml. Right-click CommerceFoundation, and then click New Scope. In the Name box, type the name of the commerce entity you would like to add, and then click OK. For example, in the Name box, type UserAlert. .Expand the Authorization Policy to CommerceFoundation\UserAlert\Definitions. Right-click Role Definitions, and click New Role Definition. In the Name box, type the name of the role as it appears in the Claim name property excluding the scope name, and then click OK. For example, if the claim name is CommerceCreateOperation:UserAlert, type CommerceCreateOperation for the role name. Repeat steps 8 and 9 for each additional role. For the hypothetical example, we must create the following additional roles: CommerceQueryOperation, CommerceUpdateOperation, and CommerceDeleteOperation. Right-click Role Assignments, and then click New Role Assignment. Select the role definitions that you created in steps 8 - 10 and whose Where Defined value is Scope, and then click OK. For the hypothetical example, select CommerceCreateOperation, CommerceDeleteOperation CommerceQueryOperation, and CommerceUpdateOperation.

Adding Identities to the Authorization Policy of the Commerce Entity

Once you have established the scope, role definitions, and role assignments, you can assign Windows users or groups or application groups to a role.

In our hypothetical example, we would assign business users to the CommerceCreateOperation, CommerceQueryOperation, CommerceUpdateOperation, and CommerceDeleteOperation roles under the Role Assignments of the UserAlert scope in the CommerceEntityAuthorizationStore.xml authorization policy.

For detailed information about adding users to an authorization policy role, see:

• How to Add a User Group to an Authorization Policy Role

• How to Add an Individual User to an Authorization Policy Role

• How to Add Users or Groups to Authorization Roles

• How to Add Users to Predefined Roles

Setting the CommerceAuthorization Attributes in Channel Configuration

For authorization to work in Commerce Server 2009 R2, you must set several authorization attributes in ChannelConfiguration.config for any channel(s) associated through metadata with commerce entities that require authorization. Specifically, you must do the following:

1. Set the level of authorization. You must set the authorizationDemand attribute to Required or Optional.

2. Set the mode of authorization: You must set the authorizationMode attribute to Automatic, Delegated, or TrustedSubsystem.

3. Identify and configure the claimstores: You must set the name, issuer and type attributes and specify the claimstore configuration.

The following table specifies the supported values for the following attributes under the CommerceAuthorization element:

Element Name	Attribute Name	Possible Attirbute Value	Description	Data Type
CommerceAuthorization	authorizationDemand	Required	Authorization is enforced and performed on all requests sent to the Commerce Server Foundation. In a deployment where the authorizationDemand attribute is set to Required, every operation sequence must have at least one component that implements the ICommerceAuthorizableSequenceComponent interface. For more information about operation sequences, see Commerce Foundation Operation Sequences and Operation Service Interpretation of the Operation Sequence.	String
		Optional	Authorization is enforced at the operation sequence level. Requests for operations that require no authorization (for example, getProducts) are served whether security information is included in the request or not. In a deployment where the authorizationDemand attribute is set to Optional, you can have a mix of operation sequences, some of which may or may not have components that require authorization. For more information about operation sequences, see Commerce Foundation Operation Sequences and Operation Service Interpretation of the Operation Sequence.	String
		Disabled	Authorization is not performed on any requests sent to the Commerce Server Foundation.	String
CommerceAuthorization	authorizationMode	Automatic	Specifies that the operation service automatically determines the appropriate method for loading claims based on the current WCF OperationContext. If the OperationContext.Current is null, TrustedSubsystem mode is used. Otherwise, Delegate mode is used. Note: This is the recommended setting.	String
		Delegated	Loads the claims for the incoming request thread identity.	String
		TrustedSubsystem	Loads the claims for the current process identity.	String

The following table specifies the supported values for the following attributes under the claimStores element:

Element Name	Attribute Name	Description	Data Type
claimStore	name	Specifies the unique name of the claimstore	String
claimStore	issuer	Specifies the name of the authority or identity provider that issues the claim In Commerce Server 2009 R2, the value of this attribute must match the Issuer attribute in MetadataDefinitions.xml of the ClaimsetDefinition that uses the claim, except when an STS is being used to issue claims.	String
claimStore	type	Specifies the fully qualified name of the class: namespace and class, assembly name, assembly version, culture, public key token.	String
Configuration	customElementName	Specifies the name of the element to be parsed by the Configuration element specified in the customElementType attribute and provided to the claimStore as configuration.	String
Configuration	customElementType	Specifies the fully qualified name (namespace and class, assembly name, assembly version, culture, public key token) of the Configuration element that parses the element specified in the customElementName attribute.	String
commerceAzmanClaimStore	policyFilePath Note   This attribute only applies to the customElementType Microsoft.Commerce.Server.Configuration.CommerceAzmanClaimStoreElement.	Specifies the path and file name of the authorization policy associated with the claimStore.	String
commerceAzmanClaimStore	Application Note   This attribute only applies to the customElementType Microsoft.Commerce.Server.Configuration.CommerceAzmanClaimStoreElement.	Specifies the name of the application referenced within the authorization policy file. For example, CommerceFoundation is the application referenced in the CommerceEntityAuthorizationStore.xml authorization policy.	String
commerceAzmanClaimStore	cachingEnabled	Specifies whether role assignments are cached for the duration of the refreshInterval to increase performance.	Boolean
commerceAzmanClaimStore	refreshInterval	Specifies the interval (hh:mm:ss) at which the claims of authenticated Windows users, such as business users and trusted subsystem Windows identities, are refreshed in the commerceAzmanClaimStore cache. This memory management feature limits the cache size by refreshing the claims of authenticated Windows users at the specified interval. The default value is 5 minutes. Note: If this attribute is not specified and the cachingEnabled attribute is set to true, the default value of 5 minutes is used.	TimeSpan
commerceAzmanClaimStore	claimType	Specifies the uniform resource identifier (URI) for the type of claims that are issued by this claimStore. For example, the default Role claim type is defined as https://schemas.microsoft.com/ws/2008/06/identity/claims/role	String
PrincipalCreator	Type	Specifies the fully qualified name (namespace and class, assembly name, assembly version, culture, public key token) of the PrincipalCreator.	String
Configuration	customElementName	Specifies the name of the element to be parsed by the Configuration element specified in the customElementType attribute and provided to the PrincipalCreator as configuration.	String
Configuration	customElementType	Specifies the fully qualified name (namespace and class, assembly name, assembly version, culture, public key token) of the Configuration element that parses the element specified in the customElementName attribute.	String
CommercePrincipalCreator	createWindowsClaimsIdentity	When true, the CommercePrincipalCreator converts incoming Windows identities into a CommerceWindowsClaimsIdentity. Set this attribute to true if you need to interact with Active Directory to load claims based on group membership or require Windows identity impersonation. Otherwise, incoming Windows identities are converted into a generic CommerceClaimsIdentity, which only supports loading claims from the claim stores specified in channel configuration. Note: If you set this value to true, you must be able to clone the Windows user token for the incoming identity.	Boolean

The sample configuration shows how authorization is configured in ChannelConfiguration.config:

<CommerceAuthorization authorizationDemand="Optional">
      <commerceClaimsProvider>
        <claimStores>
          <claimStore name="CatalogAuthorizationStore" issuer="SharePoint" type="Microsoft.Commerce.Server.CommerceAzmanClaimStore, Microsoft.Commerce.Server, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
            <Configuration customElementName="commerceAzmanClaimStore" customElementType="Microsoft.Commerce.Server.Configuration.CommerceAzmanClaimStoreElement, Microsoft.Commerce.Server, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
              <commerceAzmanClaimStore policyFilePath="C:\inetpub\wwwroot\wss\VirtualDirectories\808059a6fc42-aed4-4ee2-95c1-5d4354ca74b1\CatalogAuthorizationStore.xml" application="CatalogandInventorySystem" cachingEnabled="true" claimType="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" />
            </Configuration>
          </claimStore>
          <claimStore name="ProfileAuthorizationStore" issuer="SharePoint" type="Microsoft.Commerce.Server.CommerceAzmanClaimStore, Microsoft.Commerce.Server, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
            <Configuration customElementName="commerceAzmanClaimStore" customElementType="Microsoft.Commerce.Server.Configuration.CommerceAzmanClaimStoreElement, Microsoft.Commerce.Server, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
              <commerceAzmanClaimStore policyFilePath="C:\inetpub\wwwroot\wss\VirtualDirectories\808059a6fc42-aed4-4ee2-95c1-5d4354ca74b1\ProfilesAuthorizationStore.xml" application="ProfileSystem" cachingEnabled="true" claimType="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" />
            </Configuration>
          </claimStore>
          <claimStore name="OrderAuthorizationStore" issuer="SharePoint" type="Microsoft.Commerce.Server.CommerceAzmanClaimStore, Microsoft.Commerce.Server, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
            <Configuration customElementName="commerceAzmanClaimStore" customElementType="Microsoft.Commerce.Server.Configuration.CommerceAzmanClaimStoreElement, Microsoft.Commerce.Server, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
              <commerceAzmanClaimStore policyFilePath="C:\inetpub\wwwroot\wss\VirtualDirectories\808059a6fc42-aed4-4ee2-95c1-5d4354ca74b1\OrdersAuthorizationStore.xml" application="OrderSystem" cachingEnabled="true" claimType="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" />
            </Configuration>
          </claimStore>
          <claimStore name="CommerceEntityAuthorizationStore" issuer="SharePoint" type="Microsoft.Commerce.Server.CommerceAzmanClaimStore, Microsoft.Commerce.Server, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
            <Configuration customElementName="commerceAzmanClaimStore" customElementType="Microsoft.Commerce.Server.Configuration.CommerceAzmanClaimStoreElement, Microsoft.Commerce.Server, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
              <commerceAzmanClaimStore policyFilePath="C:\inetpub\wwwroot\wss\VirtualDirectories\808059a6fc42-aed4-4ee2-95c1-5d4354ca74b1\CommerceEntityAuthorizationStore.xml" application="CommerceFoundation" cachingEnabled="true" claimType="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" />
            </Configuration>
          </claimStore>
          <claimStore name="UserIdClaimStore" issuer="UserIdClaimStore" type="Microsoft.Commerce.Server.CommerceUserIdClaimStore, Microsoft.Commerce.Server, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
            <Configuration customElementName="commerceUserIdClaimStore" customElementType="Microsoft.Commerce.Server.Configuration.CommerceUserIdClaimStoreElement, Microsoft.Commerce.Server, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
              <commerceUserIdClaimStore authorizedUsers="*" />
            </Configuration>
          </claimStore>
        </claimStores>
       <principalCreator type="Microsoft.Commerce.Server.CommercePrincipalCreator, Microsoft.Commerce.Server, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
          <Configuration customElementName="commercePrincipalCreator" customElementType="Microsoft.Commerce.Server.Configuration.CommercePrincipalCreatorElement, Microsoft.Commerce.Server, Version=9.0.0.0, Culture=neutral,PublicKeyToken=31bf3856ad364e35">
            <commercePrincipalCreator createWindowsClaimsIdentity="false"/>
          </Configuration>
        </principalCreator>
      </commerceClaimsProvider>
    </CommerceAuthorization>

In this configuration, the CommerceAzmanClaimStore generates claims about the user by loading and parsing the authorization policy (.xml file) specified in the policyFilePath attribute.

The commerceUserIdClaimStore is used to generate claims for an incoming identity that is not a claims-based identity. It is also used any time someone executes a query for CommerceClaim entities.

The commerceUserIdClaimStore creates claims in the following situations:

• If the WCF OperationContext is non-null and contains headers issued by the CommerceUserRecognition class, the commerceUserIdClaimStore attempts to issue claims based on the WCF headers. If the user requesting the claims appears in the authorizedUsers list of the commerceUserRecognition configuration, the commerceUserIdClaimStore generates claims. Otherwise, the commerceUserIdClaimStore does not generate claims because the request came from an untrusted user.

• If there is no WCF operation context or CommerceUserRecognition WCF header present, the commerceUserIdClaimStore attempts to issue claims based on CommerceUserContext.Current. If CommerceUserContext.Current is non-null, the commerceUserIdClaimStore generates claims. Otherwise, the commerceUserIdClaimStore does not generate claims.

You must configure authorization for each channel and for each ChannelConfiguration.config file in your deployment. For two-tier deployments, you must configure authorization for both the external and internal zone.

See Also

Other Resources

Understanding Claims-Based Identity

Managing Authentication

Managing Authorization

Commerce Foundation Operation Sequences

Operation Service Interpretation of the Operation Sequence

How to Add a User Group to an Authorization Policy Role

How to Add an Individual User to an Authorization Policy Role

How to Add Users or Groups to Authorization Roles

How to Add Users to Predefined Roles