Use and modify roles for internal users
You can use predefined roles and create custom roles. You can also modify roles by adding security criteria and generic access rights.
This section applies to Open Storefront Framework (OSF) and Storefront Classic.
This section describes the predefined roles included with Commerce and how to create and modify custom roles. For information about assigning roles to internal users, see Understand Role-based Access Control.
Use predefined roles
Commerce includes a number of predefined roles. Each predefined role contains a privilege of the same name that provides access to a certain area of the administration interface. For example, the Design role contains the Design privilege, which gives access to the Design page in the administration interface to users assigned the role. You cannot remove the privilege from a predefined role or add a different one to it. If you want a role to contain multiple privileges, you must create a custom role, as described below.
Note that you can add security criteria and generic access rights to a predefined role, but a more flexible approach is to leave the predefined roles as is and add security criteria and generic access rights to custom roles only.
The following table describes the predefined roles and their corresponding privileges. Note that each role and privilege has an ID which is used to identify it in API calls.
Role and Privilege Name | Role ID | Privilege ID | Description |
---|---|---|---|
Administrator | adminRole | ora.adminPrivilege | Full access to the Commerce administration interface. |
CS Agent | csAgentRole | ora.csAgentPrivilege | Full access to the Agent Console except Manual Adjustments. (Available only if your subscription includes the Agent Console.) |
CS Agent Supervisor | csAgentSupervisorRole | ora.csAgentSupervisorPrivilege | Full access to the Agent Console. (Available only if your subscription includes the Agent Console.) |
Account Manager | accountManagerRole | ora.accountManagerPrivilege | Full access to the Accounts page. (This feature may not be enabled in your environment.) |
Catalog | catalogRole | ora.catalogPrivilege |
Full access to the Catalog page. You must also assign the Media privilege if the user will upload images for products, SKUs, and collections. |
Dashboard | dashboardRole | ora.dashboardPrivilege |
Read access to the dashboard, which is the landing page for the administration interface that users see when they log into Commerce. All privileges that control access to the administration interface allow the user to see the dashboard, but only the Dashboard or Administrator privilege allows a user to see the summary reports there. A user who can see the summary reports on the dashboard needs the Reporting or Administrator privilege to click through to view the full reports. |
Design | designRole | ora.designPrivilege | Full access to the Design page. |
Marketing | marketingRole | ora.marketingPrivilege | Full access to the Marketing page. |
Media | mediaRole | ora.mediaPrivilege | Full access to the Media page. |
Operations | operationsRole | ora.operationsPrivilege | Full access to the Service Operations page. |
Preview | previewRole | ora.previewPrivilege | Access to the Preview button. |
Publishing | publishingRole | ora.publishingPrivilege | Full access to the Publishing page. |
Reporting | reportingRole | ora.reportingPrivilege | Full access to the Reports page. |
Search | searchRole | ora.searchPrivilege | Full access to the Search page |
Settings | settingsRole | ora.settingsPrivilege | 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.) |
Create custom roles
In addition to providing the predefined roles described above, Commerce provides support for creating custom roles. Unlike predefined roles, you can delete custom roles, and you can add privileges to and remove privileges from them.
To create a custom role, use the createAdminRole
endpoint in the Admin API, as shown in the following example. As this example shows,
when you create a role, you can assign privileges, security criteria, and access
rights in the same call. Alternatively, you can create the role and later assign
these entities, as described in Modify roles.
POST /ccadmin/v1/adminRoles HTTP/1.1
Authorization: Bearer <access_token>
x-ccasset-language: en
{
"repositoryId": "HomeGoodsMerchandiser",
"securityCriteria": [
{
"id": "securityCriterionHomeGoodsCatalog"
},
{
"id": "securityCriterionHomeGoodsPriceGroup"
}
],
"accessRights": [
{
"repositoryId": "ora.catalogPrivilege"
},
{
"repositoryId": "ar1"
}
],
"name": "Home Goods Merchandiser"
}
The response is similar to this:
{
"securityCriteria": [
{
"name": "Security Criterion for HomeGoodsPriceGroup",
"description": "Grants access to HomeGoodsPriceGroup",
"id": "securityCriterionHomeGoodsPriceGroup"
},
{
"name": "Security Criterion for HomeGoodsCatalog",
"description": "Grants access to catalog assets of the HomeGoodsCatalog",
"id": "securityCriterionHomeGoodsCatalog"
}
],
"name": "Home Goods Merchandiser",
"repositoryId": "HomeGoodsMerchandiser",
"description": null,
"links": [
{
"rel": "self",
"href": "http://www.example.com:7002/ccadmin/v1/adminRoles"
}
],
"accessRights": [
{
"displayName": "Access Right 1",
"name": "ar1",
"repositoryId": "ar1",
"description": "First of several access rights.",
"id": "ar1",
"type": "generic"
},
{
"displayName": "Catalog",
"name": "Catalog",
"repositoryId": "ora.catalogPrivilege",
"description": "Catalog Privilege",
"id": "ora.catalogPrivilege",
"type": "privilege"
}
],
"securityCriteriaLastModified": "2021-03-08T21:12:30.047Z",
"id": "HomeGoodsMerchandiser",
"category": "Custom"
}
Modify roles
You can use the updateAdminRole
endpoint in the Admin API to modify
predefined roles or custom roles by adding or removing security criteria and generic
access rights. For custom roles, you can also use this endpoint to add and remove
privileges.
Note that when you call this endpoint, the body of the request can
include the securityCriteria
property, the
accessRights
property, or both. If you include one of these
properties in the call, the entities specified in the property replace the ones
currently assigned to the role. So, for example, if you include the
securityCriteria
property to add a security criterion to a
role, the value of the property should include all of the security criteria that are
currently assigned to the role, in addition to the security criterion you want to
add; if you specify only the new criterion, the existing criteria will be removed
from the role. Similarly, if you include the accessRights
property
to add a privilege or a generic access right, the value of the property should
include the privileges and generic access rights that are currently assigned to the
role. If you add a generic access right to a predefined role, be sure to include the
role's privilege in the accessRights
property, or the request will
be rejected.