Skip to main content

Auth0 Roles Management

Context​

Before Auth0, Hybris saved all the groups that determine the roles of customers in the ecommerce. With the moving to a composable architecture and the arrival of Auth0, it's time to move the responsibility of managing roles/groups from Hybris to Auth0.

This documentation describes the different scenarios and tasks to achieve the migration, and management of the change of user roles, and integration between Auth0 and the different systems (Hybris, Dixa).

Initial Importation of Roles​

First task to do is to review the initial list of roles created in the Auth0 tenants, and adapt them to the identifiers in the initial list of groups that was defined here

It's necessary to review the roles definition in Terraform and define it correctly.

Currently Hybris groups have an customised attribute called authRole mapping, that saves a reference to the corresponding Auth0 roles (not all the hybris groups need to have this attribute populated). DIXA and Auth0 API works with Role Ids so it's necessary to modify the current mapping in production and UAT to populate it with the Role Id, also in order to prevent unnecesary calls to the Auth0 API for searching and mapping the group based in other attribute (an Auth0 role has 3 attributes: id, name and description). This unnecessary logic should be added in several points in Hybris (Hybris get customer groups endpoint and future customer groups notification generation).

Integration Scenarios​

This section cover the different scenarios that we need to accomplish and review.

Hybris Groups to Auth Roles Migration​

Currently the Hybris & Mobile integration with Auth0 is already in production. New customers register in Auth0 and then they are created in Hybris; at the same time that old users migrate their authentication from Hybris to Auth0. In this scenario, it is necessary to assign the corresponding roles to the users. These roles will be those hybris groups that the user has assigned and whose Auth0 Role property is populated.

The proposed solution here is to migrate the Hybris groups to Auth0 roles in a new action during the login flow execution, so the steps of the new action will be:

1- Check if the role migration process has been executed before; to do this we should save a flag in the customer Auth0 metadata, the first time the process is correctly executed for the customer.

2- If the process has not been executed we should retrieve from Hybris the groups for the customer invoking the corresponding Hybris endpoint.

https://[www|uat].rapha.cc/rapha/users/:userId/customergroups?fields=DEFAULT

Response example:

{
    "userGroups": [
        {
            "name": "RCC",
            "uid": "RCC",
            "auth0Role": "RCC"
        },
        {
            "uid": "customergroup",
            "auth0Role": "CustomerGroup"
        }
    ]
}

The groups to taking into account will be the ones with the auth0Role attribute populated, not all the groups returned by the endpoint has this attribute populated.

NOTE: Current value for auth0Role must be changed to save the Auth Id and prevent of unnecessary Auth0 API calls

3- Once the groups are retrieved, the ones that match auth0 roles must be identified and assigned to the customer. Here is an example of how to implement this using auth0 libraries.

4- If there have been no errors, a flag must be saved in the user metadata, so the process will not be executed anymore.

Role/Groups Change Management​

Once the customer Hybris groups are migrated to Auth0 roles, it's necessary to manage the changes that can be done after it, and reflect the changes in Auth0 and all the systems related (Hybris, DIXA).

Changes in Hybris​

User group assignment changes in hybris can occur in the following scenarios:

  • A HMC/Backoffice user changes the customer group assignation manually.
  • Hybris changes the customer group assignation programatically, for example, when a customer buys the RCC subscription, Hybris automatically assings the corresponding RCC groups to the customer.

For the above scenarios, Hybris must generate notifications that must be sent to the MW to trigger the corresponding actions.

Proposed solution

Currently RaphaSaveCustomerInterceptor is triggered in Hybris to generate several types of validations and notifications; it will be necessary to define and include new notifications to be triggered when a group is added or removed from a customer. These notifications can be sent to auth0 api gateway roles endpoint that will deal with this changes, that will trigger the update roles lambda as it's described here. This lambda was originally thought to process notifications/changes sent from DIXA, it's necessary to adapt it to process Hybris notifications.

Example of body request tha will be accepted by the lambda and the corresponding API Gateway Endpoint:

{
  "userId": "auth0UserIdExample",
  "email": "example@test.com",
  "source": "hybris"
  "roles": [
    "RoleId1Example",
    "RoleId2Example",
    "RoleId3Example"
  ]
}
  • userId: unique Id of the user in Auth0. It's needed to update the customer data in Auth0 via Auth0 API. Not populated if Hybris sends the notification (currently Hybris does not have this info).
  • email: email that allows to retrive the data of the customer in Auth0 (including the Auth0 userId).
  • source: source application that has triggered the event: hybris or dixa at the moment.
  • roles: list of the Auth0 Role Ids that are the roles that must be the only ones assigned to the customer, so, the ones that are in the list must be assigned and the ones that are not in the list must be deleted from the customer.

Depending on the source attribute, we will need to implement different actions. For the Hybris scenario, it's enough with update the roles in Auth0, then, that roles will be retrieved by Dixa using the /user endpoint in the Auth0 API Gateway as it's described here.

For Hybris events, the userId attribute it's not gonna be populated, because Hybris does not save or has access to that value, so the email will be populated instead of it, for example:

{
  "email": "example@test.com",
  "source": "hybris"
  "roles": [
    "RoleId1Example",
    "RoleId2Example",
    "RoleId3Example"
  ]
}

