Migrate from Keycloak

bin/kc.sh export --file acme-realm.json --realm acme --users realm_file

import { betterIam } from 'better-iam';
import { postgresAdapter } from 'better-iam/adapter-postgres';
import { sendMail } 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: {
    passwordlessEmail: true,
    sendEmail: async (message) => sendMail(message),
  },
  permissions: {
    identityAttributes: {
      legacyId: 'string', // the Keycloak user ID
      department: 'string', // a Keycloak user attribute you keep
    },
    resourceTypes: {
      invoice: { actions: ['invoices:read', 'invoices:approve'] },
      report: { actions: ['reports:read', 'reports:export'] },
    },
  },
});

npx better-iam login --config better-iam.config.mjs --tenant <root-tenant-id> --email root@example.com
export BETTER_IAM_TOKEN=$(npx better-iam token --config better-iam.config.mjs)
export ROOT_TENANT_ID=<root-tenant-id>

import { iam } from '../../iam';

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

const { tenant } = await iam.api.tenants.create(admin, {
  parentId: process.env.ROOT_TENANT_ID!,
  type: 'organization',
  name: 'Acme',
  slug: 'acme', // the realm name works well as the sign-in alias
  ownerEmail: 'it-admin@acme.example',
  activate: true, // active now; the owner's account is created without an invitation
  ownerName: 'Acme IT',
  ownerEmailVerified: true, // only if Keycloak marked this address verified
});
console.log('IAM_TENANT_ID =', tenant.id);

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

type KeycloakRole = { name: string; description?: string; composite?: boolean; composites?: { realm?: string[] } };
type KeycloakGroup = { name: string; path: string; realmRoles?: string[]; subGroups?: KeycloakGroup[] };
type Realm = { realm: string; roles?: { realm?: KeycloakRole[] }; groups?: KeycloakGroup[] };

const realm = JSON.parse(await readFile('acme-realm.json', 'utf8')) as Realm;
const admin = { token: process.env.BETTER_IAM_TOKEN! };
const tenantId = process.env.IAM_TENANT_ID!;

/** What each Keycloak role allows in Better IAM. Roles not listed are created without permissions. */
const permissions: Record<string, string[]> = {
  accountant: ['invoices:read'],
  approver: ['invoices:read', 'invoices:approve'],
  analyst: ['reports:read', 'reports:export'],
};
const skipped = new Set(['offline_access', 'uma_authorization', `default-roles-${realm.realm}`]);

// Roles first, then inheritance once every role exists.
const roleIds: Record<string, string> = {};
const keycloakRoles = (realm.roles?.realm ?? []).filter((role) => !skipped.has(role.name));
for (const role of keycloakRoles) {
  const created = await iam.api.roles.create(admin, {
    tenantId,
    name: role.name,
    ...(role.description ? { description: role.description } : {}),
    ...(permissions[role.name] ? { permissions: permissions[role.name] } : {}),
  });
  roleIds[role.name] = created.id;
}
for (const role of keycloakRoles) {
  const parents = (role.composites?.realm ?? []).filter((name) => roleIds[name]).map((name) => roleIds[name]!);
  if (role.composite && parents.length)
    await iam.api.roles.update(admin, { tenantId, roleId: roleIds[role.name]!, inherits: parents });
}

