Model your B2B SaaS with organizations

Modeling a multi-tenant app is an important part of your authentication and authorization architecture. If you want to be enterprise-ready, you must be able to support complex models, onboard users and orgs frictionlessly, and respond to user changes from your customer’s identity provider (IdP) in real time.

In this post, we will talk about organizations and how you can use them to support even the most complex models. We will see how you can model your org using WorkOS, enable specific enterprise features like SSO and user provisioning per org, automatically assign roles to users, and automate the provisioning and deprovisioning of users.

What is an organization?

An organization is a collection of users, but it’s also much more.

At WorkOS an organization is a top-level resource. Each connection, directory, and audit log event belongs to an organization. If you are modeling a multi-tenant SaaS app, an organization will usually represent one of your customers.

Organizations at WorkOS have different purposes depending on how you want to use them. Organizations can be used:

• To group users under specific authentication policies (e.g. force users with specific email domains to log in with SSO).
• As containers for enterprise features, like user provisioning and audit logs.
• As a workspace for collaboration.

Let's review each one in more detail.

Orgs as groups for authentication policies

Some organizations may want to enforce specific authentication methods (like SSO, MFA, etc.) for users, to meet security requirements. With WorkOS you can configure this using authentication policies at the org level.

There are two types of policies that you can configure for each org:

• Domain policies.
• Organization policies.

Domain policies

A domain policy allows you to control authentication behavior (like logging in with SSO, or using MFA) for users with specific email domains.

These domains must be verified. Once a domain is verified, all existing and future users with email addresses matching the domain will be, by default, managed by the organization’s domain policy. You can also choose if you want to automatically add users with any of these email domains as members to the org.

Domain policies are enforced for all users with email domains included in the policy, regardless of their membership status within the organization or the organization selected during sign-in. Any users provisioned through a directory with an email domain included in the organization’s domain policy, will be automatically added as active members of the organization without needing an invitation.

For example, let's say that you make the following configuration at org level:

• You associate the verified domains acme.com and acme.au with your org.
• You set SSO as the only authentication method.
• You choose to automatically add users with any of these email domains as members to the org.

With this configuration, when jon.doe@acme.com or charlotte.sander@acme.au sign in, they must use SSO and they will automatically be added as members to the org.

Organization policies

An organization policy is applied to users who sign in to the org that contains that policy.

This is particularly useful for guest members who do not have an organization email domain, or when the organization cannot include an email domain in its domain policy because the domain is managed by another organization. This way you can require, for example, that non-SSO members be enrolled in MFA to sign in to this organization, or that they use a specific SSO connection.

The important difference to remember between domain and organization policies is:

• Organization policies are enforced when a user signs into the org (because it’s their only org, or because they selected the org when signing in).
• Domain policies are enforced each time a user with a matching email domain signs in to any org.

Orgs as containers for enterprise features

At WorkOS, enterprise features like SSO, Directory Sync, and Audit Logs, are enabled and configured only at the organization level. This enables the feature for all users that are members of this org.

Orgs as workspaces for collaboration

It’s common for users to create resources in B2B applications. You can use the organization as a container for these resources, so that access to the resources depends on a user’s access to the organization. This means that when a user creates an artifact (which can be anything, a file, a folder, or a cloud resource), you can create it as a resource within the organization. As a result, when a user leaves an organization, the data remains with the organization and not the user.

Choose your org membership model

An organization contains users as members. A user may be a member of zero, one, or many organizations and is uniquely identified by their email.

Organization membership allows you to model organizations as “workspaces” and user access to them with memberships. You can have single or multiple workspaces:

• Single workspace models are for apps that have no collaboration outside a customer’s company, like an employee survey tool, where each user is in exactly one organization. Another example is Slack, which uses a single workspace model and limits SSO access per workspace.
• Multiple workspace models are for self-serve collaborative apps like Figma or Notion, where each user can be in any number of organizations, can create their own workspace and join any number of other workspaces.

