feat(core): add PATCH/GET /saml-applications/:id APIs

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

@@ -0,0 +1,98 @@
+import {
+  ApplicationType,
+  type SamlApplicationResponse,
+  type PatchSamlApplication,
+} from '@logto/schemas';
+import { generateStandardId } from '@logto/shared';
+import { removeUndefinedKeys } from '@silverhand/essentials';
+
+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';
+
+export const createSamlApplicationsLibrary = (queries: Queries) => {
+  const {
+    applications: { findApplicationById, updateApplicationById },
+    samlApplicationSecrets: { insertSamlApplicationSecret },
+    samlApplicationConfigs: {
+      findSamlApplicationConfigByApplicationId,
+      updateSamlApplicationConfig,
+    },
+  } = queries;
+
+  const createSamlApplicationSecret = async (
+    applicationId: string,
+    // Set certificate life span to 1 year by default.
+    lifeSpanInDays = 365
+  ) => {
+    const { privateKey, certificate, notAfter } = await generateKeyPairAndCertificate(
+      lifeSpanInDays
+    );
+
+    return insertSamlApplicationSecret({
+      id: generateStandardId(),
+      applicationId,
+      privateKey,
+      certificate,
+      expiresAt: Math.floor(notAfter.getTime() / 1000),
+      active: false,
+    });
+  };
+
+  const findSamlApplicationById = async (id: string): Promise<SamlApplicationResponse> => {
+    const application = await findApplicationById(id);
+    assertThat(
+      application.type === ApplicationType.SAML,
+      new RequestError({
+        code: 'application.saml.saml_application_only',
+        status: 422,
+      })
+    );
+
+    const samlConfig = await findSamlApplicationConfigByApplicationId(application.id);
+
+    return ensembleSamlApplication({ application, samlConfig });
+  };
+
+  const updateSamlApplicationById = async (
+    id: string,
+    patchApplicationObject: PatchSamlApplication
+  ): Promise<SamlApplicationResponse> => {
+    const { config, ...applicationData } = patchApplicationObject;
+    const originalApplication = await findApplicationById(id);
+
+    assertThat(
+      originalApplication.type === ApplicationType.SAML,
+      new RequestError({
+        code: 'application.saml.saml_application_only',
+        status: 422,
+      })
+    );
+
+    const [updatedApplication, upToDateSamlConfig] = await Promise.all([
+      Object.keys(applicationData).length > 0
+        ? updateApplicationById(id, removeUndefinedKeys(applicationData))
+        : originalApplication,
+      config
+        ? updateSamlApplicationConfig({
+            set: config,
+            where: { applicationId: id },
+            jsonbMode: 'replace',
+          })
+        : findSamlApplicationConfigByApplicationId(id),
+    ]);
+
+    return ensembleSamlApplication({
+      application: updatedApplication,
+      samlConfig: upToDateSamlConfig,
+    });
+  };
+
+  return {
+    createSamlApplicationSecret,
+    findSamlApplicationById,
+    updateSamlApplicationById,
+  };
+};

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

@@ -1,8 +1,18 @@
 import crypto from 'node:crypto';
 
+import {
+  type SamlApplicationResponse,
+  type Application,
+  type SamlApplicationConfig,
+  type SamlAcsUrl,
+  BindingType,
+} from '@logto/schemas';
 import { addDays } from 'date-fns';
 import forge from 'node-forge';
 
+import RequestError from '#src/errors/RequestError/index.js';
+import assertThat from '#src/utils/assert-that.js';
+
 export const generateKeyPairAndCertificate = async (lifeSpanInDays = 365) => {
   const keypair = forge.pki.rsa.generateKeyPair({ bits: 4096 });
   return createCertificate(keypair, lifeSpanInDays);
@@ -23,7 +33,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',
@@ -56,3 +66,36 @@
     notAfter,
   };
 };
+
+/**
+ * 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:
+ * - A record from the `applications` table with a `type` of `SAML`
+ * - A record from the `saml_application_configs` table
+ */
+export const ensembleSamlApplication = ({
+  application,
+  samlConfig,
+}: {
+  application: Application;
+  samlConfig: Pick<SamlApplicationConfig, 'attributeMapping' | 'entityId' | 'acsUrl'>;
+}): SamlApplicationResponse => {
+  return {
+    ...application,
+    ...samlConfig,
+  };
+};
+
+/**
+ * Only HTTP-POST binding is supported for receiving SAML assertions at the moment.
+ */
+export const validateAcsUrl = (acsUrl: SamlAcsUrl) => {
+  const { binding } = acsUrl;
+  assertThat(
+    binding === BindingType.POST,
+    new RequestError({
+      code: 'application.saml.acs_url_binding_not_supported',
+      status: 422,
+    })
+  );
+};

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

@@ -16,7 +16,7 @@
   const updateSamlApplicationConfig = buildUpdateWhereWithPool(pool)(SamlApplicationConfigs, true);
 
   const findSamlApplicationConfigByApplicationId = async (applicationId: string) =>
