Implement access control in business accounts

For stores with business accounts, there are two types of users who can have their access to properties controlled with roles and access rights:

• Internal users who can work with the administration interface’s Accounts page because they were assigned the Administrator or Account Manager role.
• Storefront users who have been assigned the Administrator role (delegated administrators) or the Approver role. These roles allow them to manage certain aspects of their business accounts. Delegated administrators do not have access to the Commerce administration UI. Delegated administrators perform all account-management tasks on their My Account pages, which are available once they log into your store.

With the support of role-based access control, you can also use these roles and access rights to enforce restrictions on which internal users can access a shopper’s personal data. More specifically, you can control which properties an internal user can see or edit. For example, if you set the writeRole attribute of a property to Administrator, only someone with the Administrator role can set the value of a specific property.

Delegated administrators can also have their access to properties controlled with roles and access rights. For more information on delegated administrators, refer to Understand delegated administration. For specific details on how a delegated administrator can have their access to properties controlled with roles and access rights, refer to the Create access rights for use with shopper roles section of this document.

Understand how access rights and roles affect the Accounts page

Internal users with a role of Administrator or Account Manager have access to properties found on the Accounts page in the Oracle Commerce Cloud administration UI. With support of role-based access control, you can limit what a user is able to see or modify on the Accounts page based on role and access rights. This can be particularly useful when trying to limit access to information in the following areas:

• Contacts list
• Contact details
• Account details - This includes the following tabs: General, Addresses, Contacts, Contracts, Approvals, Shipping/Payments, and Registration Requests (if the feature has been enabled). The use of role-based access control could be particularly useful on tabs that display personal information such as the Addresses and Contacts tabs.

By focusing on tabs that include sensitive and personal information, you can take advantage of this feature to effectively control what a user is able to see or modify on the Accounts page.

The following image shows an example of what an internal user might see on the Accounts page of the administration interface if role-based access control is implemented for an account-based store. Specifically, an access right has been assigned to both the readAccessRight and writeAccessRight attributes of the user shopper type’s email property. In this case the user is not assigned a role that includes the same access right – as a result the email address of each contact appears as the placeholder value XXXXX. See the Configure the data to return section of this document for more information.

Other things you should pay attention to when you are considering using role-based access control to control access to properties on the Accounts page include the following:

• If you make account name, contact name, or contact email a restricted property, you should specify a non-null masking value. Otherwise, business users who view the list of contacts or accounts, but don’t have access to these fields, may see null values, and therefore may not be able to open the details of a contact or account.
• If a user tries to view a list, and the default sort is on one or more fields to which they do not have read access, the list returns unsorted results. To the requesting user, all instances of the field (in all rows) will have the same masked value. You can sort by clicking the headings in the tables that appear on the following Accounts pages: Contacts List, Accounts List, and Registration Requests List as well as on the All Sites and Contacts tabs for an account’s details page, which you see when you click on that specific account in the Accounts List.
• If a user tries to search on a field to which they do not have read access, no results will be returned. This refers to any search boxes (the ones that have Filter as the label in them) on the Accounts pages (for example, accounts, contacts, registration requests, and sites).
• If a user tries to do an Advanced search and any of the fields they search on is one to which they do not have access, no results will be returned. Advanced search is available on the Contacts List, Accounts List, and the Registration Requests List pages.

Plan access control for an account-based store

This section describes things to keep in mind as you implement property access features for an account-based store.

• Each of a property’s access-control attributes (readRole, writeRole, readAccessRight, and writeAccessRight) can be set only to a single ID. If you plan to use access rights to control property access for both internal users and delegated administrators, make sure that corresponding access rights and custom roles you create for internal users and shoppers have the same repositoryId value.

  For example, suppose you use the createAdminAccessRight endpoint to create an access right whose ID is ar10. You then assign the access right to a property’s readAccessRight attribute. Any internal user whose role includes the access right ar10 will have read access to that property. If you want delegated administrators to also have read access to that property, you must use the createAccessRight endpoint to create an access right with the exact same ID, ar10. Then, any delegated administrator whose role includes the access right ar10 will also have read access to the property.

