feat: add SAML app anonymous metadata and certificate APIs

packages/core/src/routes/init.ts

@@ -7,6 +7,7 @@
 import koaBodyEtag from '#src/middleware/koa-body-etag.js';
 import { koaManagementApiHooks } from '#src/middleware/koa-management-api-hooks.js';
 import koaTenantGuard from '#src/middleware/koa-tenant-guard.js';
+import samlApplicationAnonymousRoutes from '#src/saml-applications/routes/anonymous.js';
 import samlApplicationRoutes from '#src/saml-applications/routes/index.js';
 import type TenantContext from '#src/tenants/TenantContext.js';
 
@@ -68,7 +69,7 @@
   managementRouter.use(koaTenantGuard(tenant.id, tenant.queries));
   managementRouter.use(koaManagementApiHooks(tenant.libraries.hooks));
 
   // TODO: FIXME @sijie @darcy mount these routes in `applicationRoutes` instead
   applicationRoutes(managementRouter, tenant);
   applicationRoleRoutes(managementRouter, tenant);
   applicationProtectedAppMetadataRoutes(managementRouter, tenant);
@@ -100,7 +101,7 @@
   systemRoutes(managementRouter, tenant);
   subjectTokenRoutes(managementRouter, tenant);
   accountCentersRoutes(managementRouter, tenant);
   // TODO: @darcy per our design, we will move related routes to Cloud repo and the routes will be loaded from remote.
   if (
     (EnvSet.values.isDevFeaturesEnabled && EnvSet.values.isCloud) ||
     EnvSet.values.isIntegrationTest
@@ -112,7 +113,7 @@
 
   const userRouter: UserRouter = new Router();
   userRouter.use(koaOidcAuth(tenant));
   // TODO(LOG-10147): Rename to koaApiHooks, this middleware is used for both management API and user API
   userRouter.use(koaManagementApiHooks(tenant.libraries.hooks));
   accountRoutes(userRouter, tenant);
   verificationRoutes(userRouter, tenant);
@@ -120,6 +121,13 @@
   wellKnownRoutes(anonymousRouter, tenant);
   statusRoutes(anonymousRouter, tenant);
   authnRoutes(anonymousRouter, tenant);
+  // TODO: @darcy per our design, we will move related routes to Cloud repo and the routes will be loaded from remote.
+  if (
+    (EnvSet.values.isDevFeaturesEnabled && EnvSet.values.isCloud) ||
+    EnvSet.values.isIntegrationTest
+  ) {
+    samlApplicationAnonymousRoutes(anonymousRouter, tenant);
+  }
 
   wellKnownOpenApiRoutes(anonymousRouter, {
     experienceRouters: [experienceRouter, interactionRouter],
@@ -133,7 +141,7 @@
     anonymousRouter,
     experienceRouter,
     userRouter,
     // TODO: interactionRouter should be removed from swagger.json
     interactionRouter,
   ]);
 

packages/core/src/saml-applications/libraries/saml-applications.ts

@@ -3,20 +3,30 @@
   type SamlApplicationResponse,
   type PatchSamlApplication,
   type SamlApplicationSecret,
+  BindingType,
 } from '@logto/schemas';
 import { generateStandardId } from '@logto/shared';
 import { removeUndefinedKeys } from '@silverhand/essentials';
+import * as saml from 'samlify';
 
+import { EnvSet, getTenantEndpoint } from '#src/env-set/index.js';
 import RequestError from '#src/errors/RequestError/index.js';
 import type Queries from '#src/tenants/Queries.js';
 import assertThat from '#src/utils/assert-that.js';
 
-import { ensembleSamlApplication, generateKeyPairAndCertificate } from './utils.js';
+import {
+  ensembleSamlApplication,
+  generateKeyPairAndCertificate,
+  buildSingleSignOnUrl,
+} from './utils.js';
 
 export const createSamlApplicationsLibrary = (queries: Queries) => {
   const {
     applications: { findApplicationById, updateApplicationById },
-    samlApplicationSecrets: { insertSamlApplicationSecret },
+    samlApplicationSecrets: {
+      insertSamlApplicationSecret,
+      findActiveSamlApplicationSecretByApplicationId,
+    },
     samlApplicationConfigs: {
       findSamlApplicationConfigByApplicationId,
       updateSamlApplicationConfig,
@@ -25,8 +35,8 @@
 
   const createSamlApplicationSecret = async (
     applicationId: string,
-    // Set certificate life span to 1 year by default.
-    lifeSpanInDays = 365
+    // Set certificate life span to 3 years by default.
+    lifeSpanInDays = 365 * 3
   ): Promise<SamlApplicationSecret> => {
     const { privateKey, certificate, notAfter } = await generateKeyPairAndCertificate(
       lifeSpanInDays
@@ -37,7 +47,7 @@
       applicationId,
       privateKey,
       certificate,
-      expiresAt: Math.floor(notAfter.getTime() / 1000),
+      expiresAt: notAfter.getTime(),
       active: false,
     });
   };
@@ -91,9 +101,37 @@
     });
   };
 
