Import users

​

The short version

# 1. What would happen? Reads the file, touches no database.
theauth migrate plan --from auth0 ./users.json --hashes ./password-hashes.ndjson

# 2. Same check against your real database, still no writes.
theauth migrate import --from auth0 ./users.json --hashes ./password-hashes.ndjson --db ./theauth.db

# 3. Write.
theauth migrate import --from auth0 ./users.json --hashes ./password-hashes.ndjson --db ./theauth.db --apply

# 4. Compare counts, and check one real login.
THEAUTH_MIGRATE_PASSWORD='the-sample-users-password' \
  theauth migrate verify --from auth0 ./users.json --db ./theauth.db --sample-email someone@yourcompany.com

​

What each source gives you

​

Auth0

• Maps: user_id, email, email_verified, name, social identities as linked accounts, user_metadata and app_metadata into metadata.
• Hashes: matched to users by email. bcrypt only.
• Gaps: Auth0 does not include hashes in the normal export. Without the support-provided file, users reset on first login.

​

Keycloak

• Maps: id, username, email, emailVerified, first and last name, federated identities as linked accounts.
• Hashes: pbkdf2-sha256, pbkdf2-sha512 and pbkdf2 (SHA-1), in both the current secretData form and the older hashedSaltedValue form. Iteration count is kept per user.
• Gaps: other credential types (OTP, WebAuthn) are not imported. A user with an unsupported password algorithm is imported without a hash and listed in the report.

​

Clerk

• Maps: id, names, username, primary email, and whether that email is in the verified list.
• Hashes: password_digest when it is bcrypt or argon2.
• Gaps: other hashers are reported as UNSUPPORTED_HASHER. Clerk’s export does not carry social connections, so users reconnect on first social sign-in.

​

Better Auth

• Maps: user fields, and non-credential accounts as linked accounts.
• Hashes: the credential account’s password column, which Better Auth stores as salt:key using scrypt (N 16384, r 16, p 1). The importer reads that layout, including the NFKC normalisation Better Auth applies to passwords.
• Check it: run migrate verify --sample-email with a real account before you trust the whole batch. The layout comes from Better Auth’s source, and a mismatch would show up there.

​

Auth.js (NextAuth)

• Maps: users, and accounts as linked accounts. Sessions are not imported, users sign in once more.
• Hashes: Auth.js has no password column. If your Credentials provider keeps a bcrypt password column on users, it is picked up.

​

Anything else (CSV or JSON)

theauth migrate plan --from generic ./users.csv --map externalId=uid,email=mail,emailVerified=verified,name=full_name,passwordHash=pw

​

From code

import { createDbMigrationStore, importUsers } from "@glinr/theauth/migrate";
import { createDatabase, createTables } from "@glinr/theauth";
import { createReadStream } from "node:fs";

const db = await createDatabase({ provider: "sqlite-native", url: "./theauth.db" });
await createTables(db, "sqlite");
const store = await createDbMigrationStore(db);

const result = await importUsers({
  source: "keycloak",
  stream: createReadStream("./realm-export.json", "utf8"),
  store,
  dryRun: true,        // the default
  onConflict: "skip",  // or "update" to adopt an existing account by email, or "fail"
});

if (result.success) {
  const { created, skipped, conflicts, errors, diff } = result.data;
}

​

Conflicts and idempotency

• A user already imported from the same source with the same id is skipped. That is what makes a re-run safe.
• A user whose email already belongs to a different account is a conflict. skip leaves it and counts it, update links the export record to the existing account, fail stops at the first one.
• Records missing an id or an email are counted as errors with a row number and no content.

​

Your own database

​

Where hashes go