Documentation

Overview

BM Guardian is an identity and access management (IAM) platform for educational institutions, providing authentication (email/password + SSO), authorization (RBAC), OAuth2 application management, and a full OAuth2/OIDC Provider (Authorization Code Flow + PKCE, Client Credentials). It supports Multi-Factor Authentication (TOTP + Email OTP), two-level organization hierarchy (parent groups → child schools), user transfer workflows with approval, app-scoped user management API for subscriber apps, and org-scoped user attributes for managing institution-specific metadata. External apps can integrate as “Applications” registered per organization and authenticate users via standard OpenID Connect or manage users programmatically via the Client Credentials grant.

Quick Start

Email:    admin@bm-guardian.local
Password: admin123

Password Authentication

For apps that use BM Guardian as the primary authentication provider, users log in directly with their email and password. Tokens are managed via httpOnly cookies.

const API_BASE = process.env.NEXT_PUBLIC_BM_BASE_URL || 'http://localhost:3001';

export async function login(email: string, password: string) {
  const res = await fetch(`${API_BASE}/api/auth/login`, {
    method: 'POST',
    credentials: 'include',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password }),
  });
  if (!res.ok) throw new Error('Login failed');
  return res.json(); // { user, memberships }
}

export async function getMe() {
  const res = await fetch(`${API_BASE}/api/auth/me`, {
    credentials: 'include',
  });
  if (!res.ok) throw new Error('Not authenticated');
  return res.json(); // { id, email, firstName, lastName, role, memberships }
}

export async function refreshToken() {
  const res = await fetch(`${API_BASE}/api/auth/refresh`, {
    method: 'POST',
    credentials: 'include',
  });
  return res.ok;
}

export async function logout() {
  await fetch(`${API_BASE}/api/auth/logout`, {
    method: 'POST',
    credentials: 'include',
  });
}

await login('user@org.com', 'pass123');
const user = await getMe();
// { id, email, firstName, lastName, role, memberships }

Organization Hierarchy

BM Guardian supports a two-level organization hierarchy: parent groups contain child schools. This allows district-level administrators to manage multiple schools under a single umbrella.

Key Concepts

• Parent groups (parentId = null) serve as district or network containers.
• Child schools reference their parent via the parentId field.
• Two levels only — the API prevents deeper nesting (a parent must itself have no parent).
• Permission inheritance: parent org admins automatically have authority over all child orgs via the isOrgAdmin() helper.
• Standalone orgs (no parent, no children) are also supported.

API Usage

POST /api/organizations
{ "name": "Education Group", "slug": "education-group" }

POST /api/organizations
{ "name": "Springfield High", "slug": "springfield-high",
  "parentId": "<group-id>" }

GET /api/organizations?parentId=null

GET /api/organizations/:id
→ { ...org, children: [{ id, name, slug, isActive, createdAt }] }

User Transfer Workflow

BM Guardian supports transferring users between institutions with an approval-based workflow. The receiving school initiates the request, and the leaving school approves or rejects it.

How it works

Transfer Statuses

Endpoints

Example: Create a Transfer

{
  "userId": "user-uuid",
  "fromOrgId": "sample-institution-id",
  "toOrgId": "springfield-elementary-id",
  "toRole": "member",
  "notes": "Relocating for new term"
}

User Attributes

User attributes are a flexible key-value store for attaching metadata to users. Attributes can be org-scoped (tied to a specific institution) or global (shared across all institutions).

Attribute Types

Endpoints

Example: Set Org Attributes

{
  "attributes": {
    "school_email": "john@springfield-elementary.edu",
    "lms_account_id": "LMS-2024-001",
    "classroom": "Room 204"
  }
}

OAuth2 Authorization Code Flow + PKCE

BM Guardian acts as a full OAuth2 Authorization Server and OIDC Provider. External apps can authenticate users using the standard Authorization Code Flow with PKCE — the recommended approach for SPAs and mobile apps.

How it works

Full React Example

