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
While 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 ?
- Can your users be invited or self register?
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:
- 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.
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 . 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.
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 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.Importing hashed passwords relies on the source identity store using idiomatic implementations of one of the following algorithms: argon2, bcrypt, hmac, ldap, md4, md5, sha1, sha256, sha512, pbkdf2, and scrypt.
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: 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.
Best Practice
If you can utilize the Organizations Feature, it will greatly simplify your login system, making it more maintainable and extendable for the future. See Multiple Organization Architecture 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 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.Deprovisioning limitations
Auth0 will not communicate with the upstream IdP if there is an active session with Auth0 unless you force it with aprompt=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.
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 may exist, and that system may then create a user in Auth0. Regardless of the , the technique can be similar. The rest is a matter of using the right authorization model for the application.
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.
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.