Building on auth-server

auth-server is meant to be forked, not extended in place. This page covers the places you'll likely want to edit.

Pick one datastore variant

The repository ships with MongoDB and SQL side by side so the reference is complete, but a real fork only needs one. You can safely delete the source for the database you will not be using:

• Remove src/server.ts, src/mongo/ or src/sql/ (whichever you're not using), and the matching config.mongo.ts/config.sql.ts, docker-compose.mongo.yml/docker-compose.sql.yml, server.mongo.ts/server.sql.ts, and test/*.mongo.test.ts/test/*.sql.test.ts files.
• Rename the desired server.mongo.ts/server.sql.ts to src/server.ts.

Every example below assumes the Mongo variant; the SQL variant follows the identical pattern with *SQL classes instead of *Mongo.

Adding an OIDC provider

Every route in src/mongo/routes/ is a one-line subclass binding a library strategy or model to an HTTP path. AuthOIDCRoute.ts is the pattern to copy for a second provider:

// src/mongo/routes/AuthOIDCRoute.ts (shipped)
import { RouteDecorators } from "@rapidrest/service-core";
import { BaseAuthOIDCRouteMongo } from "@rapidrest/auth/mongo";
import { OIDCProvider } from "@rapidrest/auth";
import { ObjectDecorators } from "@rapidrest/core";
const { Config } = ObjectDecorators;
const { ApiRoute } = RouteDecorators;

@ApiRoute("/auth/oidc")
export class AuthOIDCRoute extends BaseAuthOIDCRouteMongo {
  @Config("auth:oidc")
  protected providerConfig: OIDCProvider = { /* ... */ };
}

OIDCStrategy supports multiple concurrently registered instances (see Auth Library → Strategies), but a second BaseAuthOIDCRoute subclass needs two overrides, not just a different providerConfig: a distinct strategyName, and a login() override with a matching @Auth([...]) so the base class's own hardcoded @Auth(["oauth"]) doesn't get inherited and collide with the first provider. See Auth Library → Base Routes for why that second override is necessary. With both in place, add a second file with its own path and config key:

// src/mongo/routes/AuthGithubRoute.ts
import { RouteDecorators } from "@rapidrest/service-core";
import { BaseAuthOIDCRouteMongo } from "@rapidrest/auth/mongo";
import { OIDCProvider } from "@rapidrest/auth";
import { ObjectDecorators } from "@rapidrest/core";
import type { JWTUser } from "@rapidrest/core";
import type { HttpRequest, HttpResponse } from "@rapidrest/service-core";
const { Config } = ObjectDecorators;
const { ApiRoute, Auth, Request, Response } = RouteDecorators;
const AuthUser = RouteDecorators.User;

@ApiRoute("/auth/github")
export class AuthGithubRoute extends BaseAuthOIDCRouteMongo {
  protected strategyName = "github";

  @Config("auth:github")
  protected providerConfig: OIDCProvider = {
    name: "github",
    authorizationURL: "https://github.com/login/oauth/authorize",
    tokenURL: "https://github.com/login/oauth/access_token",
    clientID: "...",
    clientSecret: "...",
    redirectURI: "https://my-auth.example.com/auth/oidc/github",
    protocol: "oauth2",
    scope: ["read:user", "user:email"],
  };

  @Auth(["github"])
  public override async login(@AuthUser user: JWTUser, @Request req: HttpRequest, @Response res: HttpResponse) {
    return super.login(user, req, res);
  }
}

Then add the matching auth:github block to src/config.mongo.ts, following the shipped auth:oidc example already there.

Extending the data models

src/mongo/Models.ts currently just re-exports the library's models unmodified:

// src/mongo/Models.ts (shipped)
export { UserMongo, AliasMongo, ProfileMongo, SecretMongo } from "@rapidrest/auth/mongo";

That re-export exists so ClassLoader/ObjectFactory pick the classes up at startup (see Core Concepts → Dependency Injection). To customize the data model, subclass it with the same name as the original export as shown in the example below:

// src/mongo/Models.ts
import { UserMongo as BaseUserMongo } from "@rapidrest/auth/mongo";
export { AliasMongo, ProfileMongo, SecretMongo } from "@rapidrest/auth/mongo";

export class UserMongo extends BaseUserMongo {
  tenantId?: string;
}

Background jobs

src/mongo/Jobs.ts re-exports DefaultAccountsMongo, the library's job that seeds the built-in accounts. Add your own scheduled jobs here the same way you would in any RapidREST project (see Background Jobs).

Non-auth routes

src/mongo/routes/ also has the standard service-core default routes (AdminRoute, MetricsRoute, OpenAPIRoute, StatusRoute). These are the same Default Routes any generated project gets. Keep them, drop them, or add your own business routes alongside the auth ones exactly as you would in any RapidREST service.

wwwRoute and AdminConsoleRoute are different — they mount the two server-rendered React apps (sign-in/sign-up/account, and the admin console) that ship with auth-server. See The React UI for what's in them and how to build on top of that layer specifically.

Testing

test/ pairs a .mongo.test.ts and .sql.test.ts file per feature area (e.g. AuthMFARoute.mongo.test.ts / AuthMFARoute.sql.test.ts). Follow that split for anything you add, and see Testing for the general route/datastore testing patterns those files build on. k6-tests/ has load tests you can adapt if you need to benchmark your fork before deploying it.