Organizations

Organizations are groups of your users that will use your product together. These are also referred to as companies, tenants, teams, workspaces, or shared accounts. Let’s say you are building a product that helps people create and share documents internally. Your customers might include:

• A two-person startup
• A fast-growing 50-person tech company
• A hobbyist using you by themselves, but who might get more employees someday
• A large enterprise

Each of these would be an organization within your product, managed by PropelAuth.

Configuration & Settings

The following options are available on the Organization Settings page in your PropelAuth dashboard.

Changing the word "Organization"

If you use a different word for organizations (maybe team, company, tenant, workspace, group, or something domain specific), you can configure this by changing the organization meta-name in the Organization Settings page in your PropelAuth dashboard.

Changing your organization meta-name will update the word "Organization" in the hosted pages as well, such as the create org page.

Users can create their own organizations

If enabled, users have access to the 'Create Org' UI, allowing them to create their own organizations.

Disable this if you want to manually create organizations yourself, on behalf of your users.

All users must be in an organization

This setting will make sure that all users must be in at least one organization before they are allowed to use your product.

The signup/login flows will direct the user to create or join an organization.

Maximum number of orgs per user

This sets the limit on the number of organizations a user can be in at once. Most commonly, we see people setting this to either 1 (meaning each user can only be in one organization) or "as many as they want."

Creating Orgs

There are three ways to create an organization.

1. Your end users can create them themselves via the hosted pages. Just like the signup and login pages, PropelAuth provides a UI for your end users to create these organizations. Our frontend libraries provide functions for you to redirect your users to the "create org" page and to get which orgs the user is a member of.

2. You can use the PropelAuth dashboard to create organizations for your users.
3. You can use our APIs to create organizations programmatically.

Organization Domains

An optional field for each organization is the Organization Domain. If you set this field, you can limit access to the organization by only allowing users with an email address that matches the set domain.

If an organization has users from multiple domains, you can add additional domains in the Organization Domain field.

Organization Metadata

Organization Metadata is an optional JSON field that store information specific to an organization. It can be updated either via the Update Org API or in the PropelAuth Dashboard.

You can retrieve this data in several ways, such as the through the backend API, when validating an access token, or in the OrgMemberInfo class in our frontend libraries.

Adding Users to Orgs

PropelAuth provides a management UI for your users as well. This enables them to send invitations, manage roles, remove users from the organization, and more.

A user that received an invitation will be prompted to sign up if they haven't yet. Afterwards, they can accept or decline the invitation.

Your users can also allow anyone with a matching email domain to automatically join at the lowest role (e.g. everyone from @acme.com can join the Acme Organization).

We also support SAML which enables your customers to connect their organization membership directly to their identity provider (like Okta, OneLogin, or JumpCloud).

Setting a Maximum User Limit per Org

Let's say you have a pricing model that has three tiers and plans

• Hobbyist, meaning team size is max 1
• Startup, meaning team size is max 5
• Growth, meaning unlimited team size

When an organization selects a plan, you will want to set a limit based on the plan they are paying for

To do this, you will want to update the organization they are a part of programmatically. Using one of our libraries, you would use the update organization endpoint to create a maximum limit of users in the specified organization. For example, if running a Node backend, it would look something like:

 function updateOrgWithNewPricingInfo(plan, orgId) {
	if (plan === "hobby") {
		auth.updateOrg(orgId, { maxUsers: 1 })
	} else if (plan === "startup") {
		auth.updateOrg(orgId, { maxUsers: 5 })
	} else {
		auth.updateOrg(orgId, { maxUsers: 100000 })
	}
}

Connecting Orgs to a Payment System

In order to properly accomplish this kind of pricing limitation, you need a mapping from your organization to a payment system, like Stripe. If you want to do this programmatically, you can use our webhooks and listen to the org.created event.

For more information on our webhooks, be sure to check out our documentation on the subject.

Enable 2FA for Organizations

