Authentication

The authentication module is optional. With JWT, the template includes a User entity, email/password login, and RS256 token issuance. With OAuth2, users are created or reused after the authorization code flow. API Key authenticates machine-to-machine calls at the HTTP edge.

Installing auth does not patch data-source-factory.ts: the User entity joins the DataSource via @Entity (DbContext), and UserRepository is registered in RepositoryModule.

Main components

Public routes

Routes with @IsPublic() bypass AuthGuard and do not require Bearer in OpenAPI/Scalar:

import { IsPublic } from '@/host/decorators/is-public.decorator';

@Post('login')
@IsPublic()
handle() { ... }

All other endpoints are protected by default — no need for @ApiBearerAuth() on each controller.

Profile restriction

The profile value comes from the user in the database (loaded by AuthGuard after JWT validation):

import { AuthProfile } from '@/core/auth/auth-profile.enum';
import { RestrictionByProfile } from '@/host/decorators/restriction-by-profile.decorator';

@Delete(':id')
@RestrictionByProfile([AuthProfile.admin])
handle(@Param('id') id: string) { ... }

Login (JWT password)

Public endpoint to authenticate with email and password:

POST /auth/login
Content-Type: application/json

{
  "username": "admin@example.com",
  "password": "admin123"
}

Response:

{
  "accessToken": "...",
  "refreshToken": "..."
}

Token refresh

Renew the access/refresh pair without re-authenticating:

POST /auth/refresh
Authorization: Bearer <refreshToken>

Or send the refresh token as an httpOnly cookie named refreshToken — AuthGuard promotes it to Authorization automatically on this route.

On login, the cookie is set with httpOnly and path=/. On localhost (API_HOST containing localhost): SameSite=Strict without Secure. Outside localhost (front ≠ API): SameSite=None; Secure so the browser accepts Set-Cookie on cross-site XHR.

Response format matches POST /auth/login (accessToken + refreshToken). Refresh tokens are rejected on all other routes by JwtStrategy.

Logged user in handlers

Inject ILoggedUserInfoService (same pattern as Globo Seguros / Solicita.ai):

import { ILoggedUserInfoService } from '@/domain/services/ilogged-user-info.service';

@Injectable()
export class MyHandler {
  constructor(private readonly loggedUserInfo: ILoggedUserInfoService) {}

  async handle(req: MyRequest) {
    const user = this.loggedUserInfo.getUser();
  }
}

The service is request-scoped and reads request.user populated by AuthGuard after JWT validation.

OAuth2 — any provider, any quantity

With the CLI (kl-nest new → OAuth2), the template ships a ready authorization code flow. The usual case is login with third-party providers (Google, Microsoft, Auth0, Keycloak, GitHub Enterprise, Okta, etc.) — you only fill credentials in .env. You do not reimplement code exchange, CSRF state, OIDC discovery, or controllers.

Google and Microsoft in .env.example are just examples. The library is generic: list as many providers as you need in OAUTH2_PROVIDERS and repeat the OAUTH2_{KEY}_* pattern for each. The KEY is the value you send in the body (provider: "auth0" → OAUTH2_AUTH0_*).

What is already built (configure only)

What you fill in (from the provider)

Created outside the API, in the IdP console:

Register an OIDC provider (pattern)

For each key in OAUTH2_PROVIDERS, add the OAUTH2_{KEY}_* block. Endpoints (authorization, token, userinfo) come from /.well-known/openid-configuration.

OAUTH2_PROVIDERS=google,microsoft,auth0,keycloak
# --- google (example) ---
OAUTH2_GOOGLE_DOMAIN=https://accounts.google.com
OAUTH2_GOOGLE_CLIENT_ID=...
OAUTH2_GOOGLE_CLIENT_SECRET=...
OAUTH2_GOOGLE_SCOPE=openid profile email
# --- microsoft (example) ---
OAUTH2_MICROSOFT_DOMAIN=https://login.microsoftonline.com/common/v2.0
OAUTH2_MICROSOFT_CLIENT_ID=...
OAUTH2_MICROSOFT_CLIENT_SECRET=...
OAUTH2_MICROSOFT_SCOPE=openid profile email
# --- auth0 ---
OAUTH2_AUTH0_DOMAIN=https://tenant.auth0.com
OAUTH2_AUTH0_CLIENT_ID=...
OAUTH2_AUTH0_CLIENT_SECRET=...
OAUTH2_AUTH0_SCOPE=openid profile email
# --- keycloak ---
OAUTH2_KEYCLOAK_DOMAIN=https://idp.company.com/realms/prod
OAUTH2_KEYCLOAK_CLIENT_ID=...
OAUTH2_KEYCLOAK_CLIENT_SECRET=...
OAUTH2_KEYCLOAK_SCOPE=openid profile email
API_HOST=http://localhost:3000

