Provisioning (B2B)

Determining how users get signed up is important to address early, and the decisions you make here will influence many of the decisions you will need to make going forward. We’ve found there are a typical set of patterns for how users will get added to your system, and things to take note of when considering workflow design too.

Auth0 supports user sign up via a number of different identity providers. During sign up, Auth0 provisions the user profile so that it contains the user’s account information. There are a number of things to consider when looking at functionality and workflow:

• Does a user get added to your company's domain or do they belong to or remain in their organization's domain?

• If the user stays in their own domain, do they belong to a single organization or can they belong to multiple organizations?

• How do you provision the organization itself in your system?

• Should you use Auth0 as an identity store?

• Can you use your own (legacy) identity store with Auth0?

• How do you migrate user identities from your identity store to Auth0?

• Can your users sign up using their organization's identity provider?

• Can your users be invited or self register?

One of the first determinations to make when providing your service(s) to other businesses is identifying to which domain users belong. Based on the answer to that question, there are a couple of different approaches you can take to provision those users. See Provisioning organization users for more information. Once you know how you want organizations to be represented in your system, you will want to consider how you are going to provision the organization itself. See Provisioning organizations for more information.

Auth0 provides out-of-the-box identity storage that can be leveraged to store user credentials safely and securely. See Self Sign Up for more information. If you already have a legacy identity store and you want to offload the management of it, then the User Migration capabilities provide you with a number of options to do so.

Alternatively, if you have to maintain your legacy identity store - perhaps because you’ve got applications which you aren’t ready to migrate or which can’t be migrated - then you can use the identity store proxy capability. Allowing your customers to use “bring their own identity” is also an attractive proposition and though we find our customers don’t initially do so, you can use the Social Sign Up capability to provide it.

What you need to do when provisioning an organization will depend on how organizations are represented in your system. This can take some time to step back and consider how users of those organizations will be interacting with your applications. See Multiple Organization Architecture to determine how to configure organizations for your IAM system.

When provisioning organizations you need to consider the following:

• You will need to add the organization to your own application configuration and/or database

• You will need to make changes to your Auth0 configuration. This will include doing some or all of the following:

  • In rare cases: create a unique tenant for the organization

  • Create a new Organization in your Auth0 Tenant

  • Add a new a database connection for that Organization (if you have isolated users per organization)

  • Enable the existing shared database connection for that Organization (if you are sharing users)

  • Add an enterprise connection for this Organization and enable it on the Organization

    • This will include working with the organization to either update their existing configuration or add configuration for your Auth0 tenant if they are not a legacy organization.

  • Provision an administrator for the organization

• To avoid mistakes, you may want to create an Organization Admin Portal to make it easier to provision new organizations.

• You may also want to create a Self-Signup portal for your Organizations. This allows your customers to create the organization themselves. This can be part of the Organization Admin Portal.

An organization admin portal is a portal that allows your administrators to create, modify, and remove organizations. These administrators can either be employees of your company, or customer admins. There are multiple activities that need to be done both in your own system and your Auth0 tenant. This portal will likely need to exist in your own system so it has access to your datastores and configuration. However, Auth0 provides the Auth0 Management API so that you can incorporate changes to your Auth0 tenant at the same time that you create the changes in your own system.

There are two main approaches that can be taken for creating a new organization. The one you choose depends highly on your tolerance for how long it would take to deploy a new organization.

• Live Updates to your Auth0 Tenant: If you want to be able to create new organizations in real-time, then you will likely want to make the changes directly to your Auth0 tenant using the Auth0 Management API. This allows the changes to take place in real-time and allow the addition of a new organization to take effect immediately. Particulary if you are providing Self-Signup for organizations you may want to do this approach.

• Change the Repository and Re-deploy: If you are taking advantage of the Deploy CLI (or a custom CLI) as part of your CI/CD pipeline, you may prefer to push your changes directly to your repository and then kickoff a new deployment instead. This can take a little more time, but it has benefits associated with version history and the ability to backout a change by re-deploying the previous version. You may want to have a separate repository just for the items that the organizations need so that you don't have to re-deploy other common components and risk making an error.

In addition to hosting the User Profile, Auth0 also has the capability to both proxy your own legacy identity store and provide a secure Auth0 hosted replacement. Both of these capabilities are supported via the use of Auth0 Database Connections. If you decide to use Auth0 as a replacement for your legacy identity store then you can migrate users either all at once with bulk migration, or progressively with automatic migration.

Automatic Migration is preferred as it allows users to be migrated individually and also allows them to retain their existing passwords in almost all situations. For Bulk Migration, we recommend using the Management API over the User Import/Export extension in all but the most simple cases, as the Management API provides for greater flexibility and control.