Organizations can enhance security by requiring two-factor authentication (2FA) for their members. Enabling this setting has two parts - first by enabling it globally in your PropelAuth dashboard and then enabling it per organization. Turning this setting on globally allows your organizations to enable 2FA requirements themselves by adding a setting to the hosted pages. Or, you can enable it for them via your PropelAuth dashboard.

To enable the 2FA requirement setting globally, navigate to your PropelAuth dashboard and then Organization Settings.

Once enabled globally, you can then enable Organizations require 2FA by default to automatically require 2FA for each org. Otherwise, this setting can then be enabled per individual org. Only org owners (or the top level role) can enable this by navigating to the Organizations section of their account page and clicking on Settings.

Here, they have the option to enable/disable this setting as well as a required date for when members of their org need to have 2FA enabled by. If they select Immediately, all users who do not yet have 2FA enabled will be required to set up 2FA before they can continue using your product.

If the org owner selects a grace period to allow 2FA setup, all users in their org will receive an email instructing them to enable 2FA by navigating to their account page. If they do not have 2FA setup by the time the grace period has ended, they will not be able to continue using your product until they have it setup.

You can also enable the 2FA requirement setting for individual orgs via the PropelAuth dashboard. Head over to the Organizations page, select the org where you want to require 2FA, and click on Settings. From here you can enable/disable the setting as well as when to enforce it.

Isolated Organizations

By default, users in your project can belong to multiple organizations with one single account. However, some customers may require stronger isolation guarantees than that, which is where “isolated organizations” come in.

The key difference between an isolated organization and a regular organization is that the users in an isolated organization are completely separate from the rest of your users. This means: 

• joe@acme.com can have an account in an Acme US isolated org and a completely separate account in an Acme AUS isolated org. These accounts will have different userIds.
• A user in an isolated org will only exist within that isolated org. They can’t be added to other organizations - isolated or not.
• You can still view all users - whether in isolated orgs or not - in our dashboard.

When would I need isolated orgs?

One use case where isolated orgs is important is if you have multiple organizations with overlapping users, but you need to treat the users as separate. We typically see this when users don’t have a 1:1 relationship between a customer and an organization.

Another use case is it allows you to skip some otherwise important checks in Enterprise SSO logins. PropelAuth has built-in safeguards like requiring email confirmations for users logging in outside of the organizations primary domain(s). With isolated organizations, however, none of those are necessary as the customer has complete control over their members.

Converting to an Isolated Organization

You can convert an org to isolated by navigating to the org's page in the PropelAuth Dashboard and clicking on Convert. Alternatively, you can use the Migrate Org to Isolated API.

There are a few scenarios that may require you to take action before the org is converted, such as a user belonging to additional orgs from the one you're converting. If that's the case, a list of each blocking user will appear that you can use to track which users need to be updated.

When you have unblocked all users, click on the Mark resolved button. Then, navigate back to the org and click Convert again.

Multiple User Accounts

One of the key features of Isolated Orgs is separate user accounts for each isolated organization. For example, a user with the email "example@acmeinc.com" can have different accounts for each isolated org that they belong to, as well as an account for all non-isolated orgs - all with unique user IDs and user properties.

Requirements and Restrictions

There are a few requirements and restrictions to consider before converting an organization to an isolated one:

• Members of the organization must login via Enterprise SSO. Other login methods such as email/password and magic links are not compatible.

• Org invites are not supported. Users can only be added to the organization by being provisioned in the organization's IdP (Okta, Entra, etc.)

• Internal roles are not supported.

• Members of the Isolated Org can only belong to that one org. They will not be allowed to join other organizations. However, they can create a different account with the same email address (see the section below) to join other organizations.

• Since users can now have multiple accounts with one email address, API requests such as Fetch User by Email will behave a bit differently. If an Isolated Org ID is not included in the request, only users who do not belong to an isolated org will be returned. If one is included, only users in that organization will be able to be returned. Here is a full list of our backend APIs that may require updating:

  1. Fetch User by Email
  2. Fetch User by Username
  3. Query for Users