-    pool.maybeOne<SamlApplicationConfig>(sql`
+    pool.one<SamlApplicationConfig>(sql`
       select ${sql.join(Object.values(fields), sql`, `)}
       from ${table}
       where ${fields.applicationId}=${applicationId}

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

@@ -1,19 +1,22 @@
 import {
   ApplicationType,
   samlApplicationCreateGuard,
+  samlApplicationPatchGuard,
   samlApplicationResponseGuard,
 } from '@logto/schemas';
 import { generateStandardId } from '@logto/shared';
 import { removeUndefinedKeys } from '@silverhand/essentials';
 import { z } from 'zod';
 
+import RequestError from '#src/errors/RequestError/index.js';
 import koaGuard from '#src/middleware/koa-guard.js';
 import { buildOidcClientMetadata } from '#src/oidc/utils.js';
 import { generateInternalSecret } from '#src/routes/applications/application-secret.js';
 import type { ManagementApiRouter, RouterInitArgs } from '#src/routes/types.js';
-import { ensembleSamlApplication, validateAcsUrl } from '#src/saml-applications/routes/utils.js';
 import assertThat from '#src/utils/assert-that.js';
 
+import { ensembleSamlApplication, validateAcsUrl } from '../libraries/utils.js';
+
 export default function samlApplicationRoutes<T extends ManagementApiRouter>(
   ...[router, { queries, libraries }]: RouterInitArgs<T>
 ) {
@@ -22,15 +25,19 @@
     samlApplicationConfigs: { insertSamlApplicationConfig },
   } = queries;
   const {
-    samlApplicationSecrets: { createSamlApplicationSecret },
+    samlApplications: {
+      createSamlApplicationSecret,
+      findSamlApplicationById,
+      updateSamlApplicationById,
+    },
   } = libraries;
 
   router.post(
     '/saml-applications',
     koaGuard({
       body: samlApplicationCreateGuard,
       response: samlApplicationResponseGuard,
-      status: [201, 400],
+      status: [201, 400, 422],
     }),
     async (ctx, next) => {
       const { name, description, customData, config } = ctx.guard.body;
@@ -72,17 +79,64 @@
     }
   );
 
+  router.get(
+    '/saml-applications/:id',
+    koaGuard({
+      params: z.object({
+        id: z.string(),
+      }),
+      response: samlApplicationResponseGuard,
+      status: [200, 404, 422],
+    }),
+    async (ctx, next) => {
+      const { id } = ctx.guard.params;
+
+      const samlApplication = await findSamlApplicationById(id);
+
+      ctx.status = 200;
+      ctx.body = samlApplication;
+
+      return next();
+    }
+  );
+
+  router.patch(
+    '/saml-applications/:id',
+    koaGuard({
+      params: z.object({ id: z.string() }),
+      body: samlApplicationPatchGuard,
+      response: samlApplicationResponseGuard,
+      status: [200, 404, 422],
+    }),
+    async (ctx, next) => {
+      const { id } = ctx.guard.params;
+
+      const updatedSamlApplication = await updateSamlApplicationById(id, ctx.guard.body);
+
+      ctx.status = 200;
+      ctx.body = updatedSamlApplication;
+
+      return next();
+    }
+  );
+
   router.delete(
     '/saml-applications/:id',
     koaGuard({
       params: z.object({ id: z.string() }),
-      status: [204, 400, 404],
+      status: [204, 422, 404],
     }),
     async (ctx, next) => {
       const { id } = ctx.guard.params;
 
       const { type } = await findApplicationById(id);
-      assertThat(type === ApplicationType.SAML, 'application.saml.saml_application_only');
+      assertThat(
+        type === ApplicationType.SAML,
+        new RequestError({
+          code: 'application.saml.saml_application_only',
+          status: 422,
+        })
+      );
 
       await deleteApplicationById(id);
 

packages/core/src/tenants/Libraries.ts

@@ -17,7 +17,7 @@
 import { createSsoConnectorLibrary } from '#src/libraries/sso-connector.js';
 import { createUserLibrary } from '#src/libraries/user.js';
 import { createVerificationStatusLibrary } from '#src/libraries/verification-status.js';
-import { createSamlApplicationSecretsLibrary } from '#src/saml-applications/libraries/secrets.js';
+import { createSamlApplicationsLibrary } from '#src/saml-applications/libraries/saml-applications.js';
 
 import type Queries from './Queries.js';
 
@@ -38,7 +38,7 @@
   passcodes = createPasscodeLibrary(this.queries, this.connectors);
   applications = createApplicationLibrary(this.queries);
   verificationStatuses = createVerificationStatusLibrary(this.queries);
-  samlApplicationSecrets = createSamlApplicationSecretsLibrary(this.queries);
+  samlApplications = createSamlApplicationsLibrary(this.queries);
   roleScopes = createRoleScopeLibrary(this.queries);
   domains = createDomainLibrary(this.queries);
   protectedApps = createProtectedAppLibrary(this.queries);
@@ -58,7 +58,7 @@
     this.connectors
   );
 
   constructor(
     public readonly tenantId: string,
     private readonly queries: Queries,
     // Explicitly passing connector library to eliminate dependency issue

packages/integration-tests/src/api/saml-application.ts

@@ -1,4 +1,8 @@
-import { type SamlApplicationResponse, type CreateSamlApplication } from '@logto/schemas';
+import {
+  type SamlApplicationResponse,
+  type CreateSamlApplication,
+  type PatchSamlApplication,
+} from '@logto/schemas';
 
 import { authedAdminApi } from './api.js';
 
@@ -11,3 +15,14 @@ export const createSamlApplication = async (createSamlApplication: CreateSamlApp
 
 export const deleteSamlApplication = async (id: string) =>
   authedAdminApi.delete(`saml-applications/${id}`);
+
+export const updateSamlApplication = async (
+  id: string,
+  patchSamlApplication: PatchSamlApplication
+) =>
+  authedAdminApi
+    .patch(`saml-applications/${id}`, { json: patchSamlApplication })
+    .json<SamlApplicationResponse>();
+
+export const getSamlApplication = async (id: string) =>
+  authedAdminApi.get(`saml-applications/${id}`).json<SamlApplicationResponse>();