WeaveKit Docs
GuidesAccess

Identity — the engine directory

WeaveKit runs RBAC against its own identity directory (weavekit_user / weavekit_department) — the single id space that row scopes, audit actors, and workflow a…

WeaveKit runs RBAC against its own identity directory (weavekit_user / weavekit_department) — the single id space that row scopes, audit actors, and workflow assignees all use. An existing customer directory is an import source: you sync it into the engine before the engine serves scoped access. The engine only ever reads the source tables.

Why sync first

If the engine scoped rows against customer ids while RBAC also needed internal ids, every row filter, audit entry, and workflow node would have to translate across two id spaces. Syncing once up front keeps a single internal id everywhere.

// weavekit.config.ts
export default {
  identity: {
    source: {
      name: 'crm',
      users:       { table: 'sales_user', id: 'id', name: 'name', email: 'email',
                     roles: 'role', department: 'dept_id', director: 'manager_id', enabled: 'active' },
      departments: { table: 'dept', id: 'id', name: 'name', parent: 'parent_id', manager: 'lead_id', enabled: 'active' },
    },
    sync: { onStart: false, deactivateMissing: true },
    required: true,
  },
} satisfies EngineConfig;

Then:

weave sync:identity          # read-only against the customer tables
weave sync:identity --dry-run

The sync is idempotent (upsert on (external_source, external_id)), links departments/users in two passes (a child may reference a parent listed later), detects department parent cycles, keeps a cursor for incremental sources, and soft-disables (never deletes) rows missing from the snapshot.

Sources

identity.source is either a declarative pg descriptor (above) or a function-backed IdentitySource:

import { createFunctionIdentitySource } from '@weave-kit/engine';

const source = createFunctionIdentitySource({
  name: 'hr',
  pull: async (cursor) => {
    const rows = await hrApi.usersSince(cursor);
    return { users: rows.users, departments: rows.departments, cursor: rows.cursor };
  },
});

Enterprise integrations (SCIM, LDAP, HRIS) implement the same IdentitySource contract and are injected the same way — the engine core stays free of protocol dependencies.

Authentication

Either keep the static key map / custom resolver:

{ auth: { source: { 'sk-rep': { id: 'u100', roles: ['sales'], departmentId: 'd-east' } } } }

…or let a verifier authenticate and the directory resolve:

{
  identity: {
    verifier: { verify: (header) => verifyJwt(header) }, // → { ref, claims } | null
    required: true,
  },
}

verifier → directory → subject. A verified credential with no synced local user is rejected with identity.notSynced (403) — run weave sync:identity first. identity.required also gates a custom auth.source on the directory.

Built-in OIDC/JWT (auth.oidc)

For a standards-based IdP you don't need a custom verifier — point auth.oidc at it and the engine validates bearer JWTs locally (signature via JWKS, iss/aud/exp/nbf, asymmetric algs only):

{
  auth: {
    oidc: {
      issuer: 'https://idp.example.com',   // discovery at <issuer>/.well-known/openid-configuration
      // jwksUri: 'https://idp.example.com/.well-known/jwks.json', // or set JWKS directly
      audience: 'weavekit-engine',
      subjectClaim: 'sub',                 // → the external user ref (default: sub)
      rolesClaim: 'roles',                 // also exposed as claims.roles for the directory
      // scopeClaim: 'tenant',
    },
  },
}

It composes with the identity directory exactly like a custom verifier: the resolved ref must have a synced local user (weave sync:identity). The subjectClaim value identifies the user; roles come from the directory. createOidcVerifier is exported for hosts that assemble the authenticator themselves.

Managing identities

Greenfield projects (no external source) manage users directly:

weave identity:list
weave identity:create "Alice" --email alice@x --roles admin,sales
weave identity:disable <id>
weave identity:enable  <id>
weave identity:set-roles <id> --roles admin
weave identity:delete  <id>

Or the admin REST surface (gated by adapters.rest.adminRoles):

RoutePurpose
GET /api/identity/userslist local users
POST /api/identity/userscreate a user
PATCH /api/identity/users/:idenable/disable and/or set roles
DELETE /api/identity/users/:iddelete a user
GET /api/identity/departmentslist local departments
POST /api/identity/departmentscreate a department

Extending (enterprise)

The engine ships the seam and the pg/function sources plus a built-in OIDC/JWT verifier (auth.oidc). @weave-kit/enterprise adds SAML, a SCIM 2.0 server, LDAP/HRIS directory connectors, group→role mapping, multi-IdP and identity-event audit against the same IdentitySource / AuthVerifier contracts. See RBAC for how the resulting subject scopes rows.

On this page