const BM_BASE = process.env.NEXT_PUBLIC_BM_BASE_URL || 'http://localhost:3000';
const CLIENT_ID = process.env.NEXT_PUBLIC_CLIENT_ID!;
const REDIRECT_URI = 'http://localhost:5174/callback';

// --- Step 1: Generate PKCE and redirect to authorize ---

function base64url(buffer: ArrayBuffer): string {
  return btoa(String.fromCharCode(...new Uint8Array(buffer)))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

async function startLogin() {
  const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
  const challenge = base64url(
    await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))
  );
  const state = base64url(crypto.getRandomValues(new Uint8Array(16)));

  sessionStorage.setItem('pkce_verifier', verifier);
  sessionStorage.setItem('oauth_state', state);

  const params = new URLSearchParams({
    response_type: 'code',
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    scope: 'openid profile email',
    state,
    code_challenge: challenge,
    code_challenge_method: 'S256',
  });

  window.location.href = `${BM_BASE}/oauth/authorize?${params}`;
}

// --- Step 2: Handle callback and exchange code for tokens ---

async function handleCallback() {
  const params = new URLSearchParams(window.location.search);
  const code = params.get('code');
  const state = params.get('state');

  if (state !== sessionStorage.getItem('oauth_state')) {
    throw new Error('State mismatch — possible CSRF attack');
  }

  const verifier = sessionStorage.getItem('pkce_verifier')!;

  const res = await fetch(`${BM_BASE}/oauth/token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: code!,
      redirect_uri: REDIRECT_URI,
      client_id: CLIENT_ID,
      code_verifier: verifier,
    }),
  });

  if (!res.ok) throw new Error('Token exchange failed');
  const { access_token, id_token } = await res.json();

  const payload = JSON.parse(atob(id_token.split('.')[1]));
  console.log('User:', payload.name, payload.email);

  return { access_token, id_token, user: payload };
}

// --- Step 3: Call UserInfo endpoint ---

async function getUserInfo(accessToken: string) {
  const res = await fetch(`${BM_BASE}/oauth/userinfo`, {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  return res.json();
}

Client Credentials Grant (Machine-to-Machine)

Subscriber apps (such as BM-LMS) can authenticate as themselves — without a user present — to manage users programmatically. This uses the standard OAuth2 Client Credentials grant type.

Prerequisites

• Register an application and note the Client ID and Client Secret.
• Configure allowedScopes for the app (any of: users:read, users:write, users:suspend, auth:verify, auth:write, mfa:read, mfa:write).

Token Request

grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&scope=users:read users:write users:suspend

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "users:read users:write users:suspend"
}

App-Scoped User Management API

Apps authenticated via the Client Credentials grant can manage users within their own organization using the /api/v1/users endpoints. All operations are scoped to the app's organization automatically.

Endpoints

Example: Create a User

// Get access token via client_credentials grant
const tokenRes = await fetch('http://localhost:3001/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    scope: 'users:read users:write',
  }),
});
const { access_token } = await tokenRes.json();

// Create a user in the app's organization
const userRes = await fetch('http://localhost:3001/api/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'jane.doe@school.edu',
    firstName: 'Jane',
    lastName: 'Doe',
    password: 'secureP@ss1',
  }),
});
const newUser = await userRes.json();

App-Scoped Auth API

Apps authenticated via the Client Credentials grant can verify user credentials, handle MFA challenges, and manage passwords on behalf of their users. The app manages its own sessions — no cookies are set by these endpoints.

Credential Verification Flow

Endpoints

Example: Verify Credentials

// Request
{ "email": "student@school.edu", "password": "password123" }

// Response (no MFA)
{ "verified": true, "user": { "id": "uuid", "email": "student@school.edu", "orgRole": "member", ... } }

// Response (MFA required)
{ "verified": false, "mfaRequired": true, "mfaPendingToken": "<jwt>", "availableMethods": ["totp"] }

Example: App-Scoped Password Reset

// Request — resetBaseUrl is YOUR app's reset page
{
  "email": "student@school.edu",
  "resetBaseUrl": "https://myapp.com/reset-password"
}
// Email sent with link: https://myapp.com/reset-password?token=<token>

// Then reset:
// POST /api/v1/auth/reset-password
{ "token": "<token-from-email>", "password": "new-password" }

App-Scoped MFA Management API

Apps can manage MFA enrollment for users within their organization. This allows subscriber apps to build custom MFA enrollment flows without requiring users to visit the BM Guardian admin dashboard.

Endpoints

Example: TOTP Enrollment via App

// Step 1: Generate TOTP QR code
const setupRes = await fetch(`http://localhost:3001/api/v1/users/${userId}/mfa/totp/setup`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${appToken}` },
});
const { qrCode, secret } = await setupRes.json();
// Show qrCode (data URL) to the user in your app

