Webflow integration guide

This guide will show you how to integrate Logto into your Webflow sites.

tip

• The sample project is available at Webflow project preview.
• A live demo is deployed at https://charless-trendy-site-f191c0.webflow.io/.

Prerequisits

1. Integrating Logto with Webflow requires the "Custom code" feature of Webflow, which requires at least the "Basic" plan.
2. A Webflow site, either use an existing site or create a new one.

Integration

Init Logto provider

note

In the following steps, we assume your Webflow site is running on https://your-awesome-site.webflow.io.

In this step, we'll add global-level custom code to your Webflow site. Since NPM is not supported in Webflow, we'll use the jsdelivr.com CDN service to import the Logto SDK.

Open the "Site settings" page, and navigate to the "Custom code" section. Add the following code to the "Head code" section.

<script type="module">
  // Import \`@logto/browser\` SDK from the jsdelivr CDN
  import LogtoClient from 'https://esm.run/@logto/browser';

  // Assign the \`logtoClient\` instance to window object,
  // enabling global usage in other pages
  window.logtoClient = new LogtoClient({
    endpoint: '<your-logto-endpoint>', // E.g. http://localhost:3001
    appId: '<your-application-id>',
  });
</script>

Implement sign-in

Before we dive into the details, here's a quick overview of the end-user experience. The sign-in process can be simplified as follows:

1. Your app invokes the sign-in method.
2. The user is redirected to the Logto sign-in page. For native apps, the system browser is opened.
3. The user signs in and is redirected back to your app (configured as the redirect URI).

Regarding redirect-based sign-in

1. This authentication process follows the OpenID Connect (OIDC) protocol, and Logto enforces strict security measures to protect user sign-in.
2. If you have multiple apps, you can use the same identity provider (Logto). Once the user signs in to one app, Logto will automatically complete the sign-in process when the user accesses another app.

To learn more about the rationale and benefits of redirect-based sign-in, see Logto sign-in experience explained.

---

Configure sign-in redirect URI

Let's switch to the Application details page of Logto Console. Add a Redirect URI https://your-awesome-site.webflow.io/callback and click "Save changes".

Implement a sign-in button

Return to your Webflow designer, drag and drop a "Sign in" button to the home page, and assign it an ID “sign-in” for later reference using getElementById().

<script type="module">
  const signInButton = document.getElementById('sign-in');
  const onClickSignIn = () => logtoClient.signIn('https://your-awesome-site.webflow.io/callback');
  signInButton.addEventListener('click', onClickSignIn);
</script>

Handle redirect

We're almost there! In the last step, we use https://your-awesome-site.webflow.io/callback as the Redirect URI, and now we need to handle it properly.

First let's create a "Callback" page in Webflow, and simply put some static text "Redirecting..." on it. Then add the following page-level custom code to "Callback" page.

<script type="module">
  (async () => {
    // Handle sign-in callback logic by calling the SDK method
    await logtoClient.handleSignInCallback(window.location.href);

    // Redirect back to the home page when the handling is done
    window.location.assign('https://your-awesome-site.webflow.io');
  })();
</script>

Implement sign-out

Calling .signOut() will clear all the Logto data in memory and localStorage if they exist.

After signing out, it'll be great to redirect your user back to your website. Let's add https://your-awesome-site.webflow.io as one of the Post Sign-out URIs in Admin Console (shows under Redirect URIs), and use the URL as the parameter when calling .signOut().

Implement a sign-out button

Return to the Webflow designer, and add a “Sign out” button on your home page. Similarly, assign an ID “sign-out” to the button, and add the following code to the page-level custom code.

const signOutButton = document.getElementById('sign-out');
const onClickSignOut = () => logtoClient.signOut('https://your-awesome-site.webflow.io');
signOutButton.addEventListener('click', onClickSignOut);

Handle authentication status

In Logto SDK, generally we can use logtoClient.isAuthenticated() method to check the authentication status, if the user is signed in, the value will be true; otherwise, it will be false.

In your Webflow site, you can also use it to programmatically show and hide the sign-in and sign-out buttons. Apply the following custom code to adjust button CSS accordingly.

