Migrate from Auth0

{"user_id":"auth0|65f1c2","email":"ada@acme.com","email_verified":true,"name":"Ada Lovelace","connection":"Username-Password-Authentication","identities":[{"connection":"Username-Password-Authentication","user_id":"65f1c2"}],"roles":["Admin"]}
{"user_id":"google-oauth2|1098765","email":"grace@acme.com","email_verified":true,"name":"Grace Hopper","connection":"google-oauth2","identities":[{"connection":"google-oauth2","user_id":"1098765"}],"roles":["Member"]}

import { betterIam } from 'better-iam';
import { postgresAdapter } from 'better-iam/adapter-postgres';
import { sendEmail } from './mail';

export const iam = betterIam({
  database: postgresAdapter({ connectionString: process.env.DATABASE_URL! }),
  secret: process.env.BETTER_IAM_SECRET!,
  baseURL: process.env.BETTER_IAM_BASE_URL!,
  authentication: {
    sendEmail,
    passwordlessEmail: true,
  },
  permissions: {
    identityAttributes: { auth0Id: 'string' },
    resourceTypes: {
      // One entry per Auth0 API, with its permissions as actions.
      invoice: { actions: ['invoices:read', 'invoices:create', 'invoices:approve'] },
    },
  },
});

npx better-iam migrate --config better-iam.config.mjs
npx better-iam store-export --config better-iam.config.mjs --output before-auth0-import.jsonl

import { readFile, writeFile } from 'node:fs/promises';
import { iam } from '../iam';

type Auth0Organization = { id: string; name: string; display_name?: string; ownerEmail: string };

const credential = { token: process.env.BETTER_IAM_TOKEN! };
const rootTenantId = process.env.ROOT_TENANT_ID!;

const organizations = JSON.parse(await readFile('auth0/organizations.json', 'utf8')) as Auth0Organization[];
const tenantMap: Record<string, string> = {};

for (const organization of organizations) {
  const { tenant } = await iam.api.tenants.create(credential, {
    parentId: rootTenantId,
    type: 'organization',
    name: organization.display_name ?? organization.name,
    ownerEmail: organization.ownerEmail,
    activate: true, // active now; the owner's account is created without an invitation
  });
  tenantMap[organization.id] = tenant.id;
  console.log(`${organization.name}: tenant ${tenant.id}, owner ${organization.ownerEmail}`);
}

await writeFile('auth0/tenant-map.json', JSON.stringify(tenantMap, null, 2));

npx tsx scripts/auth0-create-tenants.ts

import { readFile } from 'node:fs/promises';
import { iam } from '../iam';

type Auth0Role = { name: string; permissions: string[] };

// Auth0 permission name -> Better IAM action (your renames from the configure step).
const actionFor: Record<string, string> = {
  'read:invoices': 'invoices:read',
  'create:invoices': 'invoices:create',
  'approve:invoices': 'invoices:approve',
};

const credential = { token: process.env.BETTER_IAM_TOKEN! };

export async function applyAuth0Roles(tenantId: string): Promise<void> {
  const roles = JSON.parse(await readFile('auth0/roles.json', 'utf8')) as Auth0Role[];
  const document = {
    version: 1,
    roles: roles.map((role) => {
      const permissions = role.permissions.map((permission) => {
        const action = actionFor[permission];
        if (!action) throw new Error(`No action mapped for Auth0 permission ${permission}`);
        return action;
      });
      // A permissions list must name at least one action; a role without any grants nothing yet.
      return permissions.length ? { name: role.name, permissions } : { name: role.name };
    }),
  };
  const plan = await iam.api.config.plan(credential, { tenantId, config: document });
  console.log(tenantId, plan.summary);
  await iam.api.config.apply(credential, { tenantId, config: document });
}

import { createReadStream } from 'node:fs';
import { readFile, writeFile } from 'node:fs/promises';
import { createInterface } from 'node:readline';
import { iam } from '../iam';
import { saml } from '../saml';
import { applyAuth0Roles } from './auth0-roles';

type Auth0Member = {
  user_id: string;
  email?: string;
  email_verified?: boolean;
  name?: string;
  connection: string;
  identities?: Array<{ connection: string; user_id: string | number }>;
  roles: string[];
};
type Link = { providerId: string; issuer: string };

// Your Auth0 connection names.
const DATABASE_CONNECTIONS = new Set(['Username-Password-Authentication', 'email']);
const DIRECTORY_CONNECTIONS = new Set(['acme-okta']); // the customer's SCIM directory creates these people

// Auth0 connection name -> the OAuth connection that replaces it, per Auth0 Organization (see the next steps).
// providerId is the connection's id; issuer is the provider's `iss`, exactly.
const OAUTH_CONNECTIONS: Record<string, Record<string, Link>> = {
  org_acme: {
    'google-oauth2': { providerId: 'acme-google', issuer: 'https://accounts.google.com' },
  },
  org_globex: {
    'globex-okta': { providerId: 'globex-okta', issuer: 'https://globex.okta.com' },
  },
};

const credential = { token: process.env.BETTER_IAM_TOKEN! };

