WorkOS
WorkOS equips your app with advanced SSO and other enterprise-level functionalities. However, if your primary focus is to provide SSO mainly for individual end-users or small to medium-sized businesses, WorkOS might be more extensive than necessary.
In such cases, opting for our could be a more suitable and straightforward solution.
What is WorkOS
WorkOS specializes in helping developers prepare their apps for enterprise scalability, particularly by simplifying the inclusion of crucial security features such as and Directory Sync.
They also facilitate smoother integrations with user administration features systems like Systems for Cross-domain Identity Management (SCIM) and . Additionally, WorkOS offers a centralized platform for managing multiple integrations with various identity and directory providers, streamlining the process significantly.
End-user feature: Before we dive in, it’s important to understand that WorkOS is for your end-users – it does not affect the access to your Bubble account. For this, you may explore our Bubble for Enterprise article series.
Article series: Bubble for Enterprise
Why use WorkOS?
As your app expands or as you cater to larger clients, the significance of enterprise-grade security, seamless authentication, and user administration escalates. Single Sign-On (SSO) has become not just a sought-after feature among general users but in many cases a fundamental necessity for businesses at the enterprise level. The WorkOS plugins simplify the incorporation and management of these essential elements, allowing you to concentrate more on building and growing your app.
In essence, WorkOS empowers system administrators within larger organizations to manage and customize the access permissions granted to individual employees for specific services, like your app. WorkOS provides a centralized dashboard that enables administrators to efficiently allocate and configure access levels.
What can you use the WorkOS plugins for?
Bubble’s WorkOS features are divided into two different plugins:
The WorkOS SSO plugin
Short version: integrating Single-Sign on into your Bubble workflows.
The WorkOS SSO plugin is made for integrating the WorkOS Single Sign-On (SSO) functionality directly into your Bubble workflows. This integration not only simplifies the authentication process for your end-users but also enhances security and efficiency.
This lets you provide a seamless sign-on experience, allowing end-users to access your Bubble app using their existing enterprise credentials. This feature is particularly useful for apps targeting corporate or enterprise-level end-users, as it aligns with the sophisticated security protocols these organizations often require.
WorkOS works with any Identity Provider (IdP) that adheres to the . It's structured in accordance with the specifications, which simplifies the complex authentication processes involved with various IdPs.
The WorkOS workflow plugin
Short version: communicating with the WorkOS API, and making changes directly in your app that would otherwise need to be made in the WorkOS dashboard.
The WorkOS API plugin expands your toolkit significantly. It enables you to initiate a session in the Admin Portal — your hub for establishing connections — right within your Bubble app. Additionally, it adds a number of new actions to the workflow editor:
Plugin actions
WorkOS API - SSO - Get
WorkOS API - SSO - List Connections
WorkOS API - Organizations - Get
WorkOS API - Organizations - List Organizations
WorkOS API - Organizations - Create Organization
WorkOS API - Organizations - Update An Organization
WorkOS API - Organizations - Delete Organization
WorkOS API - Admin Portal - Generate
WorkOS API - Directory Sync - Get A Directory
WorkOS API - Directory Sync - List Directories
WorkOS API - Directory Sync - Delete A Directory
WorkOS API - Directory Sync - Get A Directory User
WorkOS API - Directory Sync - List Directory Users
WorkOS API - Directory Sync - Get A Directory Group
WorkOS API - Directory Sync - List Directory Groups
Webhooks - Validate Webhook
Installing the WorkOS plugins
The WorkOS plugins are made in partnership with WorkOS and are official Bubble plugins, but still need to be installed in the apps where you want to use them.
The easiest way to find and install them, is to search for WorkOS and then make sure that the listing author is WorkOS, as illustrated with the right-hand, red rectangles in the screenshot above.
Setting up your account and API key
API security: As always, it’s important to remember that API keys are sensitive information. You should not share it with anyone outside of your organization. Also, do not place it in any part of your app where it can be visible in your app’s source code.
The article series below covers this in more detail.
Article series: Security
Set up your account
Before you start the work in Bubble, you need to set up a WorkOS account. Head over to https://dashboard.workos.com/signup.
After creating your account, WorkOS may ask you to set up your team. Finish all the details needed to finish the process.
Accessing the API key
After signing up, you will be taken to the main WorkOS dashboard. On the left-hand side, you’ll find a menu where you can navigate to API keys.
It's essential to understand the terminological differences between WorkOS and Bubble for effective integration:
The API key in WorkOS is called the App secret in Bubble. This App secret is critical for secure communication in both the Staging and Production environments.
Similarly, the App ID in WorkOS corresponds to what Bubble refers to as the App ID/API key. This serves as a unique identifier for your app's integration with WorkOS.
Staging and production environments
WorkOS, much like many API providers and Bubble itself, operates in two distinct environments:
Staging, which is similar to Bubble's , allows for testing connections with greater freedom and no risk to live data.
Production, akin to Bubble’s Live environment, is the interface for end-users.
For each environment, WorkOS provides separate keys:
The Staging environment in WorkOS uses what Bubble terms as the App secret for its API key, and an App ID/API key corresponding to WorkOS's App ID.
Likewise, in the Production environment, you have a different set of App secret and App ID/API key, ensuring that your live app's interactions are secure and distinct from the testing environment.
This separation of keys prevents the overlap of testing and live operations, maintaining the integrity and security of your app's interactions with WorkOS.
Note that at the time of writing, WorkOS requires that you add billing information before you can access your production API key. The staging environment is available while you are building and testing your app, and WorkOS does not charge anything until you create your first billable resource in production.
Which of the two plugins should I use?
The order in which you set up Single Sign-On (SSO) and the WorkOS API can vary based on your specific needs and the functionalities you want to implement.
If your primary goal is to set up user authentication through SSO, it's logical to set up SSO first, and you may not need the WorkOS API plugin. This approach ensures that your app's user authentication aligns with enterprise standards.
On the other hand, if your focus is more on leveraging additional features that the WorkOS API offers, such as Directory Sync or advanced user management, you might prioritize setting up the WorkOS API. This will allow you to explore and integrate these features without necessarily having SSO configured from the start.
With that introduction, let’s have a closer look at each plugin.
Keep reading
Other ways to learn
Last updated