const isAuthenticated = await logtoClient.isAuthenticated();

signInButton.style.display = isAuthenticated ? 'none' : 'block';
signOutButton.style.display = isAuthenticated ? 'block' : 'none';

Checkpoint: Test your Webflow site

Now, test your site:

1. Deploy and visit your site URL, the sign-in button should be visible.
2. Click the sign-in button, the SDK will initiate the sign-in process, redirecting you to the Logto sign-in page.
3. After signing in, you will be redirected back to your site, seeing the username and the sign-out button.
4. Click the sign-out button to sign-out.

Get user information

You can use these Logto methods to retrieve user information programmatically:

• getIdTokenClaims: Get user information by decoding the local ID token. Some claims may not be available.
• fetchUserInfo: Get user information by sending a request to the userinfo endpoint.

It's important to note that the user information claims that can be retrieved depending on the scopes used by the user during signing-in, and considering performance and data size, the ID token may not contain all user claims, some user claims are only available in the userinfo endpoint (see the related list below).

Logto uses OIDC scopes and claims conventions to define the scopes and claims for retrieving user information from the ID token and OIDC userinfo endpoint. Both of the "scope" and the "claim" are terms from the OAuth 2.0 and OpenID Connect (OIDC) specifications.

In short, when you request a scope, you will get the corresponding claims in the user information. For example, if you request the `email` scope, you will get the `email` and `email_verified` data of the user.

By default, Logto SDK will always request three scopes: `openid`, `profile`. And `offline_access`, and there is no way to remove these default scopes. But you can add more scopes when configuring Logto:

<script type="module">
  // Import \`@logto/browser\` SDK from the jsdelivr CDN
  import LogtoClient from 'https://esm.run/@logto/browser';

  // Assign the \`logtoClient\` instance to window object,
  // enabling global usage in other pages
  window.logtoClient = new LogtoClient({
    endpoint: '<your-logto-endpoint>', // E.g. http://localhost:3001
    appId: '<your-application-id>',
    scopes: [
      UserScope.Email,
      UserScope.Phone,
      UserScope.CustomData,
      UserScope.Identities,
      UserScope.Organizations,
    ],
  });
</script>

Here's the list of supported scopes and the corresponding claims:

openid

Claim name	Type	Description	Needs userinfo?
sub	string	The unique identifier of the user	No

profile

Claim name	Type	Description	Needs userinfo?
name	string	The full name of the user	No
username	string	The username of the user	No
picture	string	URL of the End-User's profile picture. This URL MUST refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image. Note that this URL SHOULD specifically reference a profile photo of the End-User suitable for displaying when describing the End-User, rather than an arbitrary photo taken by the End-User.	No
created_at	number	Time the End-User was created. The time is represented as the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).	No
updated_at	number	Time the End-User's information was last updated. The time is represented as the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).	No

Other standard claims include family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo, and locale will be also included in the profile scope without the need for requesting the userinfo endpoint. A difference compared to the claims above is that these claims will only be returned when their values are not empty, while the claims above will return null if the values are empty.

note

Unlike the standard claims, the created_at and updated_at claims are using milliseconds instead of seconds.

email

Claim name	Type	Description	Needs userinfo?
email	string	The email address of the user	No
email_verified	boolean	Whether the email address has been verified	No

phone

Claim name	Type	Description	Needs userinfo?
phone_number	string	The phone number of the user	No
phone_number_verified	boolean	Whether the phone number has been verified	No

address

Please refer to the OpenID Connect Core 1.0 for the details of the address claim.

custom_data

Claim name	Type	Description	Needs userinfo?
custom_data	object	The custom data of the user	Yes

identities

Claim name	Type	Description	Needs userinfo?
identities	object	The linked identities of the user	Yes
sso_identities	array	The linked SSO identities of the user	Yes

urn:logto:scope:organizations

Claim name	Type	Description	Needs userinfo?
organizations	string[]	The organization IDs the user belongs to	No
organization_data	object[]	The organization data the user belongs to	Yes