With Bulk Migration users typically need to reset their password once the migration is complete unless passwords are stored hashed in your legacy identity store using one of the supported algorithms. In this case, you may be able to use bulk migration and preserve user passwords as part of the process, depending on the algorithm and the number of salt rounds used. See Bulk Import Database Schema Examples for more information.

Auth0 Database Connection types can also be configured to proxy an existing (legacy) identity store. If you need to keep user identities defined in your own legacy store - for example, if you have one or more business critical applications that you can’t migrate to Auth0, but which still need access to these identities - then you can easily integrate with Auth0. See Authenticate Users Using Your Database for more information.

An organization should map directly to one of your business customers/partners. Each business/partner that you are working with has users who will be logging in. We call those end users "organization users". There are two different approaches to how to store your organization users:

• Isolated to the organization: Every user belongs to exactly one organization. It would not make sense for that user to be a part of more than one organization, and even if they were, it would make sense for them to have a separate “identity” for that other organization. For example, a retail employee that works part time at two different stores has two different logins for each of those stores even if the stores both use the SaaS application. To learn more, see Provisioning users isolated to the organization.

• Shared between organizations: In a case like this, users either create credentials in your company, or they can access other organizations instances of your application using credentials from their own organization. A simple way to look at this is that one user may be authorized to access more than one organization’s instance of the application. A user would understand that they can use the same credentials to access both instances of an application. For example, some doctors contract with multiple clinics and may need to be able to sign into each separate clinic with their same credentials. To learn more, see Provisioning users shared between organizations.

Isolating users to the organization can provide a nice clean barrier between organizations. If no users ever need to access more than one organization (or you would rather force them to create multiple accounts), then this is an attractive approach.

You need to provision those users at the IdP level. Each of the organizations will have its own IdP for accomplishing this. This IdP will come in one of three flavors:

• Your Auth0 Tenant is the IdP: A Database Connection in your main tenant dedicated to this organization.

• Organizations bring their own IdP: You set up an Enterprise Connection for them.

• Organizations with more than one IdP: You enable more than one Enterprise Connection, Social Connection, and also may have a single Database Connection. When the user chooses their organization and attempts to log in, they will be able to choose from all of the connections that have been enabled for that organization.

We recommend using Auth0 as an IdP as a starting point because it’s simple to implement a user invite workflow. Compared to other invite flows, the only thing special about this is that the person who is creating the user will have to either select the organization ahead of time, or the system will force the organization to match that of the user doing the inviting (in situations where there is an organization administrator who belongs to that organization only).

When sharing users between organizations, you will need a way to authorize access. Because you won’t know where a user might belong when authenticating, we typically recommend storing your users in a single domain and then figuring out which organizations they can access by adding them as members of the organization. Because of this, provisioning will often be done by starting with a User Invite workflow for the single database connection, and then they will be added to the organization using the management API. You can then use the management API to retrieve which organizations the user belongs to if you need to provide a way for them to switch between organizations.

Auth0 will not communicate with the upstream IdP if there is an active SSO session with Auth0 unless you force it with a prompt=login. If one of your customer organizations can not manage logout for those users, they may still have access after they’ve been decommissioned. Depending on the IdP, if Auth0 gets a token for their API, you can request information about the user from the IdP in a rule to poll whether that user should still have access or not. If you don’t have this ability, you will have to provide your customer organizations with a way to trigger a block or decommission of users in your system either through an API call or a UI.

In most B2B scenarios, only particular individuals are allowed access to the application. As a result, it is often simpler to have an administrator provision user accounts rather than having users sign up and then have an administrator approve them. Provisioning can often be done in an automated fashion when users are added to a centralized system as well.

There are three different personas who might be inviting users:

• An administrator at your company may create the users for each organization.

• An administrator from each organization may be assigned to creating users.

• Another system responsible for creating users may exist, and that system may then create a user in Auth0. Regardless of the audience, the technique can be similar. The rest is a matter of using the right authorization model for the application.

The recommended approach for user invite is to use the Organizations Feature to accomplish this. If you are not using the Organizations Feature to implement user invites and are building your own, it is important to create each user with the user.email_verified parameter set to false and a random temporary password. The generated password should only be known to Auth0 and not stored in any external system nor passed to the user! Then, use the Management API to send an email to the user with a link to reset their password; you can even modify the email template in Auth0 to reflect that this is part of an invited sign-up workflow too. This ensures that the user's email address belongs to the user being created and the only person who knows the password is the user themselves.

Enterprise sign up is synonymous with sign in via enterprise login—there’s no distinction here per se, as user profile creation happens automatically upon first enterprise login.

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

Many B2B platforms implement some form of isolation and/or branding for their customers' organization, and this can add complexity to any Identity and Access Management (IAM) system. If this applies to you, then we recommend you take some time to read through our guidance and best practice advice for this type of environment.

Multiple Organization Architecture