// Groups: one Better IAM group per path; members of a subgroup also get the roles of every group above it.
const groupIds: Record<string, string> = {};
async function createGroup(group: KeycloakGroup, inherited: string[]): Promise<void> {
  const roles = [...new Set([...inherited, ...(group.realmRoles ?? [])])].filter((name) => roleIds[name]);
  const created = await iam.api.groups.create(admin, {
    tenantId,
    name: group.path.replace(/^\//, ''),
    description: `Keycloak group ${group.path}`,
  });
  groupIds[group.path] = created.id;
  for (const name of roles)
    await iam.api.bindings.create(admin, {
      tenantId,
      roleId: roleIds[name]!,
      subjectType: 'group',
      subjectId: created.id,
    });
  for (const child of group.subGroups ?? []) await createGroup(child, roles);
}
for (const group of realm.groups ?? []) await createGroup(group, []);

await writeFile('acme-ids.json', JSON.stringify({ roleIds, groupIds }, null, 2));

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

type KeycloakUser = {
  id: string;
  username: string;
  email?: string;
  emailVerified?: boolean;
  firstName?: string;
  lastName?: string;
  enabled: boolean;
  attributes?: Record<string, string[]>;
  realmRoles?: string[];
  groups?: string[];
  federatedIdentities?: Array<{ identityProvider: string; userId: string }>;
};

// Keycloak identity provider alias -> the Better IAM connection that replaces it (see "Brokered sign-in" below).
// providerId is the connection's id; issuer is the provider's `iss`, exactly.
const BROKERED: Record<string, { providerId: string; issuer: string }> = {
  google: { providerId: 'acme-google', issuer: 'https://accounts.google.com' },
  'acme-entra': {
    providerId: 'acme-entra',
    issuer: `https://login.microsoftonline.com/${process.env.ACME_ENTRA_TENANT_ID}/v2.0`,
  },
};

const realm = JSON.parse(await readFile('acme-realm.json', 'utf8')) as { users?: KeycloakUser[] };
const { roleIds, groupIds } = JSON.parse(await readFile('acme-ids.json', 'utf8')) as {
  roleIds: Record<string, string>;
  groupIds: Record<string, string>;
};
const admin = { token: process.env.BETTER_IAM_TOKEN! };
const tenantId = process.env.IAM_TENANT_ID!;
const ownerEmail = 'it-admin@acme.example'; // already in the tenant: tenants.create created them

// Resume support: people already imported are kept in acme-users.json.
const mapping: Record<string, string> = JSON.parse(await readFile('acme-users.json', 'utf8').catch(() => '{}'));

const users = (realm.users ?? []).filter(
  (user) =>
    user.email &&
    user.email.toLowerCase() !== ownerEmail &&
    !user.username.startsWith('service-account-') &&
    !mapping[user.id],
);
const withoutEmail = (realm.users ?? []).filter((user) => !user.email).map((user) => user.username);
if (withoutEmail.length) console.warn('Skipped, no email:', withoutEmail.join(', '));

for (let start = 0; start < users.length; start += 100) {
  const batch = users.slice(start, start + 100);
  const { identities } = await iam.api.identities.createMany(admin, {
    tenantId,
    identities: batch.map((user) => ({
      email: user.email!,
      name: [user.firstName, user.lastName].filter(Boolean).join(' ') || user.username,
      emailVerified: user.emailVerified === true,
      providers: (user.federatedIdentities ?? []).flatMap((link) =>
        BROKERED[link.identityProvider] ? [{ ...BROKERED[link.identityProvider]!, subject: link.userId }] : [],
      ),
      attributes: {
        legacyId: user.id,
        ...(user.attributes?.department?.[0] ? { department: user.attributes.department[0] } : {}),
      },
      roleIds: (user.realmRoles ?? []).filter((name) => roleIds[name]).map((name) => roleIds[name]!),
      groupIds: (user.groups ?? []).filter((path) => groupIds[path]).map((path) => groupIds[path]!),
    })),
  });
  // identities[i] replaces batch[i].
  for (const [i, identity] of identities.entries()) mapping[batch[i]!.id] = identity.id;
  await writeFile('acme-users.json', JSON.stringify(mapping, null, 2));
  console.log(`${start + batch.length}/${users.length}`);
}

// Disable everyone Keycloak had disabled, including those imported by an earlier run (repeating it is harmless).
for (const user of realm.users ?? [])
  if (!user.enabled && mapping[user.id])
    await iam.api.identities.setStatus(admin, { tenantId, identityId: mapping[user.id]!, status: 'disabled' });

import { iam } from '../../iam';

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

await iam.api.tenants.setAuthPolicy(admin, {
  tenantId: process.env.IAM_TENANT_ID!,
  authPolicy: {
    requireMfa: true,
    minPasswordLength: 14, // carry over the realm's password policy
    passwordHistory: 5,
  },
});

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

iam.useProtocol(
  createOAuthLogin({
    ...iam.protocolHost,
    connections: [
      {
        id: 'acme-google', // BROKERED.google.providerId
        tenantId: process.env.IAM_TENANT_ID!,
        kind: 'google',
        clientId: process.env.GOOGLE_CLIENT_ID!,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
        redirectUri: 'https://app.acme.example/oauth/acme-google/callback',
      },
      {
        id: 'acme-entra', // BROKERED['acme-entra'].providerId
        tenantId: process.env.IAM_TENANT_ID!,
        kind: 'microsoft',
        microsoftTenant: process.env.ACME_ENTRA_TENANT_ID!,
        clientId: process.env.ACME_ENTRA_CLIENT_ID!,
        clientSecret: process.env.ACME_ENTRA_CLIENT_SECRET!,
        redirectUri: 'https://app.acme.example/oauth/acme-entra/callback',
      },
    ],
  }),
);