saml.controller.ts

saml.controller.tsapps/api/src/modules/sso/saml.controller.tsraw ← sso12,302 B← Back to the app
1/**
2 * TASK-0131 — SAML 2.0 SP endpoints (mounted OUTSIDE the `api/v1` prefix —
3 * the SAML binding is browser-POST, not a JSON API):
4 *
5 *   GET  /saml/metadata/:orgSlug   — SP metadata (entity id, ACS,
6 *                                      WantAssertionsSigned="true").
7 *   POST /saml/acs                 — the IdP posts `SAMLResponse` (+
8 *                                      `RelayState`) here after sign-in.
9 *
10 * Both are PUBLIC (no user JWT) — the assertion signature + cert binding IS
11 * the authentication; the global AuthGuard whitelists the `/saml/` prefix
12 * (see auth.guard.ts) and `main.ts` excludes it from the api/v1 prefix.
13 *
14 * ACS result handling (browser context):
15 *   - validation/provisioning failure → 302 to `/login?error=sso_<reason>`
16 *     (the reason from the validator's rejection matrix, e.g.
17 *     `sso_bad_signature`, `sso_expired`, `sso_replayed`) — the login page
18 *     renders the error state; the failure is ALSO audited
19 *     (`sso.login_failed {reason}`).
20 *   - success → the refresh cookie is set here (the same rotating session
21 *     as a password login) and the browser is redirected to the RelayState
22 *     (open-redirect safe: relative paths only) or `/w/default`.
23 */
24import { Body, Controller, Get, Inject, Param, Post, Req, Res } from "@nestjs/common";
25import type { Request, Response } from "express";
26import { PrismaService } from "../../common/prisma.service.js";
27import { RedisService } from "../../common/redis.service.js";
28import { AuditService } from "../../common/audit.service.js";
29import { ApiError } from "../../common/errors.js";
30import { loadEnv } from "../../config/env.js";
31import { SamlConfigSchema } from "./schemas.js";
32import { buildSamlStartRedirect, validateAuthnResponse } from "./saml.js";
33import { SsoSecretsService } from "./sso-secrets.js";
34import { SsoProvisioningService } from "./provisioning.service.js";
35 
36const REPLAY_TTL_SECONDS = 600; // 10 min (the ACS replay window)
37 
38@Controller("saml")
39export class SamlController {
40  constructor(
41    @Inject(PrismaService) private readonly prisma: PrismaService,
42    @Inject(RedisService) private readonly redis: RedisService,
43    @Inject(AuditService) private readonly audit: AuditService,
44    @Inject(SsoSecretsService) private readonly secrets: SsoSecretsService,
45    @Inject(SsoProvisioningService) private readonly provisioning: SsoProvisioningService
46  ) {}
47 
48  /**
49   * The PUBLIC ORIGIN THAT SERVES THE SSO PROTOCOL ROUTES (the API). The
50   * SP metadata, the start redirect, and the ACS are all hit by the IdP /
51   * the browser at THIS origin — in two-origin dev (web :3000, api :4000)
52   * that is the API origin (SSO_ORIGIN), not the web origin. Single-origin
53   * (reference nginx) leaves SSO_ORIGIN empty → falls back to WEB_ORIGIN.
54   */
55  private origin(): string {
56    const env = loadEnv();
57    return (env.SSO_ORIGIN || env.WEB_ORIGIN).replace(/\/$/, "");
58  }
59 
60  /** The WEB origin — the final landing pages (`/login`, `/w/default`). */
61  private webOrigin(): string {
62    return loadEnv().WEB_ORIGIN.replace(/\/$/, "");
63  }
64 
65  /** SP entity id for an org (stable, slug-derived — the Audience value). */
66  private spEntityId(orgSlug: string): string {
67    return `${this.origin()}/saml/metadata/${orgSlug}`;
68  }
69 
70  /**
71   * GET /saml/start/:orgSlug — the ANONYMOUS SAML start (slug-addressed, so
72   * the login page's minimal-info `/auth/sso/options?email=` reply — which
73   * reveals only the org slug, never the protocol — can point the browser
74   * here and let the server do the protocol-specific 302). SP-initiated
75   * (HTTP-Redirect binding): build an AuthnRequest, base64url-encode it into
76   * `SAMLRequest`, redirect to the IdP's `ssoUrl`. The ACS is STATELESS
77   * (no stored-request correlation; the signature + cert binding is the
78   * trust anchor), so the E2E mock IdP auto-approves and POSTs the
79   * `AuthnResponse` directly.
80   */
81  @Get("start/:orgSlug")
82  async start(@Param("orgSlug") orgSlug: string, @Res() res: Response): Promise<void> {
83    const org = await this.prisma.organization.findUnique({ where: { slug: orgSlug } });
84    if (!org) {
85      res.status(404).json({ error: { code: "NOT_FOUND", message: "Unknown organization." } });
86      return;
87    }
88    const provider = await this.prisma.ssoProvider.findUnique({ where: { organizationId: org.id } });
89    if (!provider || provider.type !== "SAML") {
90      res
91        .status(404)
92        .json({ error: { code: "NOT_FOUND", message: "Organization has no SAML SSO provider." } });
93      return;
94    }
95    const config = SamlConfigSchema.parse(provider.config);
96    const location = buildSamlStartRedirect({
97      ssoUrl: config.ssoUrl,
98      spEntityId: this.spEntityId(org.slug),
99      acsUrl: `${this.origin()}/saml/acs`
100    });
101    res.status(302).header("location", location).end();
102  }
103 
104  /** GET /saml/metadata/:orgSlug — the SP metadata document. */
105  @Get("metadata/:orgSlug")
106  async metadata(@Param("orgSlug") orgSlug: string, @Res() res: Response) {
107    const org = await this.prisma.organization.findUnique({ where: { slug: orgSlug } });
108    if (!org) throw ApiError.notFound("Unknown organization.");
109    const provider = await this.prisma.ssoProvider.findUnique({
110      where: { organizationId: org.id }
111    });
112    if (!provider || provider.type !== "SAML") {
113      throw new ApiError(
114        "NOT_FOUND",
115        404,
116        "Organization has no SAML SSO provider.",
117        [{ reason: "no_sso_provider" }]
118      );
119    }
120    const entityId = this.spEntityId(orgSlug);
121    const acsUrl = `${this.origin()}/saml/acs`;
122    const xml = `<?xml version="1.0"?>
123<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="${entityId}">
124  <SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
125    <AssertionConsumerService index="1" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="${acsUrl}"/>
126    <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="${acsUrl}"/>
127  </SPSSODescriptor>
128</EntityDescriptor>`;
129    res.setHeader("content-type", "application/xml");
130    res.setHeader("cache-control", "no-store");
131    res.status(200).send(xml);
132  }
133 
134  /**
135   * POST /saml/acs — the Assertion Consumer Service. The IdP POSTs a
136   * form-urlencoded body: `SAMLResponse` (base64 AuthnResponse) + optional
137   * `RelayState`.
138   */
139  @Post("acs")
140  async acs(
141    @Body() body: { SAMLResponse?: string; RelayState?: string },
142    @Req() req: Request,
143    @Res() res: Response
144  ): Promise<void> {
145    const redirectTo = (error: string, orgSlug?: string) => {
146      const target = new URL(`${this.webOrigin()}/login`);
147      target.searchParams.set("error", error);
148      if (orgSlug) target.searchParams.set("org", orgSlug);
149      res.status(302).header("location", target.toString()).end();
150    };
151 
152    const samlResponse = body?.SAMLResponse;
153    if (!samlResponse) {
154      redirectTo("sso_missing_response");
155      return;
156    }
157    let xml: string;
158    try {
159      xml = Buffer.from(samlResponse, "base64").toString("utf8");
160    } catch {
161      await this.audit.audit(req, undefined, {
162        action: "sso.login_failed",
163        resourceType: "user",
164        resourceId: "saml",
165        metadata: { reason: "malformed_base64" }
166      });
167      redirectTo("sso_malformed_response");
168      return;
169    }
170    // Identify the org: from the Audience (SP entity id) — the metadata URL
171    // embeds the slug. (A response addressed to a DIFFERENT audience fails
172    // the audience check below after the org is resolved from it.)
173    const audienceMatch = /<saml:Audience>([^<]+)<\/saml:Audience>/.exec(xml);
174    const slugFromAudience = audienceMatch ? audienceMatch[1].match(/saml\/metadata\/([^"<>?\s]+)$/) : null;
175    const org = slugFromAudience
176      ? await this.prisma.organization.findUnique({ where: { slug: slugFromAudience[1] } })
177      : null;
178    if (!org) {
179      await this.audit.audit(req, undefined, {
180        action: "sso.login_failed",
181        resourceType: "user",
182        resourceId: "saml",
183        metadata: { reason: "no_sso_provider" }
184      });
185      redirectTo("sso_unknown_org");
186      return;
187    }
188    const provider = await this.prisma.ssoProvider.findUnique({ where: { organizationId: org.id } });
189    if (!provider || provider.type !== "SAML") {
190      await this.audit.audit(req, undefined, {
191        action: "sso.login_failed",
192        resourceType: "user",
193        resourceId: org.slug,
194        metadata: { reason: "no_sso_provider" }
195      });
196      redirectTo("sso_unknown_org", org.slug);
197      return;
198    }
199    const config = SamlConfigSchema.parse(provider.config);
200    const secrets = await this.secrets.getSecrets(org.id);
201    const certificates = [secrets.certificate, secrets.previousCertificate].filter(
202      (c): c is string => Boolean(c)
203    );
204    if (!certificates.length) {
205      await this.audit.audit(req, undefined, {
206        action: "sso.login_failed",
207        resourceType: "user",
208        resourceId: org.slug,
209        metadata: { reason: "no_certificate_configured" }
210      });
211      redirectTo("sso_misconfigured", org.slug);
212      return;
213    }
214 
215    const result = validateAuthnResponse(xml, {
216      entityId: this.spEntityId(org.slug),
217      acsUrl: `${this.origin()}/saml/acs`,
218      issuer: config.idpEntityId,
219      certificates,
220      nameIdAttribute: config.nameIdAttribute,
221      emailAttribute: config.emailAttribute
222    });
223    if (!result.ok) {
224      await this.audit.audit(req, undefined, {
225        action: "sso.login_failed",
226        resourceType: "user",
227        resourceId: org.slug,
228        metadata: { reason: result.reason, detail: result.detail ?? null }
229      });
230      redirectTo(`sso_${result.reason}`, org.slug);
231      return;
232    }
233 
234    // Replay protection (AFTER the checks above — a forged assertion must
235    // not consume a replay slot): the Response ID is single-use for 10 min.
236    const replayKey = `sso:replay:${result.data.id}`;
237    let seen: string | null = null;
238    try {
239      seen = await this.redis.getRedis().set(replayKey, "1", "EX", REPLAY_TTL_SECONDS, "NX");
240    } catch {
241      // Redis down: fail OPEN for availability but log (the 10-min window
242      // is a replay bound, not the primary trust anchor — the signature is).
243      await this.audit.audit(req, undefined, {
244        action: "sso.login_failed",
245        resourceType: "user",
246        resourceId: org.slug,
247        metadata: { reason: "replay_store_unavailable" }
248      });
249    }
250    if (seen === null) {
251      await this.audit.audit(req, undefined, {
252        action: "sso.login_failed",
253        resourceType: "user",
254        resourceId: org.slug,
255        metadata: { reason: "replayed", responseId: result.data.id }
256      });
257      redirectTo("sso_replayed", org.slug);
258      return;
259    }
260 
261    // Provision + session (audit `sso.login.saml` happens inside).
262    try {
263      await this.provisioning.provision({
264        req,
265        res,
266        organizationId: org.id,
267        provider: {
268          id: provider.id,
269          type: "SAML",
270          name: provider.name,
271          config: provider.config as Record<string, unknown>
272        },
273        externalId: result.data.nameId,
274        email: result.data.email ?? result.data.nameId,
275        displayName: result.data.attributes.displayName ?? result.data.attributes.name ?? null,
276        claims: result.data.attributes
277      });
278    } catch (err) {
279      // provision() throws ApiError.forbidden with the specific reason in
280      // details[0].detail (and audits sso.login_failed itself).
281      const detail =
282        err instanceof ApiError
283          ? (err.details?.[0]?.detail as string | undefined)
284          : "provisioning_failed";
285      redirectTo(`sso_${detail ?? "provisioning_failed"}`, org.slug);
286      return;
287    }
288 
289    // Success: redirect to the RelayState (open-redirect safe) or home.
290    // The target is a WEB page (the app), so the WEB origin — not the API
291    // origin that serves the ACS itself.
292    const relay = body?.RelayState;
293    const target = relay && relay.startsWith("/") && !relay.startsWith("//") ? relay : "/w/default";
294    res.status(302).header("location", this.webOrigin() + target).end();
295  }
296}
297