Migrate from WorkOS

[
  {
    "id": "org_01H...",
    "name": "Acme",
    "domains": ["acme.com"],
    "ownerEmail": "it-admin@acme.com",
    "sso": "saml",
    "directory": "scim"
  }
]

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!, // https://app.example.com
  authentication: {
    sendEmail,
    passwordlessEmail: true, // emailed codes replace Magic Auth
  },
  permissions: {
    identityAttributes: { workosId: 'string', department: 'string' },
    resourceTypes: {
      project: { actions: ['projects:read', 'projects:write'] },
    },
  },
});

import { readFileSync } from 'node:fs';
import { createSamlService } from 'better-iam/saml';
import { createScimService } from 'better-iam/scim';
import { iam } from './iam';

export const saml = createSamlService({
  ...iam.protocolHost,
  basePath: '/api/iam/saml',
  serviceProvider: {
    baseUrl: process.env.BETTER_IAM_BASE_URL!,
    privateKey: readFileSync(process.env.SAML_SP_KEY_FILE!, 'utf8'),
    publicCertificate: readFileSync(process.env.SAML_SP_CERT_FILE!, 'utf8'),
  },
  afterSignIn: '/dashboard', // the ACS redirects here with the session cookie set
  errorUrl: '/login', // failed sign-ins land here with ?error=CODE
});

export const scim = createScimService({
  ...iam.protocolHost,
  basePath: '/api/iam/scim/v2',
  adminBasePath: '/api/iam/scim-admin',
  mapAttributes: ({ enterprise }) =>
    typeof enterprise?.department === 'string' ? { department: enterprise.department } : undefined,
});

iam.useProtocol(saml);
iam.useProtocol(scim);

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

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

type WorkosOrganization = {
  id: string;
  name: string;
  domains: string[];
  ownerEmail: string;
  sso: 'saml' | 'oidc' | null;
  directory: 'scim' | 'api' | null;
};

const credential = { token: process.env.BETTER_IAM_TOKEN! };
const rootTenantId = process.env.ROOT_TENANT_ID!;
const organizations = JSON.parse(await readFile('workos/organizations.json', 'utf8')) as WorkosOrganization[];

const tenantMap: Record<string, string> = {};
for (const organization of organizations) {
  const { tenant } = await iam.api.tenants.create(credential, {
    parentId: rootTenantId,
    type: 'organization',
    name: organization.name,
    ownerEmail: organization.ownerEmail,
    activate: true, // active now; the owner's account is created without an invitation
  });
  tenantMap[organization.id] = tenant.id;
}
await writeFile('workos/tenant-map.json', JSON.stringify(tenantMap, null, 2));

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

type WorkosOrganization = { id: string; name: string; domains: string[] };

const credential = { token: process.env.BETTER_IAM_TOKEN! };
const organizations = JSON.parse(await readFile('workos/organizations.json', 'utf8')) as WorkosOrganization[];
const tenantMap = JSON.parse(await readFile('workos/tenant-map.json', 'utf8')) as Record<string, string>;

for (const organization of organizations) {
  const tenantId = tenantMap[organization.id]!;
  const claimed = await iam.api.domains.list(credential, { tenantId });
  for (const domain of organization.domains) {
    const existing = claimed.find((item) => item.domain === domain);
    const claim = existing ?? (await iam.api.domains.add(credential, { tenantId, domain }));
    if (claim.status === 'verified') continue;
    const { verified } = await iam.api.domains.verify(credential, { tenantId, domainId: claim.id });
    if (!verified) {
      console.log(`${organization.name}: publish ${claim.dnsRecord.type} ${claim.dnsRecord.name} = ${claim.dnsRecord.value}`);
    }
  }
}

import { saml, scim } from '../protocols';

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

const connection = await scim.createConnection(credential, {
  tenantId: process.env.ACME_TENANT_ID!,
  name: 'Acme Okta provisioning',
});
console.log('SCIM base URL:', `${process.env.BETTER_IAM_BASE_URL}${connection.path}`);
console.log('Bearer token (shown once):', connection.token);

// People this directory creates link to the SSO connection at their first SSO sign-in.
await saml.updateConnection(credential, {
  tenantId: process.env.ACME_TENANT_ID!,
  connectionId: 'acme-okta',
  trustScimProvisioned: [connection.id],
});

import { scim } from '../protocols';

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

await scim.setRoleMappings(credential, {
  tenantId: process.env.ACME_TENANT_ID!,
  connectionId: process.env.ACME_SCIM_CONNECTION_ID!,
  groupId: process.env.ACME_ENGINEERING_GROUP_ID!, // the group the directory pushed
  roleIds: [process.env.ACME_MEMBER_ROLE_ID!],
});

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

type WorkosOrganization = { id: string; sso: string | null; directory: string | null };
type WorkosUser = {
  id: string;
  email: string;
  email_verified?: boolean;
  first_name: string | null;
  last_name: string | null;
  identities?: Array<{ provider: string; idp_id: string }>;
};
type Membership = { organizationId: string; userId: string; roleSlug: string };
type Link = { providerId: string; issuer: string };

