Authentication Flows with the Auth Main Service

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

Authentication Methods#

Register#

The register method of the Auth Module's main 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    // ...6  }7)

This method calls the register method of the provider specified in the first parameter and returns its data.

Authenticate#

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

Code
1const data = await authModuleService.authenticate(2  "emailpass",3  // passed to auth provider4  {5    // ...6  }7)

This method calls the authenticate method of the provider specified in the first parameter and returns its data.


Auth Flow 1: Basic Authentication#

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

Code
1const { success, authIdentity, error } = await authModuleService.register(2  "emailpass",3  // passed to auth provider4  {5    // ...6  }7)8
9if (error) {10  // registration failed11  // TODO return an error12  return13}14
15// later (can be another route for log-in)16const { success, authIdentity, location } = await authModuleService.authenticate(17  "emailpass",18  // passed to auth provider19  {20    // ...21  }22)23
24if (success && !location) {25  // user is authenticated26}

If success is true and location isn't set, the user is authenticated successfully, and their authentication details are available within the authIdentity object.

The next section explains the flow if location is set.

Note: Check out the AuthIdentity reference for the received properties in authIdentity.

Diagram showcasing the basic authentication flow

Auth Identity 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.

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    // ...6  }7)8
9if (location) {10  // return the location for the front-end to redirect to11}12
13if (!success) {14  // authentication failed15}16
17// 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 front-end or client to redirect to that URL.

For example, when using the google provider, the location is the URL that the user is navigated to login.

Diagram showcasing the first part of the third-party authentication flow

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 its actor type. For example, you redirect admin users and customers to different pages.

Code
1const { success, authIdentity, location } = await authModuleService.authenticate(2  "google",3  // passed to auth provider4  {5    // ...6    callback_url: "example.com",7  }8)

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 main 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}
Tip: For providers like Google, the query object contains the query parameters from the original callback URL, such as the code and state parameters.

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

Diagram showcasing the second part of the third-party authentication flow


Reset Password#

To update a user's password or other authentication details, use the updateProvider method of the Auth Module's main 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 an email and password properties.

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

Was this page helpful?
Ask Anything
FAQ
What is Medusa?
How can I create a module?
How can I create a data model?
How do I create a workflow?
How can I extend a data model in the Product Module?
Recipes
How do I build a marketplace with Medusa?
How do I build digital products with Medusa?
How do I build subscription-based purchases with Medusa?
What other recipes are available in the Medusa documentation?
Chat is cleared on refresh
Line break