// Step 2: User scans QR, enters code from authenticator app
const verifyRes = await fetch(`http://localhost:3001/api/v1/users/${userId}/mfa/totp/verify`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${appToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ code: '123456' }),
});
// { success: true, message: "TOTP enrolled successfully" }

OIDC Endpoints

GET /.well-known/openid-configuration

GET /.well-known/jwks.json
GET /oauth/jwks

GET /oauth/authorize?
  response_type=code
  &client_id=<your_client_id>
  &redirect_uri=<registered_redirect_uri>
  &scope=openid+profile+email
  &state=<random_csrf_state>
  &code_challenge=<base64url(SHA256(code_verifier))>
  &code_challenge_method=S256
  &nonce=<optional_nonce>

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=<same_as_authorize>
&client_id=<your_client_id>
&code_verifier=<original_code_verifier>

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "scope": "openid profile email"
}

GET /oauth/userinfo
Authorization: Bearer <access_token>

{
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "iss": "http://localhost:3001",
  "aud": "app_xxxxxxxxxxxxxxxx",
  "exp": 1719000000,
  "iat": 1718996400,
  "nonce": "n-0S6_WzA2Mj",
  "email": "jane.doe@school.edu",
  "email_verified": true,
  "name": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "org_roles": [
    {
      "org_id": "org_abc123",
      "org_slug": "springfield-elementary",
      "org_name": "Springfield Elementary",
      "role": "admin"
    },
    {
      "org_id": "org_def456",
      "org_slug": "shelbyville-high",
      "org_name": "Shelbyville High",
      "role": "member"
    }
  ],
  "app_roles": [
    {
      "app_id": "app_xyz789",
      "app_name": "Learning Portal",
      "client_id": "client_abc...",
      "roles": ["staff", "app_admin"]
    }
  ]
}

// After obtaining the id_token or calling /oauth/userinfo:

interface OrgRole {
  org_id: string;
  org_slug: string;
  org_name: string;
  role: 'owner' | 'admin' | 'member';
}

// Decode the id_token (or use the userinfo response directly)
const payload = JSON.parse(atob(idToken.split('.')[1]));
const orgRoles: OrgRole[] = payload.org_roles ?? [];

// Check if the user belongs to a specific org
function isMemberOf(orgSlug: string): boolean {
  return orgRoles.some((r) => r.org_slug === orgSlug);
}

// Check if the user is an admin (or owner) of a specific org
function isOrgAdmin(orgSlug: string): boolean {
  return orgRoles.some(
    (r) => r.org_slug === orgSlug && (r.role === 'admin' || r.role === 'owner')
  );
}

// Guard a route or component
if (!isMemberOf('springfield-elementary')) {
  return <p>You do not have access to this institution.</p>;
}

// Show admin-only UI
{isOrgAdmin('springfield-elementary') && (
  <button>Manage Settings</button>
)}

Multi-Factor Authentication (MFA)

BM Guardian supports TOTP (authenticator apps like Google Authenticator, Authy) and Email OTP (6-digit code sent via SMTP) as MFA methods. MFA can be configured at both the organization level and per-user.

Organization MFA Policy

Login Flow with MFA