/** The tenant's link targets: its OAuth connections, plus each SAML connection under the Auth0 connection's name. */
async function linkTargets(auth0OrgId: string, tenantId: string): Promise<Map<string, Link>> {
  const targets = new Map(Object.entries(OAUTH_CONNECTIONS[auth0OrgId] ?? {}));
  for (const connection of await saml.listConnections(credential, { tenantId }))
    targets.set(connection.id, { providerId: connection.providerId, issuer: connection.idpIssuer });
  return targets;
}

async function readMembers(path: string): Promise<Auth0Member[]> {
  const members: Auth0Member[] = [];
  const lines = createInterface({ input: createReadStream(path), crlfDelay: Infinity });
  for await (const line of lines) if (line.trim()) members.push(JSON.parse(line) as Auth0Member);
  return members;
}

async function existingEmails(tenantId: string): Promise<Set<string>> {
  const emails = new Set<string>();
  for (let offset = 0; ; offset += 1000) {
    const page = await iam.api.identities.list(credential, { tenantId, kind: 'user', limit: 1000, offset });
    for (const identity of page) if (identity.email) emails.add(identity.email);
    if (page.length < 1000) return emails;
  }
}

async function importOrganization(auth0OrgId: string, tenantId: string): Promise<void> {
  await applyAuth0Roles(tenantId);
  const roleIds = new Map((await iam.api.roles.list(credential, { tenantId })).map((role) => [role.name, role.id]));
  const targets = await linkTargets(auth0OrgId, tenantId);
  const seen = await existingEmails(tenantId);
  const members = await readMembers(`auth0/members-${auth0OrgId}.ndjson`);

  const toImport: Array<{ member: Auth0Member; providers: Array<Link & { subject: string }> }> = [];
  let waiting = 0;
  for (const member of members) {
    if (!member.email) continue; // Better IAM needs an email address
    const email = member.email.trim().toLowerCase();
    if (seen.has(email)) continue; // already imported, or the tenant's owner
    if (DIRECTORY_CONNECTIONS.has(member.connection)) continue; // the directory creates them
    if (!DATABASE_CONNECTIONS.has(member.connection) && !targets.has(member.connection)) {
      waiting++; // their connection is not recreated in this tenant yet: a later run imports them
      continue;
    }
    // Every Auth0 identity with a Better IAM connection becomes a link (one per connection).
    const providers = new Map<string, Link & { subject: string }>();
    for (const identity of member.identities ?? []) {
      const target = targets.get(identity.connection);
      if (target) providers.set(target.providerId, { ...target, subject: String(identity.user_id) });
    }
    seen.add(email);
    toImport.push({ member, providers: [...providers.values()] });
  }

  const idMapPath = `auth0/id-map-${auth0OrgId}.json`;
  const idMap: Record<string, string> = JSON.parse(await readFile(idMapPath, 'utf8').catch(() => '{}'));
  for (let start = 0; start < toImport.length; start += 100) {
    const batch = toImport.slice(start, start + 100);
    const { identities } = await iam.api.identities.createMany(credential, {
      tenantId,
      identities: batch.map(({ member, providers }) => ({
        email: member.email!,
        name: member.name || member.email!,
        emailVerified: member.email_verified === true,
        providers,
        attributes: { auth0Id: member.user_id },
        roleIds: member.roles.flatMap((name) => roleIds.get(name) ?? []),
      })),
    });
    batch.forEach(({ member }, i) => (idMap[member.user_id] = identities[i]!.id));
  }

  await writeFile(idMapPath, JSON.stringify(idMap, null, 2));
  console.log(`${auth0OrgId}: imported ${toImport.length}, ${waiting} wait for their connection`);
}

const tenantMap = JSON.parse(await readFile('auth0/tenant-map.json', 'utf8')) as Record<string, string>;
for (const [auth0OrgId, tenantId] of Object.entries(tenantMap)) await importOrganization(auth0OrgId, tenantId);

npx tsx scripts/auth0-import-members.ts

import { createOAuthLogin } from 'better-iam/oauth';
import { iam } from './iam';

export const login = createOAuthLogin({
  ...iam.protocolHost,
  trustedOrigins: ['https://app.example.com'],
  connections: [
    {
      id: 'acme-google',
      tenantId: process.env.ACME_TENANT_ID!,
      kind: 'google',
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
      redirectUri: 'https://app.example.com/oauth/acme-google/callback',
    },
  ],
});
iam.useProtocol(login);

import { createOAuthLogin } from 'better-iam/oauth';
import { iam } from './iam';

export const login = createOAuthLogin({
  ...iam.protocolHost,
  connections: [
    {
      id: 'auth0-bridge',
      tenantId: process.env.APP_TENANT_ID!,
      kind: 'oidc',
      issuer: 'https://your-tenant.us.auth0.com/', // exactly as in Auth0's discovery document
      clientId: process.env.AUTH0_BRIDGE_CLIENT_ID!,
      clientSecret: process.env.AUTH0_BRIDGE_CLIENT_SECRET!,
      redirectUri: 'https://app.example.com/oauth/auth0-bridge/callback',
    },
  ],
});
iam.useProtocol(login);

// Inside the loop, for the tenant the bridge serves (APP_TENANT_ID):
if (tenantId === process.env.APP_TENANT_ID && DATABASE_CONNECTIONS.has(member.connection))
  providers.set('auth0-bridge', {
    providerId: 'auth0-bridge',
    issuer: 'https://your-tenant.us.auth0.com/', // the connection's issuer, trailing slash included
    subject: member.user_id,
  });