When a user, who is a member of multiple organizations attempts to log in, they have to specify which organization they want to log into. When your app knows which organization the user is attempting to sign in to, you can specify the organization ID in the authorization URL. This can be useful if, for example, the user is signing in from a customer-specific subdomain or route in your application.

WorkOS also offers APIs to make it easier to change the current organization in a session. These can be used to build common UI patterns like an “Organization Switcher”.

Assign user roles using orgs

You can use organization memberships to assign roles to users. A role represents a logical grouping of permissions, defining access control levels for users within your application. For example, a role can be “Reports admin” and it can contain the privileges reports:delete and reports:edit.

Every time a user is added to an org they must be assigned a role. The default role is member. This role cannot be deleted but you can choose to create another role and set it as default.

With WorkOS user management, you can retrieve the role from the user’s organization membership object to determine their access level and capabilities within your application.

You can also reassign organization membership roles via the API.

Besides org memberships, roles can also be assigned using the following methods:

• When provisioning users with Directory Sync. You can allow IT admins to assign roles to groups during directory setup in Admin Portal. Also, using Identity Provider Role Assignment, admins can map group membership to roles in the Admin Portal during SCIM and Google Workspace directory setup. These mappings can then be used to set the role on the organization membership via Directory Provisioning.
• With SSO and Identity Provider Role Assignment. Roles are assigned to SSO user profiles through their identity provider group memberships.

Your app's authorization strategy

When it comes to authorization strategy, you need to consider your application’s needs in terms of access control. Your options are:

• Use only roles: Roles alone can be sufficient when your application only requires coarse-grained access control. This is suitable if users only need to be separated into broad categories and there is minimal overlap between roles.
• Use roles and permissions: Permissions allow for more detailed and flexible access management. When you use permissions, you don’t need to maintain manual logic for each role, your app should only care about what permissions a user has. You can use permissions with AuthKit and configure them in the WorkOS dashboard. They are particularly useful when:some text
  • You need to frequently modify access rights or introduce new roles.
  • There is significant overlap in access rights between different roles but with some variations.
  • You want to minimize code changes when modifying access rights. By abstracting access control checks to permissions, you can add or modify roles and their access rights without changing the application code.
• Use Fine-grained authorization (FGA): If you are dealing with even more complex access control scenarios, you should use Fine-grained authorization (FGA). FGA is an advanced access control model that considers several factors to decide whether a user should have access to a resource. These factors may include a user’s role, seniority, location, or the time of day. This allows you to tailor each user's access to the resources they need and thus tighten security.

Model your org with WorkOS

Once you know how you want to model your org(s), you can do it in the dashboard or using the API.

Using the dashboard

To model your org using the dashboard, go to dashboard > Organizations and click Create Organization. You have to enter a name for the org, and optionally, one or more domains. Users signing in with SSO with a verified domain are automatically considered verified and do not need to complete the email verification process. Only add domains that you trust are owned by this organization.

Domain verification can be delegated to the Admin Portal domain verification flow. This out-of-the-box UI guides the IT admin to add a DNS TXT record to prove domain ownership. Once the DNS TXT record is correctly added, the organization domain is automatically verified.

After you create the org you will be navigated to the org details screen where you can:

• Invite an admin to set up this organization using the Admin Portal.
• Configure SSO (invite an admin to set it up in the Admin Portal, or configure the connection manually)
• Configure domain and organization policies.
• Set up Directory Sync (or have an admin do it).
• Set up Just-in-time Provisioning (JIT).
• Configure log streams to stream audit logs directly to your customer's Security Incident and Event Management (SIEM) providers like Datadog or Splunk and object storage solutions like AWS S3 or Google Cloud Storage. You can also invite your customer's admin to set it up using the Admin Portal.
• And more.

Using the API

If you prefer to create your org(s) programmatically you can use the WorkOS Organization API.

To create an organization (for example, the same one you can see in the dashboard screenshot of the previous section) with Node, run the following:

	
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('WORKOS_API_KEY');

