Understand access control for account-based storefronts

Oracle Commerce includes a storefront access control system for account-based stores that controls which functions specific account contacts can perform on the storefront.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The storefront access control system is similar to the access control system for internal users. The primary difference is that the storefront system applies to contacts accessing account-based storefronts, while the system for internal users mainly applies to the merchant employees accessing the administration interface. Both systems are built around roles, privileges, and generic access rights.

Note, however, that while these entities in the storefront access control system are similar to the equivalent entities in the internal user access control system, they are completely independent of each other. For example, both systems have a predefined Administrator role, but the role in one system has no effect in the other. Similarly, generic access rights created for one system cannot be applied to the other system.

This section describes the storefront access control system. For more information about the access control system for internal users, see Implement Access Control for Internal Users.

Set up storefront access control

To configure storefront access control for an account, a merchant's internal users can assign predefined storefront roles to the account's contacts, and create and assign custom storefront roles. These internal users must have appropriate internal privileges to perform these functions.

Commerce defines two types of storefront roles:

A standard role applies to all of the accounts a contact is associated with. For example, if a standard role is assigned to a contact who is associated with three different accounts, that contact will be able to perform the tasks the role enables for all three of those accounts, as well as for any accounts they are associated with in the future. (Note: In earlier versions of the storefront access control system, standard roles were referred to as global roles.)
An account role applies to a single account only. If a contact is assigned an account role, the role grants access to functions only in the account in which the role is defined.

A contact's access is controlled by the access rights (including privileges and generic access rights) contained in the roles that are in effect for the contact in the current context. These include all of the standard roles assigned to the contact plus any account roles assigned to the contact that are in effect in the current account context.

Predefined and custom roles

The storefront access control system includes five predefined roles, which are summarized in the following table:

Role Name	Description
Administrator	An account administrator (also referred as a delegated administrator) can assign account roles to contacts in their account, and can perform other administrative tasks such as creating contacts, managing the account’s addresses, and editing the account’s approval settings.
Approver	Can view and approve all orders for the account that require approval.
Account Address Manager	Can create, update, and delete the account’s addresses.
Profile Address Manager	Can create, update, and delete their own profile addresses.
Buyer	Can purchase items for the account. All account contacts are automatically assigned this role.

Each account is automatically preconfigured with these same five roles. However, although every account has these roles, they are all actually account roles, not standard roles. This means, for example, that if a contact is assigned the Approver role for one account, the contact does not have that role in other accounts they are associated with unless the role is specifically granted for each account individually.

In addition to these predefined roles, an internal user with the Administrator privilege can create and update custom storefront access rights and roles, and assign them to contacts. A custom role can be either an account role or a standard role; this is specified when the role is created, as shown in Create custom roles and generic access rights. To assign a predefined or custom role to a contact, the administrator uses the updateUserRoles endpoint. For example:

POST /ccadmin/v1/profiles/{id}/updateUserRoles  HTTP/1.1
Authorization: Bearer <access_token>

{ 
  "roles": [
    {
      "op": "add",
      "function": "approver",
      "relativeTo": {
        "id": "200002"
      }
    },
    {
      "op": "remove",
      "function": "admin",
      "relativeTo": {
        "id": "200002"
      }
    },
    {
      "op": "add",
      "repositoryId": "sampleId",
      "type": "role"
    }
  ]
}

The access provided by a custom role is determined by the privileges and generic access rights the role contains. A custom role can include privileges, generic access rights, or both. Privileges and access rights are described below.

Privileges

A privilege confers access to a specific function on the storefront. A privilege cannot be assigned directly to a contact; instead, you must create a custom role that contains the privilege, and then assign the role to the appropriate contacts. Note that you cannot add a privilege to a predefined role.

The storefront access control system includes two privileges that you can add to custom roles:

Manage Roles – A contact assigned a role with this privilege can create and update account roles for an account the role is effective within.
View Account Orders – A contact assigned a role with this privilege can view all orders for an account the role is effective within. (A contact without this privilege can view only their own orders.) This privilege is explained in more detail below.

Generic access rights

You can use generic access rights to limit which contacts can access specific items on the storefront. Generic access rights can be used in property-level access control, to help satisfy the requirements of the General Data Protection Regulation (GDPR) or the California Consumer Privacy Act (CCPA). As with privileges, a generic access right cannot be assigned directly to a contact; instead, it should be added to a custom role which can then be assigned to a contact. Note that you can add generic access rights to a predefined role, but a more flexible and less potentially confusing approach is to leave the predefined roles as is and add generic access rights to custom roles only.

Generic access rights can also be used to control access to functionality on the storefront. For example, suppose an account includes a page of financial data that only certain contacts are permitted to access. Access to this page might be implemented like this:

