Docs

Provisioning

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.

Provisioning organizations

best practice

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

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. See Provisioning Users Isolated to the Organization for more information. 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.
  • 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. See Provisioning Users Isolated to the Organization for more information. For example, some doctors contract with multiple clinics and may need to be able to sign into each separate clinic with their same credentials.

Provisioning users isolated to the organization

When users are isolated to the organization, this can provide a nice clean barrier between organizations. If there are never any users that 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 setup an Enterprise Connection for them.
  • Organizations with more than one IdP: This situation is a little more tricky, you have multiple options for approaching this situation, here they are in decending order of complexity:
    • You convince them to (or find that they already have) one master IdP that can route to their individual IdPs
    • You create separate Organizations (e.g. customerorg-department1 and customerorg-department2) in your applications
    • You setup a new Auth0 tenant just for them and add as many IdPs (which may include a database in Auth0) as they need 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.

Using Auth0 as an IdP is the recommended starting point as 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; the user then receives a welcome email with a link to set their password. The only thing special about this compared to other invite flows 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). See User invite for more information.

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. Since 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 through the use of 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

Since 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 instead of having users signup and then have an administrator approve them. This 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.
  • There may be another system responsible for creating users 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:
  • Using the Delegated Administration Extension
  • Updating a pre-existing user administration system that you’ve already created to use the Management API
  • Creating a new application to do this using the Management API.

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 login 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 into 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

Keep reading