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.

Best Practice

Whilst Auth0 supports numerous workflows, web based workflows using Auth0 Universal Login for sign up are considered both industry and Auth0 best practice as they provide for optimal functionality and the best security.

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 too 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.

Get Started with Auth0 Videos

Watch these two short videos Provision: Users Stores and Provision: Import Users to learn how user profiles are provisioned within an Auth0 tenant and how Auth0 allows you to move your existing users to an Auth0 user store.

Provisioning organizations

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:

    • Create a unique tenant

    • Add a database connection (if you have isolated users per organization)

    • Add an enterprise connection for this 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.

Organization Admin Portal

An organization admin portal is a portal that allows your administrators to create, modify, and remove organizations. 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.

Live Updates do come with some things to consider. There are certain operations that must be done in serial to avoid issues. Enabling clients on a connection, adding callback URL's to an Application are two examples. Any operation in the Management API where you must retrieve an entire list and re-submit the entire list with the new value added to it are operations that must be done in serial to avoid two parallel operations overwriting one of the values.

  • 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.

User migration

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.

Best Practice

Customers often opt for a two-stage approach to user migration, using Automatic Migration first to migrate as many users as possible, then using Bulk Migration for the users that remain. See User Migration Scenarios for more information.

Automatic Migration is preferred as it allows users to be migrated individually and also allows them to retain their existing password 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 migration is complete, unless passwords are stored hashed in your legacy identity store using bcrypt (or you can generate them in bcrypt form). In this case, you may be able to use bulk migration and preserve user passwords as part of the process, depending on the bcrypt algorithm and the number of salt rounds used. See Bulk Import Database Schema Examples for more information.

Best Practice

Calls to the Management API are subject to Auth0 Rate Limiting policy. You must take this into consideration, and to assist, Auth0 generally recommends use of the appropriate Auth0 SDK for your development environment rather than calling our APIs directly.

Identity store proxy

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.

Provisioning organization users

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.

Provisioning users isolated to the organization

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: This situation is a little more tricky becasue you have multiple options for approaching this situation. In descending order of complexity, these include:

    • You convince them to create (or find that they already have) one main IdP that can route to their individual IdPs.

    • You create separate organizations (e.g. customerorg-department1 and customerorg-department2) in your applications.

    • You set up a new Auth0 tenant just for them and add as many IdPs as they need (which may include a database in Auth0) to that tenant, along with their own custom domain and branding.

    • You make your existing tenant and login page more complex to handle Home Realm Discovery just for organizations that have more than one IdP

We recommend using Auth0 as an IdP as a starting point because it’s simple to implement a user invite workflow: an administrator creates a user; a randomly-generated password is created for that user, but never stored or shown to anyone; and then the user receives a welcome email with a link to set their password. 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). To learn more, see User invite.

Best Practice

If you can keep a main Auth0 tenant with a one-to-one mapping between organization and connection, it will greatly simplify your login system, making it more maintainable and extendable for the future. See Multiple Organization Architecture documents: isolated users by organization for a more in-depth view.

Provisioning users shared between organizations

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 using user app metadata. Because of this, provisioning will often be done by starting with a User Invite workflow for the single database connection, and then app metadata will be used to authorize access. User app metadata allows information to be stored in a user’s profile that can impact a user's capabilities but which a user cannot change. Let’s say I’m a doctor and I belong to Clinic A and Clinic B. I might have an organizations object in my app metadata that looks like: { “organizations”: [“clinicA”,”clinicB”] }, and then when attempting to log into the app for Clinic B, a rule can check that Clinic B is in the organizations array.

Best Practice

Because users are shared, you won’t be able to determine who has access by isolating them to their own connection, therefore you will need to use their app metadata to make the determination. When provisioning, you will need a way to set the organizations they have access to or add a new organization to an already existing user.

Deprovisioning limitations

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 a way to trigger a block or decommission of users in your system either through an API call or a UI.

User invite

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 mahy exist, and that system may then create a user in Auth0. Regardless of the audience, the technique can be similar, with the exception of the third option which would require the use of the management API and could not be done using the Delegated Administration Extension. The rest is a matter of using the right authorization model for the application.

User invite can be accomplished in a few ways:

Best Practice

Whether you are using the Management API or the Delegated Administration Extension, it is important to create each user with a random temporary password and not store that password anywhere! Then, use the Management API to send an email to the user with a link to set their password. This ensures that the only person who knows the password is the user themselves.

One of the main principles of OIDC is that no one except the user themselves ever knows their password. If you are doing an invite flow, have your backend system randomly generate a password and then discard it and have your user reset their password before ever logging in. Do not create a temporary password and give it to them to log in the first time.

Enterprise sign up

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.

best practice

A nice advantage of allowing your customers to use their own IdP is that they can administer their users and assign roles and access in their own IdP setup instead of forcing you to build administration for them. Working out the mapping for those customers will make this much easier.

If mapping isn't enough and you must put some metadata in your system, keep in mind that Auth0 will not create the user until they log in to the system the first time. Therefore, you will need to use rule extensibility to pull the initial information from somewhere else, or force users to log in the first time before you can add the metadata.

Project Planning Guide

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

B2B IAM Project Planning Guide

Multiple Organization Architecture (Multitenancy)

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