Use Descope With Bubble

Using Bubble to create web applications offers flexibility and control over your design and functionality. This guide will help you implement Descope's advanced authentication features into your Bubble project.

There are two ways to integrate Descope into your Bubble application:

1. Using OIDC and the Auth Hosting Application. This is the recommended integration as it syncs with Bubble's user management system
2. Embedding your Flow as an HTML component

Implementing Descope with OIDC

The Descope Auth Hosting Application is designed to host and run your Descope Flows without needing to implement any of our SDKs. Using this method logs the user into Bubble as a Bubble user allowing you to use Bubble's user actions and conditions. This is the recommended integration method.

Setting up OIDC

1. Access your Bubble editor, select your project, and navigate to the Plugins tab.
2. Install the API Connector plugin by clicking + Add Plugins.
3. Once installed click on Add Another API in the plugin.

4. In Descope go to Applications and click on OIDC default application.
5. In the Flow Hosting URL field you can change the flow parameter to match the flow ID of the flow you want to be displayed.

6. Go to Access Keys and create an access key. Make sure to copy the access key to clipboard before closing it.

7. In the Bubble API plugin expand the API you added:
   • Change Authentication to OAuth2 User-Agent Flow
   • Paste the Access key you copied into App Secret
   • Go to Project Settings and copy the Project ID into App ID
   • Paste openid profile email descope.claims into Scope
   • Paste https://api.descope.com/oauth2/v1/authorize into Login dialog redirect
   • Paste https://api.descope.com/oauth2/v1/token into Access token endpoint
   • Paste https://api.descope.com/oauth2/v1/userinfo into User profile endpoint
   • Paste sub into User ID key path
   • Make sure the checkboxes below are checked

Setting up Login/Sign-Up in Bubble

1. Add a button to your Bubble app, then add a workflow to the button. This will be the button that initiates login/sign-up.
2. In the workflow add an action Account->Sign-up/login with a social network. For OAuth provider click on the API you created.
3. After the user completes this step they will be logged into Descope and Bubble, you can add any additional navigation logic or actions.
4. You must initialize you Descope API by previewing your Bubble app with ?debug_mode=true in the URL and click the button you created. You should get an API initialized message from Bubble.

5. Because the user is now logged in as a Bubble user you can use Bubble techniques to restrict pages and data to authenticated users only. Some examples include:
   • Creating a workflow on protected pages that sends users to the log-in page if they are not logged in.
   • Grouping all sensitive authenticated user data and elements and displaying them conditionally if a user is logged in and making sure This element is visible by page load is unchecked.
   • You can use any of the same workflows you would if you were using basic Bubble authentication.

Updating Roles and Permissions in Bubble

If you have your Roles/Permissions set up as Option Sets in Bubble, you can get a users roles and permissions from Descope when they log in.

1. In the API Plugin go to the Descope API you created and click Add Another Call.
2. Add the user info endpoint you used earlier https://api.descope.com/oauth2/v1/userinfo. Make sure the API is set to Use as Data
3. Once you've initialized the main API by running your Bubble app in debug mode click on Initialize call in the API plugin.

4. In the response you can set Roles as your roles option set and Permissions as your permissions option set and then click Save.

5. Now you can add the Change Thing action to your login workflow. Set the Thing to change to Current User. Add an additional field for roles or permissions, use get data from API and select the Descope API User Info Call. After this you can handle the logic to suit your roles and permissions setup.

6. Now when your user logs in, the roles and permissions will update in Bubble to match the ones set in Descope.

Logging out of Bubble

Because the user is logged in as a Bubble User you can use Bubble's actions to log the user out.

1. In your logout workflow you can use the Log the user out action.
2. If you want to make sure users need to reauthenticate every time they are logged out of Bubble, go to Applications and click Force Authentication. This will make sure that if they are logged out of Bubble they will no be automatically logged in.

Implement Descope as HTML Component

Getting Started with Bubble Settings

1. Access your Bubble editor, select your project, and navigate to the Settings tab.

2. Go to the SEO/meta tags section and scroll down to Script/meta tags in header:

3. Insert the Descope SDK script into this section to enable the authentication features across your site:

<script src="https://unpkg.com/@descope/web-js-sdk@x.x.x/dist/index.umd.js" ></script>

Setting Up the Login/Sign-Up Page

1. Return to your Bubble editor and create a new page by clicking New Page. Name it Login.

2. Drag a HTML element onto the canvas from the Visual Elements panel:

3. Paste the following HTML and script into the HTML element:

<script src="https://unpkg.com/@descope/web-component@x.x.x/dist/index.js"></script>
<descope-wc project-id="__ProjectID__" flow-id="sign-up-or-in"></descope-wc>
 
<script>
        const wcElement = document.getElementsByTagName('descope-wc')[0];
	const onSuccess = () => {
            window.location.replace('/');
	};
	const onError = (err) => console.log(err);
 
	wcElement.addEventListener('success', onSuccess);
	wcElement.addEventListener('error', onError);
</script>

This will create a login/sign-up interface on your page, and handle user authentication and redirection upon successful login.

Here is the updated section that includes a note on how to protect only specific pages instead of the entire site using the footer script:

Managing Unauthorized Access

Ensure users who are not authenticated are redirected to the login page:

1. In the same Settings tab under SEO/meta tags, scroll to Script to run in the page footer and add this code:

<script>
  const sdk = Descope({ projectId: "__ProjectID__", persistTokens: true });
 
  const sessionToken = sdk.getSessionToken();
  const currentPath = window.location.pathname;
  if (!sessionToken || sdk.isJwtExpired(sessionToken)) {
    const protectedPages = ['/profile', '/dashboard', '/settings']; // Add the paths of the pages you want to protect
    if (protectedPages.includes(currentPath) && currentPath !== '/login') {
      window.location.replace('/login');
    }
  }
</script>

This approach allows you to selectively protect pages, giving you greater control over which parts of your Bubble application require user authentication.

Displaying User Details in Your Frontend

To fetch and display user details after authentication:

const sessionToken = sdk.getSessionToken();
if (sessionToken) {
  getProfile();
}
 
async function getProfile() {
  const profile = await sdk.me(sdk.getRefreshToken());
  document.getElementById('userName').innerText = profile.data.name;
  document.getElementById('userEmail').innerText = profile.data.email;
}

Final Thoughts

Integrating Descope into your Bubble application provides robust authentication capabilities, seamlessly integrated into your no-code development workflow. For additional features like logout functionality or backend session validation, please refer to our comprehensive documentation:

1. Logout Using Client SDK - here
2. Backend Session Validation - here
3. Roles and Permissions - This can be found in Step 7 of the guide here

If you have any questions or require further assistance, please contact our support team at Descope.

This guide should now enable you to integrate Descope with your Bubble platform smoothly and efficiently.