As is documented here, a DIXA user will be able to modify roles assignation in Auth0, to do that a notification will be sent to auth0 api gateway roles endpoint that will deal with this changes, that will trigger the update roles lambda

Now, the changes in DIXA not only have to be reflected in Auth0, they must be reflected also in Hybris, so It will be necessary to implement changes in the current MW architecture.

NOTE: The Auth0 API Gateway endpoints are gonna be secured, it will be necessary to refactor the Hybris implementation that sends the notifications to take this into account, currently the notifications sent by Hybris have not any securitisation, and now, it must be securised in the same way than another 3rd Party access

Modify DIXA event body​

Currently that notification sent to Auth0 API Gateway looks like the below example:

{
  "userId": "auth0UserIdExample",
  "roles": [
    "RoleId1Example",
    "RoleId2Example",
    "RoleId3Example"
  ]
}

Now, It's necessary to populate more info to pass to the Auth0 API Gateway to trigger the new logic, we need to change this approach to send a notification like the below one:

{
  "userId": "auth0UserIdExample",
  "email": "example@test.com",
  "source": "dixa"
  "roles": [
    "RoleId1Example",
    "RoleId2Example",
    "RoleId3Example"
  ]
}

Create a new Hybris endpoint to update customer groups​

Currently there is no endpoint in Hybris to assign/unassign user groups so it will be necessary to implement a new one that:

  • Given a user email and a list or Auth0 Roles ids.
  • Then searchs and matches the user groups that correspond to the Auth0 Roles and assign them to the customer.
  • And, unassigns the Auth0 User groups that the customer has and are not included in the list of roles received.

Body request example:

{
  "roles": [
    "RoleId1Example",
    "RoleId2Example",
    "RoleId3Example"
  ]
}

The email will be pass as part of the path as in the rest of Hybris Customer controller endpoints.

Create a Hybris Update User Groups Lambda & Step function to orchestrate calls​

Due to the low performance of the Hybris endpoints the call to the new endpoint it is gonna be separated from the Auth0 ones and wrapped in a new lambda that will make the corresponding modifications.

In this case, the proposed implementation will be that both lambdas (Auth0 Update User Roles and Hybris Update User Groups) will be executed using a step function that will receive the same request input:

  • 1st Step: Auth0 Update User Roles lambda is executed, roles are updated and if there is no error, it jumps to the 2nd step.
  • 2nd Step: if source is dixa, then the Hybris Update User Groups Lambda is executed, passing the new roles and the email to Hybris.

Update Roles and Groups Step Function

Role/Groups sharing​

That roles and user info can be retrieved by any application using the /user endpoint in the Auth0 API Gateway as it's described here.

This endpoint must be securised.

Adding New Roles​

Analysis​

  • Currently, most of the business logic is still in Hybris Monolith: backoffice apps, promotions, vouchers, rcc, smartedit, etc. and the corresponding Hybris user groups needed to execute this logic. Most of these groups are ad-hoc or dependant on hybris logic and way of working.

  • Currently we have 43k Hybris User groups in Hybris, not all are needed in auth0 and 3rd party applications. So it's not necessary that every time that a Hybris backoffice employee adds a group, this is automatically created in auth0, and the corresponding piece of work (assuming that Hybris is gonna be switched off). Currently there is no criteria to separate these types of groups.

  • In the near future Hybris ecommerce logic (and the roles/groups required) is gonna split in several 3rd party systems (dixa, commerce layer, contenful, future promotions engine, etc.), maybe these 3rd party systems require their own roles, currently we don’t now if they are gonna be shared saving them in auth0 or only in their own systems; it's necessary to define this criteria per 3rd party application, in the same way that defining how these roles are assigned and notified to auth0 or between future applications if it's required.

  • Currently we are gonna import an initial list of roles that it's known that some of them are gonna be needed for sure (RCC groups, ambassadors, etc). Once the new logic described in this document is deployed any modification of members for these groups must be updated in auth0 assigning the corresponding roles to the corresponding users.

  • Any user group can be created in Hybris, but to be recognised it will be necessary to populate the attribute auth0Role with the corresponding auth0 role id so, Digital & Merch teams should inform backend team to create the corresopnding groups in auth0, and then, after assigning the mapping (role ID) to the hybris group, they must assign the users in Hybris.

  • If Hybris backoffice employees assign the users before creating the role in auth0 and mapping it, the users should be unassigned and assigned again in Hybris to trigger the new logic of notifications from hybris to auth0, but, for example, the creation and assignation of customers to groups like AMBASSADORS, are currently requested to Hybris backend team. Ideally the Back End Team should be informed of this while Hybris exists if it's necessary that a group exists in auth0.

Decision & Summary​

  • No process where new Hybris groups get created in auth0 will be built.

  • Only if the group is genuinely needed to be in auth0 (ie 3rd party systems need the groups) will we manually create the role in Auth0 and hybris to ensure they are mapped correctly.

  • The checkout project (and in the future the rest of 3rd party integrations) will need to review roles logic in commercelayer and if they need any additional roles that are not currently in Auth0.

  • Eventually, a different method to create roles post-hybris will be needed (Dixa? Auth0?). Something to review closer to the time.

  • The procedure to add new roles in auth0 and map them in Hybris is defined here.