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:
Adding Authorization Rules to a Commerce Entity
Adding the Authorization Sequence Component to an Operation Sequence
Adding A New Scope to an Authorization Policy
Adding Identities to the Authorization Policy of the Commerce Entity
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.
Note
Each channel inherits metadata from the DefaultChannel. If you put a new ClaimsetDefinition under the DefaultChannel element, all other channels will have the new ClaimsetDefinition as well. If you put the new ClaimsetDefinition under a specific Channel element, then only that channel will have the new ClaimsetDefinition. To avoid inheriting ClaimsetDefinitions from the DefaultChannel, add a <Clear /> tag at the beginning of the ClaimsetDefinitions list for the other channels. In so doing, none of the ClaimsetDefinitions from the DefaultChannel persist to the channels with the <Clear /> tag. For more information, see Commerce Foundation Metadata Repository Design.
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 |
---|
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.
|
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:
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:
Set the level of authorization. You must set the authorizationDemand attribute to Required or Optional.
Set the mode of authorization: You must set the authorizationMode attribute to Automatic, Delegated, or TrustedSubsystem.
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
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