If you are currently using NextAuth.js, this guide will help you migrate to Nile Auth. Migrating production applications from one auth provider to another is a non-trivial task, and we recommend you do thorough testing. Before you begin, you’ll need a Nile account. If you don’t have one, you can sign up here. You should also review the Nile Auth documentation and validate that Nile Auth meets your application requirements (That we support the providers you need, for instance). If you notice any features missing, please let us know!

​
Migration Steps

NextAuth.js is an authentication library, rather than a service. This means that your users, sessions and accounts are stored in a database. If your existing database is PostgreSQL, you can use Nile Auth with the same database and this document will guide you through the migration. Otherwise, you’ll need to migrate your data to PostgreSQL. Data migrations to PostgreSQL are not covered is beyond the scope of this guide, but you can reach out to us for help.
1

Migrating NextAuth data to Nile Auth

You can see the schema of the auth tables in Nile Auth in our built-in tables documentation. If you are using the standard Postgres adapter for NextAuth.js, your schema is documented here. This schema is the same for NextAuth versions 3, 4 and 5 (also called Auth.js).As you can see, there are quite a few similarities between the two schemas. Making the migration relatively straightforward.First, if you are not using Nile, you’ll need to create the tables as documented.Assuming you have these tables, either built into Nile or created by yourself, you’ll need to migrate the data from the NextAuth.js tables to the Nile Auth tables. In the example queries below, I’m assuming that the NextAuth.js tables are in the nextauth schema. Modify the queries below to match your schema.
If you don’t mind users re-authenticating, you don’t need to migrate the sessions and verification_tokens tables.
Users tableNile Auth uses uuid type for the id column, while NextAuth.js uses serial type (which is actually an integer). Since there is no automatic conversion between these types, we recommend adding a new column to store the NextAuth.js user id, allowing you to keep existing references to these IDs intact.
ALTER TABLE auth.users ADD COLUMN nextauth_id integer;
To copy the data from the NextAuth.js users table to the Nile Auth users table, you can use the following query:
insert into users.users (email, name, email_verified, image, nextauth_id)
select email, name, email_verified, image, id as nextauth_id
from nextauth.users;
Sessions tableThe sessions table in Nile Auth is almost identical to the one in NextAuth.js. We just need to convert the user IDs to be Nile Auth user IDs instead of NextAuth.js user IDs.
insert into auth.sessions (session_token, user_id, expires_at)
select s.session_token, u.id as user_id, s.expires_at
from nextauth.sessions s
join users.users u on u.nextauth_id = s.user_id;
Verification Tokens tableThe verification tokens table in Nile Auth is identical to the one in NextAuth.js. No changes are needed.
insert into auth.verification_tokens (identifier, token, expires)
select identifier, token, expires
from nextauth.verification_tokens;
Accounts / Credentials tableNile Auth uses the auth.credentials table to store account information instead of the accounts table. The query below will migrate the data from the accounts table to the credentials table.
insert into auth.credentials (
    user_id,
    method,
    provider,
    provider_account,
    payload
)
select 
    u.id as user_id,
    'oidc'::authentication_method as method, -- all NextAuth.js accounts are oidc
    a.provider,
    a."providerAccountId" as provider_account,
    jsonb_build_object(
        'refresh_token', a.refresh_token,
        'access_token', a.access_token,
        'expires_at', a.expires_at,
        'id_token', a.id_token,
        'scope', a.scope,
        'session_state', a.session_state,
        'token_type', a.token_type,
        'type', a.type
    ) as payload
from nextauth.accounts a
join users.users u on u.nextauth_id = a."userId";
2

Linking users to tenants

Nile Auth is a multi-tenant authentication service. By linking users to tenants, you can control their access to resources in your application and use Nile Auth organization components in your application.This section assumes that you are already using Nile as your database, your tenants exist in tenants table, and your data is in tenant-aware tables with tenant isolation. Migrating data from existing database into Nile’s virtual tenant databases is out of scope for this guide, but you can reach out to us for help.In order to link users to tenants, you’ll need to populate the users.user_tenants table with the relationships between users and tenants. You’ll need to convert the current mapping of NextAuth.js users to tenants to the new Nile Auth user_tenants table.For example, if you have a memberships table with this mapping, you can use the following query to migrate the data:
insert into users.user_tenants (user_id, tenant_id)
select u.id as user_id, m.tenant_id as tenant_id
from memberships m
join users.users u on u.nextauth_id = m.user_id;
3

Social Providers

If you used social identity providers with , you will need to configure the same providers in Nile Auth.You can configure social providers by going to “Tenants and Users” page in Nile Console and selecting the “Providers” tab.Simply click on the provider you want to configure and you’ll see the provider configuration page. All providers use OAuth, so you’ll need to provide the OAuth client ID and secret. It is recommended to use the same client ID and secret as the one used in . And to use the same redirect URI in the social provider configuration.Social providersYou can see more details on how to configure and use each provider in the Single Sign-On section of the documentation.
4

Passwordless Authentication

If you used NextAuth.js passwordless authentication, you’ll need to configure your SMTP server and email templates in Nile Auth. Refer to the email configuration guide to learn how to do this.
5

Application Migration

In addition to the data migration, you’ll need to update your application to use Nile Auth.Refer to the NextJS guide to learn how to set up Nile Auth environment variables and routes in your application. These will replace the NextAuth.js routes in your application.NileAuth routes are purely backend and do not serve any frontend content. This means that you’ll need to create login/signup pages in your application with Nile’s customizable components. The NextJS guide above has examples of how to do this.
Note that unlike NextAuth.js, you don’t configure social providers and passwordless authentication in the application
  • you already configured them in the Social Providers and Passwordless Authentication steps above.

​
Testing

We recommend you do thorough testing in a staging environment before migrating to production. Before starting a migration, both in staging and in production, we recommend you create a few test users and organizations in your existing auth provider. Make sure you have a mix of email/password, passwordless and social providers users. Then, after migrating to Nile Auth, test the following (both in test and in production):
  • Sign up and sign in with email/password, passwordless and social providers.
  • Sign in with email/password, passwordless and social providers.
  • Sign out
  • Reset password
  • Email verification
  • Validate that the users have access to the correct organizations.
It is also important to test negative flows. For example, trying to sign in with an invalid password, or an invalid email/password combination. You want to be sure that unauthorized users are not able to sign in. Finally, use the “Tenant and Users” page in Nile Console to verify that the all the expected user data and metadata was migrated, and that the users have access to the correct organizations.

​
Best Practices

Here are some recommended practices for a smooth migration from Auth0 to Nile Auth:
  1. Staged Migration: Consider migrating users in batches rather than all at once. Start with a small subset of non-critical users or test accounts. Monitor for issues and gather feedback before proceeding with larger groups. This will allow you to test the migration and make sure it works as expected before migrating all users. The “fallback strategy” described in the migration steps can be used to support both Auth0 and Nile Auth during the migration.
  2. Communication Plan: Notify users well in advance of the migration. Provide clear instructions for any actions they n eed to take (like password resets). Set up support channels for users who encounter issues during the transition.
  3. Backup and Rollback Plan: Keep backups of all Auth0 data before starting the migration. Maintain the Auth0 configuration until the migration is complete and verified. Have a clear rollback plan in case of critical issues.
  4. Monitoring and Validation: Set up monitoring for authentication failures during and after migration. Implement logging to track successful and failed migrations. Validate user counts and access permissions after migration.