An internal user with the appropriate privileges creates a storefront access right called View Financial Data.
A contact with the Manage Roles privilege creates a custom account role called Financial Analyst that includes the View Financial Data access right.
A contact with the storefront Administrator role assigns the Financial Analyst role to contacts that are permitted to view financial data.
The storefront includes logic so if a contact attempts to access the financial results data, the page is displayed only if the contact has the Financial Analyst role.

Create custom roles and generic access rights

Commerce provides endpoints for creating custom roles and generic access rights for contacts. These endpoints are separate from the ones for creating the equivalent entities for internal users, but they are called in similar ways. Note that while a contact with the Manage Roles privilege can create custom roles, only an internal user can create generic access rights.

Creating a generic access right for contacts is done using the createAccessRight endpoint in the Admin API. (The equivalent endpoint for creating generic access right for internal users is createAdminAccessRight.) For example, to create a View Financial Data generic access right for contacts:

POST /ccadmin/v1/accessRights  HTTP/1.1
Authorization: Bearer <access_token>

{
  "displayName": "View Financial Data",
  "name": "View Financial Data",
  "repositoryId": "viewFinancialData",
  "description": "Used to control contact access to financial information"
}

To create a custom role for contacts, use the createRole endpoint. (The equivalent endpoint for creating custom roles for internal users is createAdminRole.) You can use createRole to create standard roles and account roles. For example, the following call creates a custom account role and assigns it the View Account Orders privilege and the View Financial Data generic access right:

POST /ccadmin/v1/roles  HTTP/1.1
Authorization: Bearer <access_token>

{
  "name": "Financial Analyst Account Role",
  "repositoryId": "financialAnalyst",
  "description": "Grants contact ability to view account orders and financial information",
  "type": "organizationalRole",
  "relativeTo": { "id": "or-100001" },
  "accessRights": [
    {
      "repositoryId": "viewFinancialData"
    },
    {
      "repositoryId": "ora.viewAccountOrdersPrivilege"
    }
  ]
}

Notice that type is specified as organizationalRole (which means it is an account role) and that relativeTo is used to specify the account the role is effective within.

To create a custom standard role, you use createRole but specify type as role and omit relativeTo. For example:

POST /ccadmin/v1/roles  HTTP/1.1

{
  "name": "Custom Standard Role",
  "repositoryId": "customStandardRole",
  "description": "Custom Standard Role",
  "type": "role",
  "accessRights": [
    {
      "repositoryId": "customAccessRight"
    }
  ]
}

Understand the View Account Orders privilege

By default, contacts can view only their own orders on the storefront. Certain contacts, however, such as managers in an account, may need to monitor or review all orders created in the account. To enable this, you can create a custom role that has the View Account Orders privilege, and assign this role to the contacts who require this access.

A storefront user with the View Account Orders privilege can do the following using the endpoints for orders and scheduled orders in the Store API:

List all orders or scheduled order templates created in the user's current account and site context, regardless of status. (Note, however, that the listScheduledOrdersByProfile endpoint only lists the user's own scheduled orders, regardless of whether they have the View Account Orders privilege.)
View the details of any of these orders or scheduled order templates.
View a return request for any order the user can view.
View the payment groups associated with any order the user can view.

By default, the widgets that list orders include only the contact's own orders, but you can customize these widgets to list all account orders for contacts that have the View Account Orders privilege.

Implement property-level access control on the storefront

The internal access control system can be used to restrict which internal users can view or modify shopper data such as profile properties. Access is enforced through property attributes that can be set to roles or generic access rights that a user must have to access the data.

The storefront access control system also supports property-level access control. For example, a profile property could be configured to grant access only to contacts who have the Profile Address Manager role. Although each system has its own set of endpoints for creating storefront roles and generic access rights, both systems use the same endpoints for setting the values of the property metadata attributes used to control access.

Note that property access control is intended only for properties containing personal identifiable information (PII). Restricting other properties can have unpredictable effects, because internal code may need to access the properties.

Bypass access settings for account contacts

When you restrict access to specific profile properties, you may unintentionally prevent contacts from accessing their own profile data. For example, if you allow only contacts who have a specific generic access right to see phone numbers, then contacts who do not have this generic access right will not be able to see or edit their own phone numbers when they view their profiles.

To avoid this issue, the following attributes can be used to bypass any access restrictions on properties in a contact's own profile:

shopperReadable -- Set this to true to bypass any role or access right security when a contact views the property on their own profile. Default is false.
shopperWriteable -- Set this to true to bypass any role or access right security when a contact edits the property on their own profile. Default is false.