Important

You are browsing the documentation for version 4.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

OroCustomerBundle

OroCustomerBundle enables B2B-customer-related features in Oro applications and provides UI to manage B2B customers, customers groups, customer users, and customer user roles in the back-office and the storefront UI.

The bundle also allows back-office administrators to configure B2B-customer-related settings in the system configuration UI for the entire system, individual organizations, and websites.

Bundle Responsibilities

OroCustomerBundle is responsible for:

  • Customer user CRUD

  • Assigning roles to customer users

  • Activating and deactivating customer users

  • Sending welcome emails

  • Editing password and automatically generating password for a new customer user

Configure Frontend Permissions (ACL)

OroCustomerBundle extends security model of OroSecurityBundle for entities which should be accessible for customer users in the storefront. It adds few new fields to ownership configuration of entities.

The example of the frontend permissions configuration for entity is provided below.

 1 <?php
 2 ....
 3
 4  /**
 5  * @ORM\Entity()
 6  * @Config(
 7  *      defaultValues={
 8  *          "ownership"={
 9  *              "frontend_owner_type"="FRONTEND_USER",
10  *              "frontend_owner_field_name"="customerUser",
11  *              "frontend_owner_column_name"="customer_user_id",
12  *              "frontend_customer_field_name"="customer",
13  *              "frontend_customer_column_name"="customer_id"
14  *          },
15  *          "security"={
16  *              "type"="ACL",
17  *              "group_name"="commerce",
18  *          },
19  *      }
20  * )
21  */
22  class SomeEntity extends ExtendSomeEntity
23  {
24      /**
25       * @var Customer
26       *
27       * @ORM\ManyToOne(targetEntity="Oro\Bundle\CustomerBundle\Entity\Customer")
28       * @ORM\JoinColumn(name="customer_id", referencedColumnName="id", onDelete="SET NULL")
29       */
30      protected $customer;
31
32      /**
33       * @var CustomerUser
34       *
35       * @ORM\ManyToOne(targetEntity="Oro\Bundle\CustomerBundle\Entity\CustomerUser")
36       * @ORM\JoinColumn(name="customer_user_id", referencedColumnName="id", nullable=true, onDelete="SET NULL")
37       */
38      protected $customerUser;
39  ...
40  }

Configure Anonymous Customer User

Anonymous customer user functionality consists of the sections below.

AnonymousCustomerUserToken

Oro\Bundle\CustomerBundle\Security\Token\AnonymousCustomerUserToken is the token class that is extended from AnonymousToken. It is tied with the CustomerVisitor entity class which persisted anonymous customer user data for later use. Besides it, the token stores the info taken from the visitor_id and session_id cookies. When the token is initialized for the first time, it is filled with the Anonymous Customer User string to provide compatibility with Symfony security system.

1 $token = new AnonymousCustomerUserToken(
2     'Anonymous Customer User',
3     [$currentWebsite->getGuestRole()->getRole()]
4 );

The AnonymousCustomerUserToken is created in the authenticate method of AnonymousCustomerUserAuthenticationProvider.

CustomerVisitor Entity

The Oro\Bundle\CustomerBundle\Entity\CustomerVisitor class has the following properties:

  • id

  • lastVisit - tracks guest last visit datetime

  • sessionId - a unique identifier

  • customerUser - one-to-one relation to CustomerUser entity. Used to retrieve the customer info from the token. For such cases, the Guest Customer User term is used, because it is not a “true” user.

The session id property is generated through Doctrine PrePersist Lifecycle Event:

1 $this->sessionId = bin2hex(random_bytes(10));

Listener

The Oro\Bundle\CustomerBundle\Security\Firewall\AnonymousCustomerUserAuthenticationListener class listens requests on the firewall and calls Oro\Bundle\CustomerBundle\Security\AnonymousCustomerUserAuthenticationProvider using the handle method.

The listener checks the token, and if it is the instance of AnonymousCustomerUserToken, sets a visitor Id and a session Id taken from the customer_visitor cookie to the token. If the authentication of AnonymousCustomerUserToken object is successful, you need to update cookie using the lifetime parameter, oro_customer.customer_visitor_cookie_lifetime_days. By default, this param is 30 days, and it is accessible through the System > Configuration > Commerce > Customer > Customer User section on the global and organization levels:

 1 const COOKIE_ATTR_NAME = '_security_customer_visitor_cookie';
 2 const COOKIE_NAME = 'customer_visitor';
 3
 4 $cookieLifetime = $this->configManager->get('oro_customer.customer_visitor_cookie_lifetime_days');
 5
 6 $cookieLifetime = $cookieLifetime * Configuration::SECONDS_IN_DAY;
 7
 8 $request->attributes->set(
 9     self::COOKIE_ATTR_NAME,
10     new Cookie(
11         self::COOKIE_NAME,
12         base64_encode(json_encode([$visitor->getId(), $visitor->getSessionId()])),
13         time() + $cookieLifetime
14     )
15 );

The Oro\Bundle\CustomerBundle\Security\Listener\CustomerVisitorCookieResponseListener listens kernel.response events. If the request has an _security_customer_visitor_cookie attribute, it sets a cookie to it.

Authentication Provider

