Auth0 Exponea integration for emails
Context
There are a number of cases where we want to send emails to customers, and we want to do this via Exponea as this is the provider that we use to send all of our other emails at Rapha. This document describes how we will use AWS middleware and Auth0 events to trigger emails to be sent via Exponea. This builds on top of the event driven architecture described in the Auth0 Event Logs documentation, but we are documenting the email specific part of that architecture here for clarity.
Decision
The section of the architecture inside the red line above is the emails integration. Below is a closer look at this architecture:
The events that trigger an email:
- Brute force (limit_wc) - This is when an IP address is blocked because it reached the maximum failed login attempts into a single account. We will send an email notifying the customer that their account has been blocked, and how they can unblock it.
- Brute force (limit_sul) - This is when a user is temporarily prevented from logging in because they reached the maximum logins per time period from the same IP address. We will send an email notifying the customer that their account has been blocked, and how they can unblock it.
- Brute force (limit_mu) - This is when an IP address is blocked because it attempted too many failed logins without a successful login. Or an IP address is blocked because it attempted too many sign-ups, whether successful or failed. We will send an email notifying the customer that their account has been blocked, and how they can unblock it.
- Change Password - After a user successfully changes their password, we want to send them an email confirmation. As well as being useful information for the customer, this has a security benefit. If it was not the customer that changed their passwrod, they can alert us.
- Change Email - After a user successfully changes their email address, we want to send two email confirmations - one to the old email address, and one to the new email address. As well as being useful information for the customer, this has a security benefit. If it was not the customer that changed their email address, they can alert us.
- When any of the above events are sent to the Auth0 event bus, we have an event rule that catches these events and sends them to the Email Transform Event Lambda (i.e. the Lambda is the target for that rule). Here, we transform the event data into the required format to send a SendEmail event to the Email Event Bus. This event triggers the Send email lambda, which uses the Exponea Transactional Email API to send the relevant email.
- Fail Change Password Request - This email is not sent by Bloomreach, but is worth mentioning here. We have the following scenario:
- A customer that has an account with us wants to change their password. They have not yet logged in via Auth0, and therefore have not been migrated. They access the Auth0 login page, and use the "forgot password" link to try and send a forgot password email. At this point, they do not exist in Auth0 yet and so the change password request fails. We catch this event and execute the Hybris Reset Password Lambda, which checks if the user exists in Hybris and if they do sends them an email via Hybris.
Consequences and limitations
Ideally we wanted to send all emails via Exponea, to maintain consistency and avoid any point to point integrations. However, since we are using the Auth0 Universal Login we have limited control over the login and register pages. We cannot control the behaviour of the "forgot password" link on the login page, which means that when a user clicks that link the email must be sent from Auth0 (rather than us being able to replace the link to send a request to an AWS API Gateway for example). In order to send that email we have setup an integration with Mailgun as our email provider in Auth0. All other emails will be sent via the architecture mentioned above.
Post go-live, we noticed an edge case where customers that had not yet migrated entered their credentials incorrectly too many times and were blocked via automatic brute force detection in Auth0. At this point, they have not been migrated to Auth0 and so they do not have a user profile and are not visible under "users" however they do exist in the Auth0 credentials database. When a user is blocked in this way, they will see the error message "Your account has been blocked after multiple failed login attempts. To unlock your account please reset your password using the 'forgot password' link below." but the only way to unblock users in this limbo state is via the management API. If the user requests a forgot password email and resets their email, they will still be blocked by Auth0. As a workaround, we have added a request to the "unblock users" endpoint of the Auth0 Management API to the Hybris Reset Password Lambda, so that at the same time as requesting a "forgot password" email we will automatically unblock users in Auth0.