Understand role-based access control

You can control your internal user's access to specific catalogs and price groups.

You have a great deal of flexibility in setting up access control to align with the way that your business users work within your organization. You can configure access for situations where your business runs multiple country or brand sites that use different catalogs and price groups and are managed by separate teams. Or in situations where your business sells to multiple accounts, you can configure access for the teams that manage their catalogs and price groups.

You can enhance access control in these situations by creating security criteria that grant or deny the ability to update specific catalogs or price groups. By adding security criteria to roles, and then assigning the roles to your users, you can allow your users to make changes only to the catalog assets and prices for which they are authorized.

By using multiple roles, privileges and security criteria, you can provide multiple levels of access. For example, a graphic designer needs different access to the administration interface than a merchandiser who sets up catalogs. Creating specific access controls ensures that internal users have the correct access and abilities to perform their jobs effectively.

Consider access control settings

When configuring access control, it's important to take the following into consideration:

Make sure that your access control strategy is easy to understand and easy to implement. Overly complex access control strategies will be hard to maintain as your environment grows.
Identify functions that the internal users perform, and what access is required. You can set up restrictions to various data or areas to the administration interface depending on the user's tasks.
Identify roles that the internal users can be given. For example, is the user a designer, a merchandiser or an administrator? These can all be roles that indicate the user performs a specific task. A designer does not need access to all administrative functions, but does need access to Design, Preview and Publishing areas of the administrative interface.
Determine if there are security criteria necessary for controlling access. For example, to limit the catalogs that a merchandiser has access to, you could create a security criterion that identifies the specific catalog. This allows the merchandiser to access only the specific catalog.
Create custom roles that contain security criteria created using the API, as well as privileges. For information on working with the API, refer to Implement Access Control for Internal Users.

Understand roles

Everyone who works with the administration interface or Agent Console must have a valid user profile to access the system. There is a single default Administrator profile included with your instance. Only administrators can create and work with user profiles. Note that you do not need to publish user profiles when you create or update them.

Each internal user is assigned a role, or multiple roles, which in turn, contains privileges. Roles can also contain security criteria and access rights. Entities within a role grant or deny access.

You must assign each user one or more roles. A role can contain privileges, security criteria and/or generic access right entities. You cannot assign one of these entities directly to a user, instead you assign a role that contains these entities. Commerce includes a set of predefined roles, each containing a single privilege. You cannot add privileges to, remove privileges from, or delete a predefined role.

Roles can determine whether to display a particular layout or content slot variant to a user. This functionality is primarily used in the Agent Console. For additional information, refer to Work with role-based layouts. Roles can also be used to grant read or write access to a property.

The User Management area of the administration interface, which is available only to users that have the Administrator privilege, allows you to assign roles to users. Note that you cannot create or edit the contents of a role using the administration interface. To do this, you must use the Admin API, which is described in Implement Access Control for Internal Users.

Understand privileges

Privileges grant access to areas of the administration interface or Agent Console. For example, the Catalog privilege provides access to the Catalog area of the administration interface. A user needs at least one privilege to gain access to the administration interface. Note that privileges cannot be edited or deleted. All privileges are predefine; you cannot create a privilege.

Users can have multiple privileges across different roles. The user has all of the privileges conferred by all of their assigned roles. For example, you could assign a user a Dashboard privilege that allows access to the administration interface, as well as the Agent privilege that enables access to the Agent Console. These privileges could be assigned to a user by means of a single role, or two roles.

The following table describes the access provided by the Commerce privileges. Note that these privileges, and the roles that contain them, are separate from the roles that are available for account-based storefront contacts.

Privilege	Access
Administrator	Full access to the administration interface.
CS Agent	Full access to the Agent Console, with the exception of Manual Adjustments. Note: This privilege is available only if the Agent Console is available in your environment.
CS Agent Supervisor	Full access to the Agent Console. Note: This privilege is available only if the Agent Console is available in your environment.
Account Manager	Full access to the Accounts page. Note: This feature may not be enabled in your environment, refer to Configure Business Accounts for information.
Catalog	Full access to the Catalog page (you must also assign the Media role if the user will upload images for products, SKUs, and collections).
Dashboard	Read access to the summary reports on the dashboard. The dashboard is the landing page for the administration interface that users see when they log into Commerce. All of the privileges that control access to the administration interface allow the user to see the dashboard. However only Dashboard or Administrator privilege allows a user to see the summary reports. A user who can see the summary reports on the dashboard requires the Reporting or Administrator role to view the full reports.
Design	Full access to the Design page.
Marketing	Full access to the Marketing page.
Media	Full access to the Media page.
Operations	Full access to the Operations page.
Preview	Access to the Preview button.
Publishing	Full access to the Publishing page.
Reporting	Full access to the Reporting page.
Search	Full access to the Search page.
Settings	Full access to all Settings pages except Access Control, Extensions, Extension Settings, Email Settings and Web APIs (access to those settings is granted by the Administrator privilege).