const organization = await workos.organizations.createOrganization({
  name: 'Doodle Inc',
  domainData: [
    {
      domain: 'doodle.com',
      state: 'verified',
    },
  ],
});
	

If you retrieve the org you just created, it will look like this:

	
{
  "id": "org_01JA9EEM2SZQAS3MFF09PYKTYC",
  "object": "organization",
  "name": "Doodle Inc",
  "created_at": "2024-10-15T19:07:33.155Z",
  "updated_at": "2024-10-15T19:07:33.155Z",
  "domains": [
    {
      "domain": "doodle.com",
      "id": "org_domain_01EHZNS0H9W90A90FV79GAB6AB",
      "object": "organization_domain"
    }
  ]
}
	

Keep in mind to always check our API docs for the latest up-to-date code snippets in a variety of languages. There you can find more endpoints to manage orgs.

Add members to your org

Once you have an org in place you need to start adding members to it. There are several ways to do this with WorkOS, and we already mentioned some of them. In this section we will review the available options.

Using the dashboard

Users can be added to organizations manually using the dashboard. Select the org, go to the Users tab and click Add User. If the user does not exist, they will have to be created in the dashboard > Users tab.

Using directory provisioning

You can provision users and memberships using Directory Sync, a set of developer-friendly APIs and IT admin tools that allows you to implement enterprise-grade User Lifecycle Management (ULM) into your app.

Directories can be set up via the dashboard with setup links. You can also integrate the Admin Portal with your app to generate links to configure directories.

WorkOS supports the following providers:

• Okta SCIM
• Entra ID (Azure AD) SCIM
• Google Workspace
• OneLogin SCIM
• CyberArk SCIM
• PingFederate SCIM
• JumpCloud SCIM
• Rippling SCIM
• Generic SCIM
• SFTP

If you need directory provisioning support from a provider not listed above, please reach out to support@workos.com.

Using Just-in-time provisioning (JIT)

JIT provisioning automatically creates users and organization memberships when a user signs in for the first time. WorkOS detects when their email domain matches a verified domain of an organization and prompts the user to sign in through the organization’s identity provider (IdP). This user is then automatically created and added as a member of the organization.

Users with verified email domains can be automatically added as members of an organization through the organization’s domain policy. This feature is useful when an application or organization wants to automatically group individuals into the same workspace based on their email domain and can help onboard teammates quickly.

If you want to JIT-provision guests whose email domain has not been verified by the organization, e.g. so you gate all contractor access through your IdP, you must first invite the guests to join the organization before they can sign in with the organization’s IdP. Guests can also be JIT-provisioned via IdP-initiated SSO.

You can configure JIT in the dashboard, per organization.

Using domain policies

As we saw earlier, you can automatically add people with a company email address (like @doodle.com) to your organization, using a domain policy. This helps all your employees join the right organization and avoid accidentally working in silos. Automatic membership by domain is also useful when your org is not using SSO and cannot rely on SSO JIT provisioning.

For example, let’s say that Doodle Inc. has three domains registered to their organization: doodle.com, doodlecorp.org, and dev.doodle.org. With a domain policy configured, anyone with an email address from those domains will join the Doodle Inc. organization as a member. Anyone with an email address that doesn't match those domains (like name@gmail.com or name@otherdomain.com) can get invited to the organization as a guest. Domain capture wouldn’t be a good fit for Doodle Inc. if they wanted to create multiple organizations with members from the same email domains.

To enable a domain policy you need to verify the domain(s) and configure the domain policy in the dashboard.

Using invitations

Users can also invite individuals to organizations, regardless of their email domain. This is handy for contractors within a company, or a collection of people without a shared domain.

Each invitation is for a specific email address. Invitations are for both new users and existing users.