+  const getSamlIdPMetadataByApplicationId = async (id: string): Promise<{ metadata: string }> => {
+    const [{ tenantId, entityId }, { certificate }] = await Promise.all([
+      findSamlApplicationConfigByApplicationId(id),
+      findActiveSamlApplicationSecretByApplicationId(id),
+    ]);
+
+    assertThat(entityId, 'application.saml.entity_id_required');
+
+    const tenantEndpoint = getTenantEndpoint(tenantId, EnvSet.values);
+
+    // eslint-disable-next-line new-cap
+    const idp = saml.IdentityProvider({
+      entityID: entityId,
+      signingCert: certificate,
+      singleSignOnService: [
+        {
+          Location: buildSingleSignOnUrl(tenantEndpoint, id),
+          Binding: BindingType.Redirect,
+        },
+      ],
+    });
+
+    return {
+      metadata: idp.getMetadata(),
+    };
+  };
+
   return {
     createSamlApplicationSecret,
     findSamlApplicationById,
     updateSamlApplicationById,
+    getSamlIdPMetadataByApplicationId,
   };
 };

packages/core/src/saml-applications/libraries/utils.test.ts

@@ -1,7 +1,9 @@
 import { addDays } from 'date-fns';
 import forge from 'node-forge';
 
-import { generateKeyPairAndCertificate } from './utils.js';
+import RequestError from '#src/errors/RequestError/index.js';
+
+import { generateKeyPairAndCertificate, calculateCertificateFingerprints } from './utils.js';
 
 describe('generateKeyPairAndCertificate', () => {
   it('should generate valid key pair and certificate', async () => {
@@ -57,3 +59,69 @@ describe('generateKeyPairAndCertificate', () => {
     expect(forge.pki.privateKeyToPem(privateKey).length).toBeGreaterThan(3000); // A 4096-bit RSA private key in PEM format is typically longer than 3000 characters
   });
 });
+
+describe('calculateCertificateFingerprints', () => {
+  // eslint-disable-next-line @silverhand/fp/no-let
+  let validCertificate: string;
+
+  beforeAll(async () => {
+    // Generate a valid certificate for testing
+    const { certificate } = await generateKeyPairAndCertificate();
+    // eslint-disable-next-line @silverhand/fp/no-mutation
+    validCertificate = certificate;
+  });
+
+  it('should calculate correct fingerprints for valid certificate', () => {
+    const fingerprints = calculateCertificateFingerprints(validCertificate);
+
+    // Verify fingerprint format
+    expect(fingerprints.sha256.formatted).toMatch(/^([\dA-F]{2}:){31}[\dA-F]{2}$/);
+    expect(fingerprints.sha256.unformatted).toMatch(/^[\dA-F]{64}$/);
+
+    // Verify formatted and unformatted consistency
+    expect(fingerprints.sha256.unformatted).toBe(fingerprints.sha256.formatted.replaceAll(':', ''));
+  });
+
+  it('should throw error for invalid PEM format', () => {
+    const invalidCertificates = [
+      'not a certificate',
+      '-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n',
+      // Missing begin/end markers
+      'MIIFWjCCA0KgAwIBAgIUMDAwMDAwMDAwMDAwMDAwMDAwMDAwDQYJKoZIhvcNAQEL',
+    ];
+
+    for (const cert of invalidCertificates) {
+      expect(() => calculateCertificateFingerprints(cert)).toThrow(
+        new RequestError('application.saml.invalid_certificate_pem_format')
+      );
+    }
+  });
+
+  it('should throw error for invalid base64 content', () => {
+    const invalidBase64Certificate =
+      '-----BEGIN CERTIFICATE-----\n' +
+      'This is not base64!@#$%^&*()\n' +
+      '-----END CERTIFICATE-----\n';
+
+    expect(() => calculateCertificateFingerprints(invalidBase64Certificate)).toThrow(
+      new RequestError('application.saml.invalid_certificate_pem_format')
+    );
+  });
+
+  it('should handle certificates with different line endings', () => {
+    // Replace \n with \r\n in valid certificate
+    const crlfCertificate = validCertificate.replaceAll('\n', '\r\n');
+
+    const originalFingerprints = calculateCertificateFingerprints(validCertificate);
+    const crlfFingerprints = calculateCertificateFingerprints(crlfCertificate);
+
+    expect(crlfFingerprints).toEqual(originalFingerprints);
+  });
+
+  it('should calculate consistent fingerprints for the same certificate', () => {
+    const firstResult = calculateCertificateFingerprints(validCertificate);
+    const secondResult = calculateCertificateFingerprints(validCertificate);
+
+    expect(firstResult).toEqual(secondResult);
+  });
+});

packages/core/src/saml-applications/libraries/utils.ts

@@ -6,13 +6,25 @@
   type SamlApplicationConfig,
   type SamlAcsUrl,
   BindingType,
+  type CertificateFingerprints,
 } from '@logto/schemas';
+import { appendPath } from '@silverhand/essentials';
 import { addDays } from 'date-fns';
 import forge from 'node-forge';
+import { z } from 'zod';
 
 import RequestError from '#src/errors/RequestError/index.js';
 import assertThat from '#src/utils/assert-that.js';
 
+// Add PEM certificate validation
+const pemCertificateGuard = z
+  .string()
+  .trim()
+  .regex(/^-{5}BEGIN CERTIFICATE-{5}[\n\r]+[\S\s]*?[\n\r]+-{5}END CERTIFICATE-{5}$/);
+
+// Add base64 validation schema
+const base64Guard = z.string().regex(/^[\d+/A-Za-z]*={0,2}$/);
+
 export const generateKeyPairAndCertificate = async (lifeSpanInDays = 365) => {
   const keypair = forge.pki.rsa.generateKeyPair({ bits: 4096 });
   return createCertificate(keypair, lifeSpanInDays);
@@ -33,7 +45,7 @@
   cert.validity.notAfter = notAfter;
   /* eslint-enable @silverhand/fp/no-mutation */
 
   // TODO: read from tenant config or let user customize before downloading
   const subjectAttributes: forge.pki.CertificateField[] = [
     {
       name: 'commonName',
@@ -67,6 +79,44 @@
   };
 };
 
+export const calculateCertificateFingerprints = (
+  pemCertificate: string
+): CertificateFingerprints => {
+  try {
+    // Validate PEM certificate format
+    pemCertificateGuard.parse(pemCertificate);
+
+    // Remove PEM headers, newlines and spaces
+    const cleanedPem = pemCertificate
+      .replace('-----BEGIN CERTIFICATE-----', '')
+      .replace('-----END CERTIFICATE-----', '')
+      .replaceAll(/\s/g, '');
+
+    // Validate base64 format using zod
+    base64Guard.parse(cleanedPem);
+
+    // Convert base64 to binary
+    const certDer = Buffer.from(cleanedPem, 'base64');
+
+    // Calculate SHA-256 fingerprint
+    const sha256Unformatted = crypto
+      .createHash('sha256')
+      .update(certDer)
+      .digest('hex')
+      .toUpperCase();
+    const sha256Formatted = sha256Unformatted.match(/.{2}/g)?.join(':') ?? '';
+
+    return {
+      sha256: {
+        formatted: sha256Formatted,
+        unformatted: sha256Unformatted,
+      },
+    };
+  } catch {
+    throw new RequestError('application.saml.invalid_certificate_pem_format');
+  }
+};
+
 /**
  * According to the design, a SAML app will be associated with multiple records from various tables.
  * Therefore, when complete SAML app data is required, it is necessary to retrieve multiple related records and assemble them into a comprehensive SAML app dataset. This dataset includes:
@@ -92,10 +142,13 @@
 export const validateAcsUrl = (acsUrl: SamlAcsUrl) => {
   const { binding } = acsUrl;
   assertThat(
-    binding === BindingType.POST,
+    binding === BindingType.Post,
     new RequestError({
       code: 'application.saml.acs_url_binding_not_supported',
       status: 422,
     })
   );
 };
+
+export const buildSingleSignOnUrl = (baseUrl: URL, samlApplicationId: string) =>
+  appendPath(baseUrl, `api/saml/${samlApplicationId}/authn`).toString();

packages/core/src/saml-applications/queries/configs.ts

@@ -18,11 +18,6 @@ export const createSamlApplicationConfigQueries = (pool: CommonQueryMethods) =>
   const findSamlApplicationConfigByApplicationId = async (applicationId: string) =>
     /**
      * @remarks
-     * 这里我们使用了 `.one()` 方法 instead of `.maybeOne()` 方法，是因为我们在创建 SAML app 时，直接会创建一条对应的 SAML config 记录。这样在后续我们通过 API 操作 SAML app 的 config 时，不需要额外判断：
-     * 1. 是否需要插入 SAML config（一个 alternative 是，在创建 SAML app 时，不插入一条 SAML config 记录，在 PATCH 时，使用 insert into ... on conflict 的 query 来达到同样的目的）
-     * 2. 在 SAML app 对应的 config 不存在时，GET 方法需要对 null 的 SAML config 进行额外的处理
-     * 根据我们的设计，如果在创建 SAML app 时，就同时创建一条 SAML config 记录，在之后的所有场景中，我们只涉及对这条 DB 记录的 update 操作。在我们的业务场景中，没有手动对 SAML config 记录的 delete 操作。
-     *
      * Here we use the `.one()` method instead of the `.maybeOne()` method because when creating a SAML app, we directly create a corresponding SAML config record. This means that in subsequent API operations on the SAML app's config, we don't need additional checks:
      * 1. Whether to insert a SAML config (an alternative approach is not to insert a SAML config record when creating the SAML app, and use an `insert into ... on conflict` query during PATCH to achieve the same result).
      * 2. When the corresponding config for the SAML app does not exist, the GET method needs to handle the null SAML config additionally.

packages/core/src/saml-applications/queries/secrets.ts

@@ -3,6 +3,7 @@
 import { sql } from '@silverhand/slonik';
 
 import { buildInsertIntoWithPool } from '#src/database/insert-into.js';
+import RequestError from '#src/errors/RequestError/index.js';
 import { DeletionError } from '#src/errors/SlonikError/index.js';
 import { convertToIdentifiers } from '#src/utils/sql.js';
 
@@ -20,6 +21,22 @@
       where ${fields.applicationId}=${applicationId}
     `);
 
+  const findActiveSamlApplicationSecretByApplicationId = async (
+    applicationId: string
+  ): Promise<SamlApplicationSecret> => {
+    const activeSecret = await pool.maybeOne<SamlApplicationSecret>(sql`
+      select ${sql.join(Object.values(fields), sql`, `)}
+      from ${table}
+      where ${fields.applicationId}=${applicationId} and ${fields.active}=true
+    `);
+
+    if (!activeSecret) {
+      throw new RequestError({ code: 'application.saml.no_active_secret', status: 404 });
+    }
+
+    return activeSecret;
+  };
+
   const findSamlApplicationSecretByApplicationIdAndId = async (applicationId: string, id: string) =>
     pool.one<SamlApplicationSecret>(sql`
       select ${sql.join(Object.values(fields), sql`, `)}
@@ -68,6 +85,7 @@
   return {
     insertSamlApplicationSecret,
     findSamlApplicationSecretsByApplicationId,
+    findActiveSamlApplicationSecretByApplicationId,
     findSamlApplicationSecretByApplicationIdAndId,
     deleteSamlApplicationSecretById,
     updateSamlApplicationSecretStatusByApplicationIdAndSecretId,

packages/core/src/saml-applications/routes/anonymous.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+
+import koaGuard from '#src/middleware/koa-guard.js';
+import type { AnonymousRouter, RouterInitArgs } from '#src/routes/types.js';
+
+export default function samlApplicationAnonymousRoutes<T extends AnonymousRouter>(
+  ...[router, { libraries }]: RouterInitArgs<T>
+) {
+  const {
+    samlApplications: { getSamlIdPMetadataByApplicationId },
+  } = libraries;
+
+  router.get(
+    '/saml-applications/:id/metadata',
+    koaGuard({
+      params: z.object({ id: z.string() }),
+      status: [200, 400, 404],
+      response: z.string(),
+    }),
+    async (ctx, next) => {
+      const { id } = ctx.guard.params;
+
+      const { metadata } = await getSamlIdPMetadataByApplicationId(id);
+
+      ctx.status = 200;
+      ctx.body = metadata;
+      ctx.type = 'text/xml;charset=utf-8';
+
+      return next();
+    }
+  );
+}