@finsweet/auth-sdk

v1.11.4

Published

9 months ago

Finsweet Auth SDK.

Downloads

0High
0Medium
0Low

erikmejias

alexiglesias

Finsweet Auth SDK for Webflow sites

Integrate Finsweet Authentication on top of a Webflow site.

Features:

Log users with Finsweet SSO.
Protect pages from unauthenticated users.
Protect pages from unauthorized users if they don't have a specific subscription.
Update UI elements with the user's info.
Show/hide UI elements based on the user's auth.
Extendable with JavaScript.

Index:

Get started

Import the SDK using the CDN at the beginning of the <head>.

<!-- Finsweet Auth -->
<script src="https://cdn.jsdelivr.net/npm/@finsweet/auth-sdk@1/auth-sdk.js"></script>

You need to pass some properties to the script to create the instance. To do so, there are two options:

Both options are complementary. Attributes instantiation is more specific than JavaScript instantiation, so it will override the properties you pass to it.

Instantiate with JavaScript

Create a window.fsAuth object before importing the library script.

<script>
  window.fsAuth = {
    client_id: '{CLIENT_ID}',
    redirect_uri: '{REDIRECT_URL}',
    returnTo: '{RETURN_URL}',
    protect: '{IS_PROTECTED} | {ALLOWED_PRODUCTS}',
    loginPage: '{CUSTOM_LOGIN_PAGE}',
  };
</script>

Where the properties are:

| Attribute | Required (either with JavaScript or Attributes) | Description | Example | | -------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | client_id | Yes | Defines the client_id of the Auth0 Application. | sdfg54s6d4ba78f4sv10e8rwewerfs2 | | redirect_uri | Yes | Defines where the users will be redirected after a successful login.This URL must be set in the Allowed Callback URLs setting in Auth0. | https://www.example.com/dashboard | | returnTo | Yes | Defines where the users will be redirected after a successful logout.This URL must be set in the Allowed Logout URLs setting in Auth0. | https://www.example.com/landing | | protect | No | Defines if the current page is protected. There are two ways of setting this property:- If set to true, only logged-in users will be able to access the page.- If set to an array of Stripe Product IDs, only users subscribed to those products will be able to access the page. | true["prod_LL0lRhbk39h3kg", "prod_LL0nYsoD4dvxvh"] | | loginPage | No | By default, this library redirects the users to Auth0's SSO Login page when they are required to be logged in.If this param is defined, users will be redirected to this URL instead. | https://www.example.com/login |

Note: Required properties only need to be set 1 time. If you set, for example, client_id using JavaScript, there's no need to also set it using Attributes unless you want to override it.

Instantiate with Attributes

This method is similar, but properties are added directly to the <script> tag.

Any property set to the <script> using Attributes will override previous existing properties that have been set using JavaScript. This combination allows you, for example, to set up some properties in the global Custom Code of the project, and then add/override some properties when importing the <script> into each individual page.

<!-- Finsweet Auth -->
<script
  src="https://cdn.jsdelivr.net/npm/@finsweet/auth-sdk@1/auth-sdk.js"
  fs-auth-id="{CLIENT_ID}"
  fs-auth-redirect="{REDIRECT_URL}"
  fs-auth-return="{RETURN_URL}"
  fs-auth-protect="{IS_PROTECTED} | {ALLOWED_PRODUCTS}"
  fs-auth-login="{CUSTOM_LOGIN_PAGE}"
></script>

Where the Attributes are:

| Attribute | Required (either with JavaScript or Attributes) | Description | Example | | ------------------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | fs-auth-id | Yes | Defines the client_id of the Auth0 Application. | fs-auth-id="sdfg54s6d4ba78f4sv10e8rwewerfs2" | | fs-auth-redirect | Yes | Defines where the users will be redirected after a successful login.This URL must be set in the Allowed Callback URLs setting in Auth0. | fs-auth-redirect="https://www.example.com/dashboard" | | fs-auth-return | Yes | Defines where the users will be redirected after a successful logout.This URL must be set in the Allowed Logout URLs setting in Auth0. | fs-auth-return="https://www.example.com/landing" | | fs-auth-protect | No | Defines if the current page is protected. There are two ways of setting this property:- If set to true, only logged-in users will be able to access the page.- If set to comma-separated Stripe Product IDs, only users subscribed to those products will be able to access the page. | fs-auth-protect="true"fs-auth-protect="prod_LL0lRhbk39h3kg, prod_LL0nYsoD4dvxvh" | | fs-auth-login | No | By default, this library redirects the users to Auth0's SSO Login page when they are required to be logged in.If this param is defined, users will be redirected to this URL instead. | https://www.example.com/login |

Note: Required properties only need to be set 1 time. If you set, for example, client_id using JavaScript, there's no need to also set it using Attributes unless you want to override it.

Global elements

You can define some elements on each page using Attributes:

| Attribute | Description | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | fs-auth-element="login" | Defines a login button.If the user is already logged-in, the button will be hidden.Optionally, you can add the fs-auth-redirect attribute to this element if you want to override the global redirect property for this element. | | fs-auth-element="logout" | Defines a logout button.If the user is not logged-in, the button will be hidden.Optionally, you can add the fs-auth-return attribute to this element if you want to override the global return property for this element. | | fs-auth-element="loader" | Defines a loader element.The library will hide this element after it finishes loading. |

When these elements are successfuly shown, the fs-auth-cloak attribute is removed from them.

If you want to preseve the elements on the page when they should be hidden (like showing a login button even when the user is already logged in), you can optionally add the following attribute to them:

fs-auth-preserve="true"

User elements

You can populate some elements on each page using the User's info. The properties you can use are:

| Attribute | Description | Example | | ---------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------- | | fs-auth-user="name" | Populates the user's entire name, if defined. | John Doe | | fs-auth-user="given-name" | Populates the user's given name, if defined. | John | | fs-auth-user="family-name" | Populates the user's family name (surname), if defined. | Doe | | fs-auth-user="nickname" | Populates the user's nickname, if defined. | johndoe | | fs-auth-user="email" | Populates the user's email, if defined. | [email protected] | | fs-auth-user="birthdate" | Populates the user's birthdate, if defined. | 01/01/1970 | | fs-auth-user="country" | Populates the user's country, if defined. | US | | fs-auth-user="website" | Populates the user's website, if defined. | https://johndoe.com | | fs-auth-user="picture" | Populates the user's picture, if defined.This attribute is only allowed on Image elements. | https://johndoe.com/images/profile.jpg |

Populating the elements follows this rules:

If an element is successfuly populated (which means that the user is logged in and his profile has the property defined), the fs-auth-cloak attribute is removed from it.
If not (which means that the user is not logged in or that the property is not defined), the fs-auth-cloak attribute is kept.

You can also add fallbacks by comma-separating the properties. When implementing fallbacks, the first existing property will be rendered.

For example, when we want to display the given-name but also make sure that we display something else if the user doesn't have this value, you can write:

fs-auth-user="given-name, name, nickname"

In this case, the library will try to populate given-name. If it fails, it will try name, and lastly nickname.

Protected elements

You can protect individual elements to be only displayed to users that match a condition by adding the following attribute:

fs-auth-protect="{IS_PROTECTED} | {ALLOWED_PRODUCTS}"

It works the same way as the protect property of the page instance:

If set to true, only logged-in users will be able to access the element. Example: fs-auth-protect="true".
If set to comma-separated Stripe Product IDs, only users subscribed to those products will be able to access the element. Example: fs-auth-protect="prod_LL0lRhbk39h3kg, prod_LL0nYsoD4dvxvh".

And follows this rules:

If the user can access the element, the fs-auth-cloak attribute is removed from it.
If the user can't access the element, the element is removed.

Hidden elements

Opposite to protected elements, you can also hide individual elements from users that match a condition. Example use case: you want to show a button to all unsubscribed users, but hide it for subscribed users.

You can do it by adding the following attribute:

fs-auth-hide="{IS_PROTECTED} | {ALLOWED_PRODUCTS}"

If set to true, logged-in users will not be able to access the element. Example: fs-auth-hide="true".
If set to comma-separated Stripe Product IDs, users subscribed to those products will not be able to access the element. Example: fs-auth-hide="prod_LL0lRhbk39h3kg, prod_LL0nYsoD4dvxvh".

And follows this rules:

If the user can access the element, the fs-auth-cloak attribute is removed from it.
If the user can't access the element, the element is removed.

Cloak helper

As a helper to avoid content flashes, you can optionally add the following attribute to any element:

fs-auth-cloak="true"

This attribute will be removed from the element only if the element must be displayed. It is inspired from Vue's v-cloak attribute.

This means that if you define the following CSS in the <head> tag:

<style>
  [fs-auth-cloak] {
    display: none;
  }
</style>

Elements having this attribute:

Will be initially hidden when the page starts loading.
After the library loads and checks if the user is authenticated, it will remove it from the elements that can be shown.

This allows to prevent flashing elements that shouldn't be displayed while the library is loading.

Extending with JavaScript

The library populates the window.fsAuth object with the following properties that you can use to write your own logic:

interface FsAuth {
  /**
   * A promise that resolves when the library has finished loading and authenticating the user.
   * @returns The same {@link FsAuth} object for convenience.
   */
  loading: Promise<FsAuth>;

  /**
   * The Auth0 instance.
   */
  auth0: Auth0Client;

  /**
   * Defines if the user is logged in.
   */
  isAuthenticated: boolean;

  /**
   * The User object, if logged in.
   */
  user?: User;

  /**
   * The user's subscriptions.
   */
  subscriptions?: Promise<Subscription[]>;

  /**
   * Defines if the user is allowed to access the current page.
   */
  allowed?: boolean;

  /**
   * Stores error objects, if existing.
   */
  error?: Error;

  /**
   * The settings set when creating the instance.
   *
   *
   * The Auth0 Client ID.
   */
  client_id: string;

  /**
   * The URL to return after a successful login. Must be whitelisted in Auth0.
   */
  redirect_uri?: string;

  /**
   * The URL to return after a successful login, or after a failed try to access a protected page.
   */
  returnTo?: string;

  /**
   * By default, this library redirects the users to Auth0's SSO Login page when they are required to be logged in.
   * If defined, users will be redirected to this URL instead.
   */
  loginPage?: string;

  /**
   * Defines if the current page has any sort of protection.
   */
  protect?: Protection;

  /**
   * Defines if the current page should be hidden for specific users.
   */
  hide?: Protection;

  /**
   * The current version of the Auth SDK.
   */
  version: string;

  /**
   * Processes DOM Elements to:
   * - Add login/logout functionality.
   * - Populate elements with user data.
   * - Show/hide protected elements.
   *
   * @param elements A single Element, Array or NodeList of Elements to process.
   */
  handleUI: (elements: Element | Element[] | NodeListOf<Element>) => Promise<void>;
}

This window.fsAuth object is frozen using Object.freeze() to avoid unauthorized third party mutations.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme