Authentication Flows with the Auth Main Service

In this guide, you'll learn how to use the methods of the Auth Module's service to implement authentication flows and reset a user's password.

Authentication Methods#

Register#

The register method of the Auth Module's service creates an auth identity that can be authenticated later.

For example:

Code
1const data = await authModuleService.register(2  "emailpass",3  // passed to auth provider4  {5    // pass data from request parameters, such as6    url: "example.com",7    headers: req.headers,8    query: req.query,9    // pass in the body the data necessary for the authentication provider10    // to register the user, such as email and password11    body: {12      email: "user@example.com",13      password: "supersecret",14    },15    protocol: req.protocol,16  }17)

This method calls the register method of the provider specified in the first parameter. The method passes the second parameter as input for the provider, and returns its data.

Based on the returned data, you can determine if the registration was successful, and if any further action is required to complete the registration. This is explained further in the auth flows sections below.

Authenticate#

To authenticate or log in a user, you use the authenticate method of the Auth Module's service. For example:

Code
1const data = await authModuleService.authenticate(2  "emailpass",3  // passed to auth provider4  {5    // pass data from request parameters, such as6    url: "example.com",7    headers: req.headers,8    query: req.query,9    // pass in the body the data necessary for the authentication provider10    // to authenticate the user, such as email and password11    body: {12      email: "user@example.com",13      password: "supersecret",14    },15    protocol: req.protocol,16  }17)

This method calls the authenticate method of the provider specified in the first parameter. The method passes the second parameter as input for the provider, and returns its data.

Based on the returned data, you can determine if the authentication was successful, and if any further action is required to complete the authentication. This is explained further in the auth flows sections below.

Auth Flow 1: Basic Authentication#

The basic authentication flow requires first using the register method, then the authenticate method.

Step 1: Register User#

Code
1const { 2  success, 3  authIdentity, 4  error,5} = await authModuleService.register(6  "emailpass",7  // passed to auth provider8  {9    // pass data from request parameters, such as10    url: "example.com",11    headers: req.headers,12    query: req.query,13    // pass in the body the data necessary for the authentication provider14    // to register the user, such as email and password15    body: {16      email: "user@example.com",17      password: "supersecret",18    },19    protocol: req.protocol,20  }21)22
23if (error) {24  // registration failed25  // TODO return an error26  return27}

If the register method returns an error property, the registration failed, and you can return an error message to the user.

Otherwise, if the success property is true, the registration was successful, and the user's authentication details are available within the authIdentity object.

Registering Auth Identities with Same Identifier

If an auth identity, such as a customer, tries to register with an email of another auth identity, the register method returns an error. This can happen either if another customer is using the same email, or an admin user has the same email.

There are two ways to handle this:

• Consider the customer authenticated if the authenticate method validates that the email and password are correct. This allows admin users, for example, to authenticate as customers.
• Return an error message to the customer, informing them that the email is already in use.

Step 2: Authenticate User#

Code
1// later (can be another route for login)2const { 3  success, 4  authIdentity, 5  location,6} = await authModuleService.authenticate(7  "emailpass",8  // passed to auth provider9  {10    // pass data from request parameters, such as11    url: "example.com",12    headers: req.headers,13    query: req.query,14    // pass in the body the data necessary for the authentication provider15    // to authenticate the user, such as email and password16    body: {17      email: "user@example.com",18      password: "supersecret",19    },20    protocol: req.protocol,21  }22)23
24if (success && !location) {25  // user is authenticated26}

If the authenticate method returns a success property that is true, and the location property is not set, the user is authenticated successfully. Their authentication details are available within the authIdentity object.

Otherwise, if the location property is set, you must follow the third-party service authentication flow to complete the authentication.

Auth Flow 2: Third-Party Service Authentication#

The third-party service authentication method requires using the authenticate method first:

Code
1const { success, authIdentity, location } = await authModuleService.authenticate(2  "google",3  // passed to auth provider4  {5    // pass data from request parameters, such as6    url: "example.com",7    headers: req.headers,8    query: req.query,9    body: req.body,10    protocol: req.protocol,11  }12)13
14if (location) {15  // return the location for the frontend to redirect to16}17
18if (!success) {19  // authentication failed20}21
22// authentication successful

If the authenticate method returns a location property, the authentication process requires the user to perform an action with a third-party service. So, you return the location to the frontend or client to redirect to that URL.

For example, when using the google provider, the location is the URL that the user must be redirected to in order to log in with their Google account.

Overriding Callback URL#

The Google and GitHub providers allow you to override their callbackUrl option during authentication. This is useful when you redirect the user after authentication to a URL based on their actor type. For example, you redirect admin users and customers to different pages.

Code
1const { 2  success, 3  authIdentity, 4  location,5} = await authModuleService.authenticate(6  "google",7  // passed to auth provider8  {9    // ...10    callback_url: "example.com",11  }12)

validateCallback#

Providers handling this authentication flow must implement the validateCallback method. It implements the logic to validate the authentication with the third-party service.

So, once the user performs the required action with the third-party service (for example, log in with Google), the frontend must redirect to an API route that uses the validateCallback method of the Auth Module's service.

The method calls the specified provider’s validateCallback method passing it the authentication details it received in the second parameter:

Code
1const { success, authIdentity } = await authModuleService.validateCallback(2  "google",3  // passed to auth provider4  {5    // request data, such as6    url,7    headers,8    query,9    body,10    protocol,11  }12)13
14if (success) {15  // authentication succeeded16}

If the returned success property is true, the authentication with the third-party provider was successful.

Reset Password#

To update a user's password or other authentication details, use the updateProvider method of the Auth Module's service. It calls the update method of the specified authentication provider.

For example:

Code
1const { success } = await authModuleService.updateProvider(2  "emailpass",3  // passed to the auth provider4  {5    entity_id: "user@example.com",6    password: "supersecret",7  }8)9
10if (success) {11  // password reset successfully12}

The method accepts as a first parameter the ID of the provider, and as a second parameter the data necessary to reset the password.

In the example above, you use the emailpass provider, so you have to pass an object having entity_id and password properties.

If the returned success property is true, the password has been reset successfully.