// WorkOS role slug -> Better IAM role name in every tenant.
const roleNames: Record<string, string> = { admin: 'Admin', member: 'Member' };

// WorkOS identity provider -> the Better IAM connection that replaces it, per WorkOS organization. 'SSO' is the
// organization's SSO connection; SAML connections are read from the tenant below, OIDC ones are listed here with
// their id and exact issuer.
const CONNECTIONS: Record<string, Record<string, Link>> = {
  org_globex: {
    SSO: {
      providerId: 'globex-entra',
      issuer: `https://login.microsoftonline.com/${process.env.GLOBEX_ENTRA_TENANT_ID}/v2.0`,
    },
  },
};

const credential = { token: process.env.BETTER_IAM_TOKEN! };
const organizations = JSON.parse(await readFile('workos/organizations.json', 'utf8')) as WorkosOrganization[];
const tenantMap = JSON.parse(await readFile('workos/tenant-map.json', 'utf8')) as Record<string, string>;
const memberships = JSON.parse(await readFile('workos/memberships.json', 'utf8')) as Membership[];

const users = new Map<string, WorkosUser>();
for await (const line of createInterface({ input: createReadStream('workos/users.ndjson'), crlfDelay: Infinity })) {
  if (line.trim()) {
    const user = JSON.parse(line) as WorkosUser;
    users.set(user.id, user);
  }
}

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;
  }
}

for (const organization of organizations) {
  if (organization.directory === 'scim') continue; // the directory creates these people
  const tenantId = tenantMap[organization.id]!;
  const targets: Record<string, Link> = { ...CONNECTIONS[organization.id] };
  if (organization.sso === 'saml') {
    const [connection] = await saml.listConnections(credential, { tenantId });
    if (connection) targets.SSO = { providerId: connection.providerId, issuer: connection.idpIssuer };
  }
  if (organization.sso && !targets.SSO) {
    console.log(`${organization.id}: recreate its SSO connection first`);
    continue;
  }

  await iam.api.config.apply(credential, {
    tenantId,
    config: {
      version: 1,
      roles: [
        { name: 'Admin', permissions: ['projects:read', 'projects:write'] },
        { name: 'Member', permissions: ['projects:read'] },
      ],
    },
  });
  const roleIds = new Map((await iam.api.roles.list(credential, { tenantId })).map((role) => [role.name, role.id]));
  const seen = await existingEmails(tenantId);

  const rows = memberships
    .filter((membership) => membership.organizationId === organization.id)
    .flatMap((membership) => {
      const user = users.get(membership.userId);
      const email = user?.email.trim().toLowerCase();
      if (!user || !email || seen.has(email)) return [];
      seen.add(email);
      const roleId = roleIds.get(roleNames[membership.roleSlug] ?? '');
      const providers = new Map<string, Link & { subject: string }>();
      for (const identity of user.identities ?? []) {
        const target = targets[identity.provider];
        if (target) providers.set(target.providerId, { ...target, subject: identity.idp_id });
      }
      return [{
        workosId: user.id,
        entry: {
          email,
          name: [user.first_name, user.last_name].filter(Boolean).join(' ') || email,
          emailVerified: user.email_verified === true,
          providers: [...providers.values()],
          attributes: { workosId: user.id },
          roleIds: roleId ? [roleId] : [],
        },
      }];
    });

  const idMap: Record<string, string> = {};
  for (let start = 0; start < rows.length; start += 100) {
    const batch = rows.slice(start, start + 100);
    const { identities } = await iam.api.identities.createMany(credential, {
      tenantId,
      identities: batch.map((row) => row.entry),
    });
    batch.forEach((row, i) => (idMap[row.workosId] = identities[i]!.id));
  }
  await writeFile(`workos/id-map-${organization.id}.json`, JSON.stringify(idMap, null, 2));
  console.log(`${organization.id}: imported ${rows.length}`);
}

npx tsx scripts/workos-import-users.ts

import { iam } from '@/lib/iam';
import { findOrganizationByTenantId } from '@/lib/organizations'; // your table: tenantId -> { loginUrl? }

export async function POST(request: Request) {
  const { email } = (await request.json()) as { email: string };
  // A domain no tenant has verified is refused; treat it as "no organization".
  const found = await iam.api.domains.discover({ email }).catch(() => null);
  if (!found) return Response.json({ method: 'passwordless', tenantId: null });

  const organization = await findOrganizationByTenantId(found.tenantId);
  const sso = found.allowedMethods === null || found.allowedMethods.includes('federated');
  if (sso && organization?.loginUrl) return Response.json({ redirect: organization.loginUrl });

  // No SSO for this organization: an emailed code or magic link in its tenant.
  return Response.json({ method: 'passwordless', tenantId: found.tenantId });
}