Modeling Your App

WorkOS has a wide suite of products to solve your business needs. This guide explains some of the common choices when it comes to modeling your integration.

WorkOS is designed to support a wide array of use cases and architectural scenarios, from simple business-to-consumer (B2C) user authentication to complex business-to-business (B2B) architectures with multiple organizations and authentication policy enforcement.

Features are designed to grow with you, allowing you get started easily and expand your security options as you onboard larger and larger enterprise customers.

Whether you are looking to add the initial authentication piece to a new application, or exploring migration from an existing vendor, you may find yourself asking:

In most cases the answer is yes, and the aim of this guide is to help you understand how. We’ll cover the terminology used in this space, describe some common B2C and B2B flows, and finally demonstrate some scenarios that explain how everything fits together.

Supporting Email + Password, Single Sign-On, OAuth, Magic Auth, and other authentication concerns on your own is a complex task. You’d need to understand the authentication process, as well as model your applications sign-in and signup user interfaces to account for and handle all possible routes, error states and edges cases.

There are three main ways to add WorkOS authentication to your application:

A hosted login solution that provides a customizable UI and supports a wide range of authentication methods.

If you prefer to craft your own UI in your own stack, AuthKit can be integrated with the User Management API.

For applications that are only interested in SSO capabilities.

In the majority of cases we recommend using the hosted AuthKit solution.

On successful completion, AuthKit will return an authentication code to your application via your specified redirect URI, this is exchanged for the user object and used to create a session.

See the Quick Start guide for more information on how to implement this.

Prior to building your integration, it is useful to think about which authentication methods are part of your requirements. Typical consumer authentication methods include the following:

The most common method of authentication, users sign up or sign in to your app with email and password. This method is enabled by default.

OAuth, also known as Social Login, is when a user logs in with an account belonging to a different service. Examples include logging in with your Google, Microsoft or GitHub account instead of making a new account with your app. These authentication methods can be configured from the WorkOS dashboard.

Also known as Passwordless, Magic Auth authentication works by emailing the user a unique, one-time-use 6 digit code which they then use to authenticate.

A similar technique is Magic Link, where the user can log in by clicking a link emailed to them. This method has proven to be unreliable as IT teams often employ security measures that scan user emails and programmatically click any links found in the email, invalidating the Magic Links. As such, WorkOS has deprecated Magic Links in favour of Magic Auth.

The favored authentication method by enterprise sized companies, SSO allows an organization’s users to sign in with a single ID to related, yet independent software systems.

The WorkOS User Management APIs make the above easy to implement using your own UI, or you can use AuthKit for a fully hosted experience.

You might encounter the concepts of single-tenant and multi-tenant when discussing an application’s authentication model. Single-tenant and multi-tenant architectures offer different approaches to managing resources and data in software applications, especially in cloud services or Software as a Service (SaaS) environments.

In the context of authentication and authorization, single-tenant refers to a software architecture where a separate instance of the software is set up for each client on separate servers or virtual machines.

Each organization is paired with its own instance of both the application and the underlying database. This approach offers full data isolation between customers, but comes at the cost of being more resource-intensive and costly. Each client’s setup may require separate maintenance, updates, and support.

Multi-tenant refers to a software architecture where a single instance of the software serves multiple customer organizations, known as tenants.

Each tenant’s data is isolated and remains invisible to other tenants because the software is designed to securely handle this data across all tenants.

In the context of WorkOS, a multi-tenant application could be accomplished by the use of Organizations and Organization Memberships to ensure that end-users only have access to the data they are authorized to.

By default WorkOS comes with two environments: staging and production. The former is for development and testing, the latter for live traffic. For single-tenant applications, new environments can be added to your WorkOS account to accommodate each of your users. For more information or to request new environments, please reach out to support.

In a simple B2C model, all users belong to the application, users do not require assignment or management by an organization in order to perform actions or access resources. In this model your customer is also the end-user, they sign up or sign in to your app in order to use your services without being associated with an organization.

It’s common to have a single users table in your database linking to the WorkOS user (among other services), you may optionally decide to use WorkOS as the source of truth for other user information such as firstName, lastName or email, though this depends on your application requirements.

In this model, WorkOS’s primary role is to authenticate users and store them in a simple, flat structure. This is the default model and is the simplest to implement, but as your needs grow you may find yourself needing to add additional functionality.

In contrast to the B2C example, a typical B2B model introduces the concept of Organizations.

Organizations relate a set of users and provide a structure to manage and enforce authentication methods and resource access. We can extend our previous diagram to introduce this concept.

In this model, we have a one-to-many relationship between users and organizations, a user can belong to many organizations and an organization can have many users, this relationship is expressed by our Organization Membership table. Unlike the B2C example, the customer here is a (usually enterprise) company that has its own users, typically employees or contractors.

While you can still use all the authentication methods outlined above with B2C models, the main difference between B2C and B2B is that the latter tends to prefer SSO as its authentication method of choice.

This model starts to become incredibly powerful as we can now capture more complex scenarios. For example, we could leverage features such as domain verification and domain policies to control authentication behavior and provision members automatically.

Domain verification is the process of proving ownership of a specific domain, typically handled by a company’s IT department. Once a domain is verified, all existing and future users with email addresses matching the domain are, by default, managed by the organization’s domain policy. This allows the organization to control authentication and membership behavior for these users, such as requiring these users to authenticate via SSO.

Users signing in with SSO with a verified email domain are automatically considered verified and do not need to complete the email verification process.

When onboarding a new enterprise customer, they will likely ask to integrate their SSO connection provided by their own Identity Provider (IdP) with your application.

The Admin Portal provided by WorkOS makes this process easy to implement by providing a hosted UI that guides your user through SSO configuration.

With the Admin Portal, the process of configuring your customer’s SSO integration is reduced to creating an Organization in WorkOS, saving relevant data in your own database and then redirecting the user to the Admin Portal to guide them through the configuration flow.

As with B2C models, user data on the WorkOS side can be used as the source of truth, but the far more common scenario is to store user information in your own database which links to the WorkOS user.

The WorkOS User Management and SSO products can be used independently, with the latter acting as authentication middleware which intentionally does not handle user database management for your application. If you’re unsure which is best for your business, it’s recommended to stick with User Management as it gives you the aforementioned flexibility to add and/or remove features as your needs grow.

As your application grows you may find yourself needing to add additional features to support customer needs. WorkOS User Management is designed with this is mind. As you move upmarket and take on larger and larger customers, you can easily adopt and extend your feature set within an established architecture. The following scenarios explain some common use cases with specific feature sets.