• New users: If an invitation is created for an email address that does not yet exist, an email is sent to that user with a link to sign up for your application and join the organization. As part of signing up, they automatically join the organization. If a user is invited to multiple organizations, they only join the organization for which they clicked the invitation email indicating intent to join that specific organization.
• Existing users: If an invitation is for an existing user, clicking the link in the email and signing in adds the user as a member of the organization. If the user is already signed in, you can use the invitation code to validate that the signed-in user is eligible to use the invitation, by querying the Invitation API.

Invitations do not have to be specific to an organization. An invitation sent without specifying an organization is an invitation to join the application.

Invitations can be sent programmatically by your application with the Invitation API, or viewed and manually created in the dashboard.

By default, WorkOS sends these emails, but you can also send the emails yourself.

Invite users provisioned through a directory

When you provision users from a directory, those with an email domain matching a verified organization domain will be automatically added as members of the organization, without needing an invitation.

Other users will be created with pending memberships and receive an email invitation to join the organization. Those users won’t be able to sign in until the invitation is accepted, at which point they become active organization members.

Model your app as a closed-registration invitation-only system

You can choose to model your application as a closed-registration invitation-only system. When signup is disabled, users cannot register for a new account but if they have a valid invitation code, registration is opened up both in AuthKit and the API so that a new user may sign up.

Move users between orgs

If a user is not part of your company at first (for example, a contractor), but is then hired and you want to add them to your org, you can invite them to their new org. If the two orgs used different authentication methods, then as long as the user keeps using the same email, WorkOS will identify the duplication and resolve it by linking these identities under the same user, as identified by the email address. This will not automatically remove the user from the old org though, you would have to do that manually.

Remove members from your org

When it comes to removing users from an org, there are two models that your app can use:

• Soft-delete: preferred in cases where a member retains some data after leaving the organization (e.g. messages, documents, or other data). It provides the option to reactivate these memberships.
• Hard-delete: preferred if the app has no need to “remember” the membership (e.g. when members operate solely on customer data and have no data of their own).

Deactivate and reactivate org members

If you use a soft-delete model, you can utilize the organization membership lifecycle. Organization memberships have three possible statuses:

• pending: when a user is invited to an organization
• active: when a user is added as an organization member or accepts an invitation
• inactive: when an organization membership is deactivated

You can soft-delete users using the deactivation API. Deactivating an organization membership sets its status to inactive and revokes all active sessions. Note that pending memberships cannot be deactivated and should be deleted using the delete membership API instead.

If you want to reactivate a soft-deleted org membership, you can use the reactivation API. Reactivating an organization membership sets its status to active and retains the role attached to the organization membership prior to deactivation. This role can be updated using the update organization membership API.

Note that pending memberships cannot be reactivated. For this the user should go through the invitation acceptance flow instead. If invitations are not needed, the organization membership can be created as active directly.

Delete org members

You can hard-delete organization memberships using the deletion API. This is an option for users who should no longer have access to an organization.

You can also deactivate or delete members from organizations, using the dashboard.

Sync org membership changes from directories

If you use Directory Sync, you can automate the process of provisioning and deprovisioning users, and respond to any changes as soon as they are sent from the IdP to WorkOS.

WorkOS supports dozens of integrations, including SCIM. Directory updates are delivered to you via webhooks, or retrieved by your app using the events API:

• With the events API, your application retrieves events from WorkOS. The events API offers a more robust data synchronization solution compared to webhooks, ensuring seamless synchronization of your system state with WorkOS.
• With webhooks, WorkOS automatically notifies your app when an event occurs by invoking an endpoint hosted within your application.

Your app stores a mapping between your customer and their directory. This allows you to maintain your app in sync with the directory provider used by your customer.

Conclusion

In this post, we talked about organizations, a top-level resource in WorkOS, and how you can use them to model complex multi-tenant apps.

We saw how you can set up policies to enforce authentication methods and automatically add users to orgs, enable specific features per org, and use Directory Sync or JIT to automate the provisioning and deprovisioning of users. We also went through all the available ways to manage org memberships, either using the API or tools like Directory Sync.

‍Sign up today to model your app with WorkOS and make sure that you can support complex models while keeping up with industry best practices.