• If you set access-control attributes on a property, think about whether you want to set the property’s shopperReadable and shopperWriteable attributes to true. If these attributes are false, shoppers (including delegated administrators) who do not have the appropriate access right assigned to them via a role, will not be able to access the properties for their own accounts and orders. For more information about these attributes, see Understand roles and access rights.
• Depending on how you implement property restrictions, you may want to customize the storefront widgets you have configured for layouts that your delegated administrators access. (For example, the Order Approval Settings, Account Contacts, and Account Addresses widgets.) You could add logic that provides better user experience for delegated administrators. For example, if a delegated administrator does not have write access to a property, the widget could include logic that prevents them from saving the property, rather than waiting to get an error from the server.
• Commerce provides one set of endpoints for creating access rights and roles for shoppers and another for creating them for internal users. However, there is only one set of endpoints for assigning access rights to properties. If you plan to control property access for both internal users and delegated administrators, make sure that corresponding access rights you create with createAdminAccessRight (for internal users) and createAccessRight (for delegated administrators) have the same repositoryId value. This helps ensure consistency when you implement property access control for both types of users.

  For more information about assigning access rights to properties, see Set access control on properties.

• If your account-based store is configured to allow shoppers to submit account registration requests, do not restrict a shopper’s write access to any properties of the organizationRequest item type, as this will cause any registration request the shopper submits to fail.

Create access rights for use with shopper roles

You create access rights to control delegated administrators’ access to properties using the createAccessRight endpoint in the Admin API.

The following example creates an access right that can be used with shopper roles:

POST /ccadmin/v1/accessRights  HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
    "displayName": "Shopper Email Access Right 1",
    "name": "shopperEmailAr1",
    "repositoryId": "shopperEmailAr1",
    "description": "First of several storefront access rights."
}

The response is similar to this:

{
  "displayName": "Shopper Email Access Right 1",
  "name": "shopperEmailAr1",
  "repositoryId": "shopperEmailAr1",
  "description": "First of several storefront access rights.",
  "links": [
    {
      "rel": "self",
      "href": "http://www.example.com:7002/ccadmin/v1/accessRights"
    }
  ]
}

Create custom shopper roles

Commerce provides the ability to create custom shopper roles that will contain shopper access rights. Custom roles are global roles, which can be assigned to delegated administrators in any account. You should not use the built-in Storefront Roles (Buyer, Account Address Manager, Administrator, Approver, and Profile Address Manager), for property access control. While the REST API does not prevent you from assigning access rights to the built-in Storefront Roles, these roles are account-specific and using them to control access to individual properties may not produce the results you expected when you planned your access-control strategy.

Note: Custom shopper roles do not appear in the administration interface, so you must assign them to shopper profiles with the createProfile, updateProfile, or updateUserRoles endpoints in the Admin API.

To create a custom shopper role, use the createRole endpoint in the Admin API. The following example creates a custom role and assigns an existing access right to it in the same request. You can also create a custom role with no access rights and assign them to the role later with the updateRole endpoint, or just use the role (without access rights) to control property access.

POST /ccadmin/v1/roles  HTTP/1.1
Authorization: Bearer <access_token>
x-ccasset-language: en

{
  "name": "No Email Access",
  "repositoryId": "noEmail",
  "description": "Delegated admin who cannot access shopper email addresses.",
  "accessRights": [
    {
      "repositoryId": "shopperEmailAr1"
    }
  ]
}

The response is similar to this:

{
    "name": "No Email Access",
    "repositoryId": "noEmail",
    "description": "Delegated admin who cannot access shopper email addresses.",
    "links": [
        {
            "rel": "self",
            "href": "http://www.example.com:7002/ccadmin/v1/roles"
        }
    ],
    "accessRights": [
        {
            "repositoryId": "shopperEmailAr1",
        }
    ],
    "category": "Custom"
}

The following example assigns two existing access rights to an existing custom role:

PUT /ccadmin/v1/roles/noPhone  HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "accessRights": [
    {
      "repositoryId": "bbar1",
      "repositoryId": "bbar2"
    }
  ]
}

The response is similar to this:

{
    "name": "No Phone Number Access",
    "repositoryId": "noPhone",
    "description": "Delegated admin who cannot access shopper phone numbers.",
    "links": [
        {
            "rel": "self",
            "href": "http://www.example.com:7002/ccadmin/v1/roles"
        }
    ],
    "accessRights": [
        {
            "repositoryId": "bbar1",
            "repositoryId": "bbar2",
        }
    ],
    "category": "Custom"
}