The authenticate method of the Oro\Bundle\CustomerBundle\Security\AnonymousCustomerUserAuthenticationProvider class verifies AnonymousCustomerUserToken. The Oro\Bundle\CustomerBundle\Entity\CustomerVisitorManager class finds the CustomerVisitor entity using the visitor_id and session_id key fields and creates or updates the CustomerVisitor entity if it was created earlier. As a result, the AnonymousCustomerUserToken object is created and is populated with user, roles, and organization data, and holds the CustomerVisitor object.

AnonymousCustomerUserFactory

The Oro\Bundle\CustomerBundle\DependencyInjection\Security\AnonymousCustomerUserFactory class ties listener and provider. Also, it defines the update_latency configuration option. It helps prevent sending too many requests to the database when updating the lastVisit datetime of the AnonymousCustomerUser entity. Its default value is set in the DI container and is expressed in seconds:

1oro_customer.anonymous_customer_user.update_latency: 600 # 10 minutes in seconds

Firewall Configuration

To activate anonymous customer user functionality for some routes or apply it to the existing ones, define it in the security section with the anonymous_customer_user: true property:

1security:
2    firewalls:
3        frontend:
4            anonymous_customer_user: true

In this example, we enable guest functionality for the application storefront.

Guest Customer User

Guest Customer User is a customer user with the following DB properties:

  • confirmed = false

  • enabled = false

  • is_guest = true

The Oro\Bundle\CustomerBundle\Entity\GuestCustomerUserManager class has a logic of creation Guest Customer User.

It is used for creating some business products under Anonymous Customer, like RFQ or Order, in the storefront. For example, when creating one of the mentioned products, we can tie it with Guest Customer info taken from AnonymousCustomerUserToken token:

 1// $request is a some Request object
 2$token = $this->tokenAccessor->getToken();
 3
 4if ($token instanceof AnonymousCustomerUserToken) {
 5    $visitor = $token->getVisitor();
 6    $user = $visitor->getCustomerUser();
 7    if ($user === null) {
 8        $user = $this->guestCustomerUserManager
 9            ->generateGuestCustomerUser(
10                [
11                    'email' => $request->getEmail(),
12                    'first_name' => $request->getFirstName(),
13                    'last_name' => $request->getLastName(),
14                    ...
15                ]
16            );
17        $visitor->setCustomerUser($user);
18    }
19    $request->setCustomerUser($user);
20}

Ownership

When using guest functionality for some business products, you should specify their owner. With Oro\Bundle\CustomerBundle\Entity\CustomerVisitorOwnerAwareInterface and Oro\Bundle\CustomerBundle\Owner\AnonymousOwnershipDecisionMaker, you can do it using the following conditions:

  • entity should implement CustomerVisitorOwnerAwareInterface

  • token should be instance of AnonymousCustomerUserToken

  • entity should contain CustomerVisitor and it should equal the current visitor in the session

Configure Guest Access and Permissions

When we implement guest functionality for some product, it should be tied with the related feature and added to system configuration on the global, organization, and website level). By default, it should be disabled:

1//.../DependencyInjection/Configuration.php
2'guest_product_toggle' => ['type' => 'boolean','value' => false],
3'guest_product_owner' => ['type' => 'string', 'value' => null]

 1#...Resources/config/oro/system_configuration.yml
 2system_configuration:
 3    groups:
 4        guest_product_section:
 5            title: some.title
 6        guest_product_owner_section:
 7            title: some.title
 8    fields:
 9        guest_product:
10            data_type: boolean
11            type: Oro\Bundle\ConfigBundle\Form\Type\ConfigCheckbox
12            options:
13                label: some.title
14                tooltip: some.tooltip
15        guest_product_owner:
16            ui_only: true
17            data_type: string
18            type: Oro\Bundle\UserBundle\Form\Type\UserSelectType
19            options:
20                label: some.title
21                tooltip: some.tooltip
22                required: true
23    tree:
24        system_configuration:
25            commerce:
26                children:
27                    sales:
28                        children:
29                            guest_product_section:
30                                children:
31                                    - guest_product
32                            guest_product_owner_section:
33                                children:
34                                    - guest_product_owner

1#...Resources/config/oro/features.yml
2features:
3    guest_product_feature:
4        label: some.label
5        description: some.description
6        toggle: guest_product_toggle

Next, we should activate feature toggle voter in the DI configuration:

 1oro_bundle.voter.guest_product:
 2    parent: oro_customer.voter.anonymous_customer_user
 3    calls:
 4        - [ setFeatureName, ['guest_product_feature'] ]
 5    tags:
 6        - { name: oro_featuretoggle.voter }
 7
 8oro_bundle.voter.guest_customer_user:
 9    parent: oro_customer.voter.customer_user
10    calls:
11        - [ setFeatureName, ['guest_product_feature'] ]
12    tags:
13        - { name: oro_featuretoggle.voter }

Sometimes, it is necessary to open some business entity or action for guests using ACL configuration.

So, to enable certain entities and actions for the Anonymous Customer User role by default, use the following code example:

1#.../Migrations/Data/ORM/data/frontend_roles.yml
2ANONYMOUS:
3    permissions:
4        entity|Oro\Bundle\SomeBundle\Entity\Some: [VIEW_BASIC, CREATE_BASIC, EDIT_BASIC, DELETE_BASIC]
5        action|some_action: [EXECUTE]

Once the application is installed, the predefined Non-Authenticated Visitors role will have the mentioned permissions/capabilities enabled.