Identity plugin

The foundational plugin. It answers who is this person? and what are they allowed to do?, and it enforces both app-wide: an AuthGuard is registered as the global APP_GUARD, so every route requires a valid session unless it is marked @Public().

Apograph is invite-only by design. There is no public registration; the only route into an account is an admin’s invite, or — since 0.4.0 — a first sign-in through an identity provider a deployment has configured.

Install

npm install @apograph/identity-server @apograph/identity-admin

Add an identity provider package only if you want single sign-on:

npm install @apograph/identity-provider-oidc

To reach a directory none of them speaks, see writing an SSO provider.

Register

// apps/server/src/plugins.ts
import { IdentityPlugin } from '@apograph/identity-server';

IdentityPlugin(config.plugins.identity);

With providers, the second argument carries the constructed adapters:

IdentityPlugin(config.plugins.identity, {
    sso: {
        providers: [{ name: 'google', provider: createGoogleProvider({ /* … */ }) }]
    }
});

// apps/admin/src/plugins.ts
import { IdentityPlugin } from '@apograph/identity-admin';

IdentityPlugin();

The admin half goes first in the admin list. It is the one plugin contributing public routes — the sign-in and accept-invite screens — which have to render outside the gated layout the shell wraps everything else in.

What it owns

Workspaces, users, roles, permissions, memberships, sessions and tokens are its tables, and it ships their migrations. It also seeds the three system roles — admin, contributor, viewer — idempotently on boot, and protects them from deletion.

Environment

Sessions and tokens

Root administrator

Provisioning is idempotent and non-destructive: an existing account with that address is left exactly as it is. This is how you get your first login.

Single sign-on

Per-provider variables — SSO_OIDC_*, SSO_GITHUB_*, SSO_SAML_* — are on the single sign-on page, along with what a sign-in is and is not allowed to do to an account.

HTTP surface

Sign-in, sign-out and the redemption halves of the invite and reset flows live here, under /api/auth. Issuing invites and resets belongs to the users plugin; identity owns the tokens table and the redemption.

The full route list is in the endpoint reference, and the permission keys the guards check are in the permission reference.

What is not here