Authentication

Overview

This guide will show you how to configure:

• Token-based authentication using JWKS
• Password reset URL
• Identity Provider (IDP)
• App keys for baskets and wishlists

Storefront Core uses OAuth to authenticate with the SCAYLE Checkout.

Before you start

Make sure you've completed the Setup your Storefront Guide.

Create a new API client using the SCAYLE Panel to get your:

• client_id
• client_secret

Token-based authentication using JWKS

Token-based authentication allows us to implement our login forms instead of relying on forms provided by the Checkout service.

Token-based authentication flow

Token verification (System overview)

Configuration

To implement our login forms, Storefront Core acts as an OAuth client and uses the Get JSON Web Key Set Authentication API endpoint returning keys for verify JSON Web Token:
{OAUTH_API_HOST}/.well-known/jwks.json.

The API host, client ID, and client secret are configured in the oauth property:

typescript

Copy

let config = {
    oauth: {
        apiHost: 'https://{{tenant-space}}.storefront.api.scayle.cloud/v1/',
        clientId: '1',
        clientSecret: '', // Set in .env NUXT_STOREFRONT_OAUTH_CLIENT_SECRET
    },
    auth: {
        redirect: {
            home: '',
            logout: ''
        }
    },
}

Environment variables

Protected RPC

If you want to add a protected RPC, the RPC must check again if there is a user within the request and the requested data/action can be requested/done by the user. This can be done by e.g. matching user IDs within the access token and e.g. the user ID within an order.
For user-related actions like changing the password, this is done by the Auth Service itself.

Password reset URL

Add a URL where a user can reset their password:

1. Go to the nuxt.config.ts.
2. Set storefront.shops.[1001].auth.resetPasswordUrl to the URL where a user can reset their password.

The password reset URL must include the query param hash={hash}. When the password-forgotten mail is sent, {hash} will be replaced with an actual hash, which is needed to reset the password.

typescript

Copy

export default {
  //...
  storefront: {
    //...
    shops: {
      1001: {
        //...
        auth: {
          resetPasswordUrl: 'http://localhost:3000/signin?hash={hash}',
        },
      },
    },
  },
}

Identity Providers

Identity Provider (IDP) support enables the option to use Single Sign-On (SSO). This simplifies the login process by reducing the number of passwords users need to remember, as one set of credentials is used across multiple websites.

The backbone of the Storefront Core integrated IDP support consists of two functionalities:

1. The internal part that runs useIDP() composable generates redirect URLs for all of the configured IDPs.
2. handleIDPLoginCallback performs the actual login in our system.

For more information, check the Authentication API Guide.

Configure Identity Provider

Configure your available Identity Providers in the nuxt.config.ts.

Currently available IDPs are Google, Facebook, Keycloak, Apple, and Okta.

typescript

Copy

export default {
  //...
  storefront: {
    // Global IDP configuration for all shops
    idp: {
      enabled: true,
      idpKeys: ['facebook', 'google'],
      idpRedirectURL: 'http://localhost:3000/signin',
    },
    //...
    shops: {
      1001: {
        // Shop-specific overrides for the IDP configuration
        idp: {
          enabled: true,
          idpKeys: ['facebook'],
          idpRedirectURL: 'http://localhost:3000/signin',
        },
      },
    },
  },
}

Redirect URL

Redirects of the URLs for the IDPs you configured are handled by the useIDP composable. Composables pack related functions together so that you can use them within Vue components.

The function checks if IDP is enabled, validates necessary configurations, and returns a list of redirect URLs for each IDP based on your shop configuration as the data return value.

ts

Copy

const { data: externalIDPRedirects, handleIDPLoginCallback } = await useIDP()

handleIDPLogin callback

Once the user clicks on the IDP button, the user is redirected to the IDP login page. After successful login, the user is redirected to the callback URL. That is the shop URL with the query parameter code appended to it. This code is used to generate the access token and refresh token.

ts

Copy

watch(
  () => route.query,
  async (query) => {
    if (query.code && isString(query.code)) {
      await handleIDPLoginCallback(query.code)
    }
  },
  {
    immediate: true,
  },
)

IDP Authentication flow

Styling IDP buttons

The IDPForm component in the Storefront Boilerplate renders login buttons for each provider defined by your configuration. Currently, we have pre-built style buttons for Google, Facebook, Keycloak, Apple, and Okta.

Add a new style to an IDP Service

If you want to add styles to a new IDP Service that is not predefined or override the default class name, you can modify the idpClasses object.

ts

Copy

const idpClasses: Record<string, string> = {
  google: 'bg-[#4285F4] text-white hover:bg-[#3869c1] focus:bg-[#3869c1]',
  facebook: 'bg-[#1877F2] text-white hover:bg-[#165dbb] focus:bg-[#165dbb]',
  keycloak: 'bg-[#C43A31] text-white hover:bg-[#a32b26] focus:bg-[#a32b26]',
  apple: 'bg-black text-white hover:bg-[#333333] focus:bg-[#333333]',
  okta: 'bg-[#0061F2] text-white hover:bg-[#004ecb] focus:bg-[#004ecb]',
}

App keys for baskets and wishlists

The appKeys configuration defines how keys are generated for baskets and wishlists.

wishlistKey and basketKey are template strings. When creating the key Storefront Core will replace {shopId} and {userId} with the current shopId and userId. It will then hash the result with the chosen hash algorithm.

md5 is currently still supported to provide backward-compatibility.

typescript

Copy

let config = {
    appKeys: {
        wishlistKey: 'wishlist_{shopId}_{userId}',
        basketKey: 'basket_{shopId}_{userId}',
        hashAlgorithm: 'sha256',
    },
}