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 is defined for use in all existing and new accounts. This type of role can be assigned to a contact either globally or in the scope of one or more accounts. (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.
- Any standard roles assigned to the contact in global scope.
- Any standard roles assigned to the contact in the current account context.
- Any account roles assigned to the contact that are relative to the current account context.
Access rights
Storefront system contains generic access rights and privileges just like internal access control, but the access rights and privileges and their functionalities are independent of that of internal access rights. Access rights can be used for property level access control (GDPR), custom access control or for specific functionalities provided by Oracle commerce.
For details on how generic access rights are created, the different privileges available and their usage, see Understand access rights in Storefront.
Predefined 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.
Custom roles
Commerce provides the endpoints to create custom shopper roles that will contain access rights. These can be either standard roles or account roles; this is specified when the role is created. You should not use the roles assigned in the scope of a particular account, for property access control. While the REST API does not prevent you from assigning access rights to the account roles, or the built-in Storefront roles (Buyer, Account Address Manager, Administrator, Approver and Profile Address Manager), 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.
Both Admin users and Storefront users have the capability to create and assign roles to users. An Admin user needs the Administrator privilege for creating a role, whereas an account contact needs the Manage Roles privilege for creating a role.
Assigning roles to Storefront users
Admin users with Administrator privilege or Account Manager privilege can assign custom roles or pre-defined roles to Storefront users. Similarly, account administrators can also assign roles to other contacts in their respective accounts.
An Admin user can assign a standard role to a user either globally or in
the scope of one or more accounts. If a role is assigned globally, it applies to all
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. To add or remove
roles from a user, use the addUserRoles and
removeUserRoles APIs respectively.
An account administrator cannot assign standard roles globally. Any
standard roles that the delegated admin assigns to the account contacts will be
associated only for that account. A delegated admin cannot change a contact’s roles
outside the account context they are working in. For example, if a user is the
delegated administrator in 2 different accounts and an account contact exists in
both accounts, the administrator user can only alter the contact’s roles in one
account at a time. To update the roles in the other account, they will have to
switch the context in which they call the Storefront endpoint. To add or remove
roles from an account member, use the addMemberRoles and
removeMemberRoles APIs respectively.
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 totrueto bypass any role or access right security when a contact views the property on their own profile. Default isfalse.shopperWriteable-- Set this totrueto bypass any role or access right security when a contact edits the property on their own profile. Default isfalse.