Third-Party or Social Login in Storefront

In this guide, you'll learn how to implement third-party or social login in your storefront. You'll implement the flow using Google as an example.

Third-Party Login Flow in Storefront#

Assuming you already set up the Auth Module Provider in your Medusa application, you can login a customer with a third-party service, such as Google or GitHub, using the following flow:

1. Authenticate the customer with the Authenticate Customer API route. It may return:
   • A URL in a location property to authenticate with third-party service, such as login with Google. When you receive this property, you must redirect to the returned location.
   • A token in a token property. In that case, the customer was previously logged in with the third-party service, such as Google, and no additional actions are required. You can use the token to send subsequent authenticated requests.
2. Once the authentication with the third-party service finishes, it must redirect back to the storefront with query parameters such as code and state. So, make sure your third-party service is configured to redirect to your storefront's callback page after successful authentication.
3. In the storefront's callback page, send a request to the Validate Authentication Callback API route passing the query parameters (code, state, etc...) received from the third-party service.
4. If the callback validation is successful, you'll receive the authentication token. Decode the received token in the storefront using tools like react-jwt.
   • If the decoded data has an actor_id property, then the customer is already registered. So, use this token for subsequent authenticated requests.
   • If not, follow the rest of the steps.
5. The customer is not registered yet, so use the received token from the Validate Authentication Callback API route to create the customer using the Create Customer API route.
6. Send a request to the Refresh Token Route to retrieve a new token for the customer, passing the token from the Validate Authentication Callback API in the header. You can then use the token returned by the Refresh Token request to send subsequent authenticated requests.

You'll implement the flow in this guide using Google as an example. The example snippets use the JS SDK, but you can follow a similar approach without it, as well.

JS SDK Authentication Configuration#

Before implementing the third-party login flow, you need to configure in the JS SDK the authentication method you're using in your storefront. This defines how the JS SDK will handle sending authenticated requests after the customer is authenticated.

Learn more about the authentication methods and how to configure them in the Login Customer guide.

Step 1: Authenticate Customer in Medusa#

When the customer clicks on a "Login with Google" button, send a request to the Authenticate Customer API route.

For example:

You define a loginWithGoogle function that:

• Sends a request to the /auth/customer/google API route using the JS SDK's auth.login method.
• If the response is an object with a location property, then you redirect to the returned page for authentication with the third-party service.
• If the response is a string, then the customer has been authenticated before and the method returns the customer's authentication token.
• Now, all subsequent requests are authenticated. As an example, you can retrieve the customer's details using the store.customer.retrieve method.
  • Notice that the JS SDK sets and passes the authentication headers or session cookies (based on your configured authentication method) automatically. If you're not using the JS SDK, make sure to pass the necessary headers in your request as explained in the API reference.

Step 2: Callback Page in Storefront#

In the previous step, you implemented as part of the login flow redirecting the customer to the third-party service for authentication.

Once the customer authenticates with the third-party service, the service redirects the customer back to your storefront with query parameters such as code and state.

The next step is to create the page in your storefront that the customer is redirected to after they authenticate with Google. You'll use this page's URL as the Redirect Uri in your Google settings, and set it in the callbackUrl of your Google Auth Module Provider's configurations.

Install the React-JWT Library#

First, install the react-jwt library in your storefront to use it for decoding the token received from Google:

npm
yarn
pnpm

Implement the Callback Page#

Then, in a new page in your storefront that will be used as the callback / redirect uri destination, add the following:

This adds in the new page the function sendCallback which sends a request to the Validate Callback API route, passing it all query parameters received from Google. Those include the code and state parameters.

Notice that the JS SDK stores the JWT token returned by the Validate Callback API route automatically and attaches it to subsequent requests. If you're building this authentication flow without the JS SDK, you need to pass it manually to the next requests.

Add the Function to Create a Customer#

Next, replace the TODO after the sendCallback function with the following:

JS SDK / React Applicable
1const createCustomer = async () => {2  // create customer3  await sdk.store.customer.create({4    email: "example@medusajs.com",5  })6}7
8// TODO add more functions...

This adds to the page the function createCustomer which creates a customer if this is the first time the customer is authenticating with the third-party service.

Notice that this method assumes that the token received from the Validate Callback API route is already set in the JS SDK. So, if you're implemeting this flow without using the JS SDK, make sure to pass the token received from the Validate Callback API route in the authorization Bearer header.

Add the Function to Refresh the Token#

Next, replace the new TODO with the following:

JS SDK / React Applicable
1const refreshToken = async () => {2  // refresh the token3  const result = await sdk.auth.refresh()4}5
6// TODO add more functions...

This adds to the page the function refreshToken which is used after the new customer is created to refresh their authentication token. This ensures that the authentication token includes the details of the created customer.

Notice that this method assumes that the token received from the Validate Callback API route is already set in the JS SDK. So, if you're implemeting this flow without using the JS SDK, make sure to pass the token in the authorization Bearer header.

The refreshToken method also updates the token stored by the JS SDK, ensuring that next requests use that token. So, if you're not using the JS SDK, make sure to pass the new token in the request header as explained in the API reference.

Add the Function to Validate the Callback#

Finally, add in the place of the new TODO the validateCallback function that runs when the page first loads to validate the authentication:

The validateCallback function uses the functions added earlier to:

1. Send a request to the Validate Callback API route, which returns an authentication token.
   • The sendCallback function also sets the token in the JS SDK to be passed in subsequent requests.
2. Decodes the token to check if it has an actor_id property.

• If so, then the customer is previously registered, and the authentication token can be used for subsequent authenticated requests.
• If not, this is the first time the customer is authenticating with the third-party service, so:
  1. Create a customer using the Create Customer API route.
  2. Refetch the customer's authentication token after it's created using the Refresh Token API route.
  3. Use the token for subsequent authenticated requests.

3. Retrieve the customer's details as an example of testing authentication.

The customer is now authenticated, and you can redirect them to the home page or the page they were trying to access before logging in.

Full Code Example for Third-Party Login Callback Page#