Refer to Configure Business Accounts for additional information on roles for storefront contacts.

Validate of privileges and roles

The following are validations that the system performs for all privileges and roles based upon the action you perform:

Create/Update Profile - The system validates that the profile has at least one role that contains at least one privilege
Update Profile - The system verifies that you are not removing the Administrator privilege from yourself
Delete Role - The system verifies that the user will still have the Administrator privilege when the role is deleted. Note that predefined roles cannot be deleted.

Understand security criteria

Security criteria restricts a user's ability to update specific catalogs or price groups. For example, a user with the Catalog privilege might also have a security criterion that narrows catalog access allowing the ability to update only CatalogA and no other catalogs. A user's security criteria acts as a filter that narrows the specific data accessible with their assigned privilege. Security criteria restricts update access but does not restrict read-only access.

Using security criteria is optional. You can use them to prevent certain users from updating specific catalogs or price groups. Note that to create, update or delete security criteria, add them to roles or remove them from roles, you must use the API. Refer to Implement Access Control for Internal Users for additional information on working with the APIs.

A given security criterion applies either to catalogs or to price groups. There are three types of security criteria that narrow user access:

Grant: This grants update access to one or more specific catalogs or price groups. For example a user who has a single Grant security criteria for Catalogs A and B can update Catalogs A and B but cannot update any other catalogs.
Deny: This denies access to one or more specific catalogs or price groups. For example, a user who has a single Deny security criteria for Catalogs C and D can update all catalogs except catalogs C and D.
Grant None: This denies update access to all catalogs or price groups. A user with a Grant None security criteria for catalogs cannot update any catalogs.

Price group security criteria applies not only to updating the properties of a price group, but also updating all of the prices within the price group. For example, a security criterion that grants update access to PriceGroup1 allows a user to update the properties of PriceGroup1, as well as all the prices within PriceGroup1. Note that update access to each price group is independent of access to any other price group, even if you are using price group hierarchies. Anyone who has update access to the Catalog privilege, and has update access to at least one price group, can create a price group.

Catalog security criteria applies not only to updating the properties of the catalog, but also updating all of the collections, products and SKUs within the catalog. For example, a security criterion that grants update access to Catalog A also grants access to the collections, products and SKUs within Catalog A. Any user that has the Catalog privilege can create or update a product type. Similarly, any user who has the Catalog privilege, and has update access to at least one catalog, can create a catalog.

When working with catalog hierarchy and shared items, the following rules apply:

If you have access to at least one parent of an item, then you have access to the item. If a product is shared by two catalogs, and you have update access to one parent of the product, then you can update the product.
To link an item to a parent, you need access to both the item and to its destination parent.
To unlink an item from a parent, you need access to that parent.
To delete an item, you need access to all of its parents. If it has no parent, you require access to the item itself.

Note that in this case, parent indicates an immediate parent, which can be a catalog, a collection or a product.

You can create, update or delete an unassigned product or collection if you have the Catalog privilege and access to at least one catalog. You can also link unassigned collections to the catalog.

A product or collection that belongs to both an unassigned collection and an assigned collection of a catalog is subject to the rules stated earlier but without counting the unassigned collection as a parent. For example, if product P belongs to both the unassigned collection C1 and the assigned collection C2, the user must have access to C2 to update product P, even though they have access to unassigned collections.

Access to a legacy secondary catalog and access to its primary catalog are independent of one another. The primary and secondary catalogs are treated the same as any other catalogs, with respect to access control.

Access to an independent catalog automatically gives a user access to all of the filtered catalogs on which the independent catalog is based. It is also possible to give a user access to a filtered catalog, but not to its base independent catalog. The following table shows the access control rules regarding filtered catalogs and their base independent catalogs:

Capability	Available to user with access to base independent catalog?	Available to user with access to filtered catalog but not based independent catalog?
Control if a product in the base independent catalog appears by default in all filtered catalogs.	Yes	No
Determine to which catalogs a product in the base independent catalog is directly linked.	Yes	No
Determine if a product in the base independent catalog appears in the filtered catalog.	Yes	Yes
Determine if a product in the base independent catalog appears in a different filtered catalog.	Yes	No
Update any other product property for any product in the base independent catalog. This does not include the properties listed earlier.	Yes	Yes
Update a property of the filtered catalog.	Yes	Yes
Delete the filtered catalog.	Yes	Yes
Delete a product that is in the base independent catalog.	Yes, if the user has access to all of the immediate parents of the product.	No
Link or unlink a product in the base independent catalog to or from a parent collection.	Yes	No
Create a product in the base independent catalog.	Yes	No
Create any catalog, including creating a filtered catalog in any base independent catalog.	Yes	Yes
Create, update, link, unlink or delete a collection in the base independent catalog.	Yes, although link and delete actions may require access to other parent catalogs of the collection.	No
Create, update or delete SKUs under a product in the base independent catalog.	Yes	No

When working with products and media, the user needs access to a product to perform the following media-related operations:

Add a media item to the product from the Media Library. To upload new media items to the product, the user also needs the Media privilege
Update the product-specific override values of the properties of a media item assigned to the product. For example, Alt Text or Title
Remove the product-specific override values of the properties of a media item assigned to the product. For example, resetting the properties to their default values
Reorder the media items assigned to the product
Specify which media item is the primary one for the product
Remove a media item from the product

Access to a product's prices is controlled separately from access to the product itself. A user with the Catalog privilege can update a product's prices without having access to the product itself, as long as the user has access to the price group in which the prices reside. Access to a product does not provide access to its prices. Only access to a price group allows a user to update prices. The same applies to SKUs and their prices. Note the following:

To create a product, or update a product that was imported without prices, a user must have access to every price group for which the includeAllProducts flag is set.
To delete a product, a user needs access to all price groups containing prices for the product.

Security criteria apply when catalog assets and prices are imported, either using the Import function in the UI, or when a logged-in user performs a bulk import. Bulk imports performed by registered applications are not subject to security criteria. If you use catalog security criteria, it is recommended that you use APIs rather than the UI for any catalog imports. This allows you to receive information about any records that fail to import due to access restrictions.

Combine security criteria

A user can have multiple security criteria within one role, or across different roles. The following examples show the effects of having multiple security criteria:

A user with Grant access to PriceGroup1 and PriceGroup2 can update both PriceGroup1 and PriceGroup2
A user with Grant access to Catalog 1 and Catalog2 can update Catalog2, Catalog2, and catalog assets whose immediate parents belong to Catalog1 or Catalog2
A user with Deny access to PriceGroup1 and PriceGroup2 cannot update PriceGroup1 or PriceGroup2
A user with Deny access to Catalog1 and Catalog2 cannot update Catalog1, Catalog2 or any catalog assets whose immediate parents belong only to Catalog1 or Catalog2

For example, consider the following rules. Note that in each of the following rules, the assets are either catalogs or price groups:

Grant Asset1 + Deny Asset2 = Grant Asset1
Grant Asset1 + Deny Asset1 = Grant None
Grant Asset1 + Deny Asset1 + Grant Asset2 + Deny Asset3 = Grant Asset2 (Grant and Deny Asset1 cancel themselves out.)
Grant None + any other security criteria = Grant None

Understand system-generated roles

If a user with security criteria creates a catalog or price group, the system may generate a role for that user to ensure that he or she has access to the asset just created. The system-generated role contains a security criterion that grants access to the catalog or price group. If the user subsequently creates another catalog or price group, the system adds a security criterion to the role, granting access to the new asset.

System-generated roles are visible in the Advanced section of the user's details in the User Management area of the administration console. System-generated roles function the same as other roles, except that the system may keep adding security criteria.

Generic access rights

The access control described here does not modify existing functionality related to access rights and the property-level access control that you use to meet the requirements of the General Data Protection Regulation (GDPR). However, if you use APIs it is important to note that privileges are a type of access right. Therefore non-privilege access rights are referred to as generic access rights. If a role contains generic access rights, they are visible in the Advanced section of the role's details in the User Management area of the administration console. Refer to Refer to Implement Access Control for Internal Users for more information on using generic access rights to control access to the properties of data items.

Understand when access control takes effect

Changes to the contents of a user's access takes effect as follows:

Changes to a user's security criteria take effect the next time the user logs in. The user's access to specific catalogs or price groups does not change during their current session
Changes to a user's privileges take effect immediately, whenever any aspect of the UI or functionality checks for privileges
Changes to a user's generic access rights take effect immediately, when the user tries to access a property that is subject to access rights