urn:logto:scope:organization_roles

Claim name	Type	Description	Needs userinfo?
organization_roles	string[]	The organization roles the user belongs to with the format of <organization_id>:<role_name>	No

---

Considering performance and the data size, if "Needs userinfo?" is "Yes", it means the claim will not show up in the ID token, but will be returned in the userinfo endpoint response.

API resources

We recommend to read 🔐 Role-Based Access Control (RBAC) first to understand the basic concepts of Logto RBAC and how to set up API resources properly.

Configure Logto client

Once you have set up the API resources, you can add them when configuring Logto in your app:

<script type="module">
  // Import \`@logto/browser\` SDK from the jsdelivr CDN
  import LogtoClient from 'https://esm.run/@logto/browser';

  // Assign the \`logtoClient\` instance to window object,
  // enabling global usage in other pages
  window.logtoClient = new LogtoClient({
    endpoint: '<your-logto-endpoint>', // E.g. http://localhost:3001
    appId: '<your-application-id>',
    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // Add API resources
  });
</script>

Each API resource has its own permissions (scopes).

For example, the https://shopping.your-app.com/api resource has the shopping:read and shopping:write permissions, and the https://store.your-app.com/api resource has the store:read and store:write permissions.

To request these permissions, you can add them when configuring Logto in your app:

<script type="module">
  // Import \`@logto/browser\` SDK from the jsdelivr CDN
  import LogtoClient from 'https://esm.run/@logto/browser';

  window.logtoClient = new LogtoClient({
    endpoint: '<your-logto-endpoint>',
    appId: '<your-application-id>',
    scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
  });
</script>

You may notice that scopes are defined separately from API resources. This is because Resource Indicators for OAuth 2.0 specifies the final scopes for the request will be the cartesian product of all the scopes at all the target services.

Thus, in the above case, scopes can be simplified from the definition in Logto, both of the API resources can have read and write scopes without the prefix. Then, in the Logto config:

<script type="module">
  // Import \`@logto/browser\` SDK from the jsdelivr CDN
  import LogtoClient from 'https://esm.run/@logto/browser';

  window.logtoClient = new LogtoClient({
    endpoint: '<your-logto-endpoint>',
    appId: '<your-application-id>',
    scopes: ['read', 'write'],
    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
  });
</script>

For every API resource, it will request for both read and write scopes.

note

It is fine to request scopes that are not defined in the API resources. For example, you can request the email scope even if the API resources don't have the email scope available. Unavailable scopes will be safely ignored.

After the successful sign-in, Logto will issue proper scopes to API resources according to the user's roles.

Fetch access token for the API resource

To fetch the access token for a specific API resource, you can use the getAccessToken method:

const isAuthenticated = await logtoClient.isAuthenticated();

if (isAuthenticated) {
  (async () => {
    const token = await logtoClient.getAccessToken();
    console.log(token);
  })();
}

This method will return a JWT access token that can be used to access the API resource when the user has related permissions. If the current cached access token has expired, this method will automatically try to use a refresh token to get a new access token.

Fetch organization tokens

If organization is new to you, please read 🏢 Organizations (Multi-tenancy) to get started.

You need to add UserScope.Organizations scope when configuring the Logto client:

import LogtoClient, { UserScope } from 'https://esm.run/@logto/browser';

window.logtoClient = new LogtoClient({
  // ...other configs
  scopes: [UserScope.Organizations],
});

Once the user is signed in, you can fetch the organization token for the user:

import { UserScope } from 'https://esm.run/@logto/browser';

const isAuthenticated = await logtoClient.isAuthenticated();

(async () => {
  if (!isAuthenticated) {
    return;
  }
  const claims = await logtoClient.getIdTokenClaims();

  console.log('ID token claims:', claims);
  console.log('Organization IDs:', claims.organizations);

  // Assuming there's at least one organization, let's take the first one
  const organizationId = claims.organizations[0];
  const token = await logtoClient.getOrganizationToken(organizationId);

  console.log('Organization access token:', token);
})();

Further readings

• Customize sign-in experience
• Configure connectors
• Protect your API