End-to-end flow (any provider):

sequenceDiagram
  participant FE as Frontend
  participant API as Koala Nest
  participant IdP as OIDC Provider
  FE->>API: POST /oauth2/auth-link { provider: auth0 }
  API-->>FE: { url }
  FE->>IdP: redirect (user signs in)
  IdP-->>FE: callback ?code&state
  FE->>API: POST /oauth2/token { provider, code, state }
  API-->>FE: OAuthUserInfoDto
  FE->>API: POST /auth/login { username, password }
  API-->>FE: accessToken + refreshToken

Your own OAuth server (advanced)

When you host the server and it does not expose OIDC discovery, set URLs manually (no _DOMAIN):

OAUTH2_PROVIDERS=myapp
OAUTH2_MYAPP_CLIENT_ID=...
OAUTH2_MYAPP_CLIENT_SECRET=...
OAUTH2_MYAPP_SCOPE=openid profile email
OAUTH2_MYAPP_AUTHORIZATION_URL=https://auth.myapp.com/oauth/authorize
OAUTH2_MYAPP_TOKEN_URL=https://auth.myapp.com/oauth/token
OAUTH2_MYAPP_USERINFO_URL=https://auth.myapp.com/oauth/userinfo

State validation (flow authenticity)

On POST /oauth2/auth-link, the API generates a random state and stores it temporarily:

oauth2:state:{state} → { provider }   (10 min TTL)

On POST /oauth2/token, it checks the state exists, matches the request provider, and removes the key (one-time use). This ensures the code belongs to a flow started by the API — CSRF protection. The frontend (Angular, etc.) only forwards code and state; validation is always server-side, because the endpoint is public.

Implemented in OAuth2AuthService — uses ICacheService under the hood (temporary storage, not business data cache).

sequenceDiagram
  participant FE as Frontend
  participant API as Koala Nest
  participant Store as Store (memory or Redis)
  participant IdP as OIDC Provider
  FE->>API: POST /oauth2/auth-link { provider }
  API->>Store: save oauth2:state:{state}
  API-->>FE: { url with state }
  FE->>IdP: redirect
  IdP-->>FE: callback ?code&state
  FE->>API: POST /oauth2/token { provider, code, state }
  API->>Store: validate and remove state
  API-->>FE: OAuthUserInfoDto

What remains for the developer

The template does not persist users or issue API JWT automatically after OAuth. You decide:

1. Map OAuthUserInfoDto → claims (sub, profile, email);
2. Call POST /auth/login to issue the API JWT;
3. (Optional) create/update the user in the database before step 2.

Bootstrap with guards

When the CLI installs authentication, main.ts registers global guards. Background jobs are started automatically by JobsBootstrapService via JobsModule.register() in AppModule:

app.useGlobalGuards(
  await app.resolve(AuthGuard),
  await app.resolve(ProfilesGuard),
);

Job bootstrap subscribes to domain events and starts CronJobs only when CRON_JOBS_ENABLED=true. The delay before starting jobs is controlled by BOOTSTRAP_DELAY_MS.

API Key (M2M)

API Key authenticates synchronous HTTP callers (integrations, BFF, occasional service hops). It does not replace a message broker or force a file-proxy API — cloud storage + messaging remain the preferred scalable design. The strategy lives in the host layer; handlers only see the already-authenticated user via ILoggedUserInfoService.

CLI (new): --auth jwt,api-key (or oauth2,api-key / jwt,oauth2,api-key). On an existing project: kl-nest add auth api-key (with JWT and/or OAuth2 already installed, or in the same command: kl-nest add auth jwt api-key). Optional --api-key-internal-subnet allows private (RFC1918) IPs for domain type when pods talk inside the cluster.

CRUD and token

• Endpoints under /api-key (create/list/read/update/delete), scoped to the authenticated user
• On create, the key is an RS256 JWT with typ: api-key, sub = userId, iss = key id — returned only in that response
• Usage: header ApiKey: <jwt>

Origin types (origin CSV)

* in the list only unlocks in develop/test. With internal subnet enabled, private IPs also pass domain without listing every pod.

Enable trust proxy when the API sits behind a load balancer / ingress.

Authentication in Scalar

With authentication installed, Scalar obtains credentials via authentication in apiReference:

• JWT: JWT scheme (password flow) → POST /auth/login
• OAuth2: one scheme per provider (authorization code) → POST /oauth2/scalar-token
• API Key: ApiKey scheme (header ApiKey)

Full guide: OpenAPI with Scalar

Next steps

• Security — layered view (Helmet, CORS, cookies, guards)
• Environment variables — JWT, OAuth2, and Redis keys
• OpenAPI with Scalar — automatic Scalar configuration
• Controllers — thin HTTP → handler pattern