MFA Enrollment Endpoints

MFA Challenge Endpoints

Admin MFA Management

SSO Provider Setup

Institution admins can configure SSO providers per organization. Navigate to SSO Providers (/providers) in the admin sidebar.

Supported Provider Types

API Reference

Swagger UI

BM Guardian includes a built-in Swagger UI for interactive API exploration. All endpoints are documented with request/response schemas, parameter descriptions, and authentication requirements.

Audit Logging & Provisioning

BM Guardian maintains a comprehensive audit trail for accountability (GDPR/DPDP compliance) and supports outbound user provisioning to external identity systems.

Audit Logs

Every significant admin action is recorded: user login/logout, suspension, deletion, erasure, MFA enrollment, provisioning events, and more. Each log entry captures the actor, action, target, metadata, IP address, and timestamp.

Outbound Provisioning

Provisioning connectors sync user lifecycle events (creation, suspension, activation, deletion) to external identity systems. Events are dispatched automatically when users are managed via the admin dashboard or the App-Scoped API.

GDPR & Data Privacy Compliance

BM Guardian includes built-in support for GDPR (EU) and DPDP (India) data subject rights, including data portability and the right to erasure.

Data Portability (GDPR Art. 20)

Super admins can export all user data as JSON via GET /api/users/:id/export. The export includes: user profile, organization memberships, user attributes, transfers, app role assignments, sessions, OAuth consents, linked SSO providers, and audit logs.

Right to Erasure (GDPR Art. 17 / DPDP Sec. 12)

The DELETE /api/users/:id/erase endpoint anonymizes a user's PII (email becomes erased-uuid@anonymized.local, name becomes “Erased User”) and removes all associated data: sessions, attributes, OAuth consents, app role assignments, and org memberships. Audit log entries are preserved but the actor reference is set to null.

Environment Variables

Create a .env file in the server/ directory:

# JWT Secrets (generate your own for production)
JWT_ACCESS_SECRET=your-access-secret-key-here
JWT_REFRESH_SECRET=your-refresh-secret-here

# Database (defaults to ./data/bm-guardian.db)
DATABASE_PATH=./data/bm-guardian.db

# Server
SERVER_PORT=3001
LOG_LEVEL=info

# OIDC (defaults to http://localhost:3000)
ISSUER_URL=http://localhost:3000

# SMTP (for Email OTP — falls back to console.log if not set)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-smtp-user
SMTP_PASS=your-smtp-password
SMTP_FROM=noreply@bm-guardian.com

# Background cleanup interval (default: 900000 = 15 minutes)
CLEANUP_INTERVAL_MS=900000

For external client apps connecting to BM Guardian:

NEXT_PUBLIC_BM_BASE_URL=http://localhost:3001
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret

Security Best Practices

• Always use HTTPS in production
• Validate redirect URIs — must match exactly what's registered
• Use httpOnly cookies — tokens are never exposed to JavaScript
• Token rotation — refresh tokens proactively, revoke on logout
• CORS — pre-configured for localhost in dev; add production origins in server/src/index.ts
• Credential encryption — client secrets and SAML certs are AES-256 encrypted at rest
• OAuth2 tokens signed with RS256 — verify ID tokens and access tokens using the JWKS endpoint
• PKCE enforcement — public clients must use PKCE; confidential clients must provide client_secret
• One-time authorization codes — codes are deleted immediately after use and expire in 10 minutes
• Transfer approval workflow — org-scoped data is atomically cleaned up during user transfers
• Permission inheritance — parent org admins inherit access to all child organizations
• MFA — TOTP with ±1 step window (30s tolerance), Email OTP with 5-minute expiry, max 5 attempts per challenge
• TOTP secrets encrypted with AES-256 at rest; recovery codes bcrypt-hashed and single-use
• Background cleanup — expired MFA challenges, sessions, and OAuth codes automatically purged every 15 minutes
• App-scoped API — client credentials tokens are org-scoped; apps can only manage users within their own organization

Troubleshooting