Custom Database Connection Anatomy Best Practices
You typically use a custom database connection to provide access to your own legacy identity store for authentication (sometimes referred to as legacy authentication) or perform user import through automatic migration (often referred to as trickle or lazy migration). You can also use custom database connections to proxy access to an Auth0 tenant in scenarios where you use Auth0 multi-tenant architecture. To learn more, read Multi-Tenant Applications Best Practices.
You typically create and configure custom database connections using the Auth0 Dashboard. You create a database connection and then toggle Use my own database to enable editing of the database action scripts. A custom database connection can also be created and configured with the Auth0 Management API Create a connection endpoint and the auth0 strategy.
As shown below, you use custom database connections as part of a login workflow to obtain user identity information from your own legacy identity store for authentication or user import.
In addition to artifacts common for all database connection types, a custom database connection allows you to configure action scripts—custom code used when interfacing with legacy identity stores. The scripts you choose to configure depend on whether you are creating a connection for legacy authentication or for automatic migration.
Action scripts can be implemented as anonymous functions; however, anonymous functions make it hard to debug when it comes to interpreting the call-stack generated as a result of any exceptional error conditions. For convenience, we recommend providing a function name for each action script. To see some recommended names, read Custom Database Action Script Execution Best Practices.
In a legacy authentication scenario, no new user record is created; the user remains in the legacy identity store and Auth0 uses the identity it contains when authenticating the user. Custom database connections are also used outside of the Universal Login workflow. For example, a connection's changePassword action script is called when a password change operation occurs for a user that resides in a legacy identity store.
Automatic migration
During automatic migration, Auth0 creates a new user in an identity store (database) managed by Auth0. Auth0 uses the identity in the Auth0-managed identity store when authenticating the user. For this to occur, Auth0 first requires the user to be authenticated against the legacy identity store, and only if this succeeds will the new user be created in the Auth0 managed database. Auth0 creates the new user using the same ID and password that was supplied during authentication.
User creation in an automatic migration scenario typically occurs after the Login action script completes. We recommend that you do not attempt to delete users from a legacy identity store as an inline operation within the Login script, but instead as an independent process. This prevents accidental user deletion should an error condition occur during migration.
With automatic migration, users remain in the legacy identity store and can be deleted or archived if required. A side-effect can occur where a user is deleted from Auth0 but remains in the legacy data store. In this case, a login made by the deleted user could result in either the Login or Get User script executing and the user again migrating from the legacy identity store.
We recommend marking legacy store user identities as migrated before either Login or Get User scripts complete and prior to any eventual legacy store deletion to prevent the unintentional recreation of intentionally-deleted users.
Size
We recommend that the total size of any action script not exceed 100 KB. The larger the size, the more latency is introduced due to the packaging and transport process employed by the Auth0 platform, and this will have an impact on the performance of your system. Note that the 100 KB limit does not include any npm modules that may be referenced as part of any require statements.