Merge pull request #3890 from Infisical/daniel/sso-endpoints-docs

docs(api-reference/organizations): document SSO configuration endpoints

backend/src/ee/routes/v1/ldap-router.ts

@@ -17,6 +17,7 @@ import { z } from "zod";
 import { LdapGroupMapsSchema } from "@app/db/schemas";
 import { TLDAPConfig } from "@app/ee/services/ldap-config/ldap-config-types";
 import { isValidLdapFilter, searchGroups } from "@app/ee/services/ldap-config/ldap-fns";
+import { ApiDocsTags, LdapSso } from "@app/lib/api-docs";
 import { getConfig } from "@app/lib/config/env";
 import { BadRequestError } from "@app/lib/errors";
 import { logger } from "@app/lib/logger";
@@ -132,10 +133,18 @@ export const registerLdapRouter = async (server: FastifyZodProvider) => {
     config: {
       rateLimit: readLimit
     },
-    onRequest: verifyAuth([AuthMode.JWT]),
+    onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]),
     schema: {
+      hide: false,
+      tags: [ApiDocsTags.LdapSso],
+      description: "Get LDAP config",
+      security: [
+        {
+          bearerAuth: []
+        }
+      ],
       querystring: z.object({
-        organizationId: z.string().trim()
+        organizationId: z.string().trim().describe(LdapSso.GET_CONFIG.organizationId)
       }),
       response: {
         200: z.object({
@@ -172,23 +181,32 @@ export const registerLdapRouter = async (server: FastifyZodProvider) => {
     config: {
       rateLimit: writeLimit
     },
-    onRequest: verifyAuth([AuthMode.JWT]),
+    onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]),
     schema: {
+      hide: false,
+      tags: [ApiDocsTags.LdapSso],
+      description: "Create LDAP config",
+      security: [
+        {
+          bearerAuth: []
+        }
+      ],
       body: z.object({
-        organizationId: z.string().trim(),
-        isActive: z.boolean(),
-        url: z.string().trim(),
-        bindDN: z.string().trim(),
-        bindPass: z.string().trim(),
-        uniqueUserAttribute: z.string().trim().default("uidNumber"),
-        searchBase: z.string().trim(),
-        searchFilter: z.string().trim().default("(uid={{username}})"),
-        groupSearchBase: z.string().trim(),
+        organizationId: z.string().trim().describe(LdapSso.CREATE_CONFIG.organizationId),
+        isActive: z.boolean().describe(LdapSso.CREATE_CONFIG.isActive),
+        url: z.string().trim().describe(LdapSso.CREATE_CONFIG.url),
+        bindDN: z.string().trim().describe(LdapSso.CREATE_CONFIG.bindDN),
+        bindPass: z.string().trim().describe(LdapSso.CREATE_CONFIG.bindPass),
+        uniqueUserAttribute: z.string().trim().default("uidNumber").describe(LdapSso.CREATE_CONFIG.uniqueUserAttribute),
+        searchBase: z.string().trim().describe(LdapSso.CREATE_CONFIG.searchBase),
+        searchFilter: z.string().trim().default("(uid={{username}})").describe(LdapSso.CREATE_CONFIG.searchFilter),
+        groupSearchBase: z.string().trim().describe(LdapSso.CREATE_CONFIG.groupSearchBase),
         groupSearchFilter: z
           .string()
           .trim()
-          .default("(|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}}))"),
-        caCert: z.string().trim().default("")
+          .default("(|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}}))")
+          .describe(LdapSso.CREATE_CONFIG.groupSearchFilter),
+        caCert: z.string().trim().default("").describe(LdapSso.CREATE_CONFIG.caCert)
       }),
       response: {
         200: SanitizedLdapConfigSchema
@@ -214,23 +232,31 @@ export const registerLdapRouter = async (server: FastifyZodProvider) => {
     config: {
       rateLimit: writeLimit
     },
-    onRequest: verifyAuth([AuthMode.JWT]),
+    onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]),
     schema: {
+      hide: false,
+      tags: [ApiDocsTags.LdapSso],
+      description: "Update LDAP config",
+      security: [
+        {
+          bearerAuth: []
+        }
+      ],
       body: z
         .object({
-          isActive: z.boolean(),
-          url: z.string().trim(),
-          bindDN: z.string().trim(),
-          bindPass: z.string().trim(),
-          uniqueUserAttribute: z.string().trim(),
-          searchBase: z.string().trim(),
-          searchFilter: z.string().trim(),
-          groupSearchBase: z.string().trim(),
-          groupSearchFilter: z.string().trim(),
-          caCert: z.string().trim()
+          isActive: z.boolean().describe(LdapSso.UPDATE_CONFIG.isActive),
+          url: z.string().trim().describe(LdapSso.UPDATE_CONFIG.url),
+          bindDN: z.string().trim().describe(LdapSso.UPDATE_CONFIG.bindDN),
+          bindPass: z.string().trim().describe(LdapSso.UPDATE_CONFIG.bindPass),
+          uniqueUserAttribute: z.string().trim().describe(LdapSso.UPDATE_CONFIG.uniqueUserAttribute),
+          searchBase: z.string().trim().describe(LdapSso.UPDATE_CONFIG.searchBase),
+          searchFilter: z.string().trim().describe(LdapSso.UPDATE_CONFIG.searchFilter),
+          groupSearchBase: z.string().trim().describe(LdapSso.UPDATE_CONFIG.groupSearchBase),
+          groupSearchFilter: z.string().trim().describe(LdapSso.UPDATE_CONFIG.groupSearchFilter),
+          caCert: z.string().trim().describe(LdapSso.UPDATE_CONFIG.caCert)
         })
         .partial()
-        .merge(z.object({ organizationId: z.string() })),
+        .merge(z.object({ organizationId: z.string().trim().describe(LdapSso.UPDATE_CONFIG.organizationId) })),
       response: {
         200: SanitizedLdapConfigSchema
       }

backend/src/ee/routes/v1/oidc-router.ts

@@ -13,6 +13,7 @@ import { z } from "zod";
 
 import { OidcConfigsSchema } from "@app/db/schemas";
 import { OIDCConfigurationType, OIDCJWTSignatureAlgorithm } from "@app/ee/services/oidc/oidc-config-types";
+import { ApiDocsTags, OidcSSo } from "@app/lib/api-docs";
 import { getConfig } from "@app/lib/config/env";
 import { authRateLimit, readLimit, writeLimit } from "@app/server/config/rateLimiter";
 import { verifyAuth } from "@app/server/plugins/auth/verify-auth";
@@ -153,10 +154,18 @@ export const registerOidcRouter = async (server: FastifyZodProvider) => {
     config: {
       rateLimit: readLimit
     },
-    onRequest: verifyAuth([AuthMode.JWT]),
+    onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]),
     schema: {
+      hide: false,
+      tags: [ApiDocsTags.OidcSso],
+      description: "Get OIDC config",
+      security: [
+        {
+          bearerAuth: []
+        }
+      ],
       querystring: z.object({
-        orgSlug: z.string().trim()
+        organizationId: z.string().trim().describe(OidcSSo.GET_CONFIG.organizationId)
       }),
       response: {
         200: SanitizedOidcConfigSchema.pick({
@@ -180,9 +189,8 @@ export const registerOidcRouter = async (server: FastifyZodProvider) => {
       }
     },
     handler: async (req) => {
-      const { orgSlug } = req.query;
       const oidc = await server.services.oidc.getOidc({
-        orgSlug,
+        organizationId: req.query.organizationId,
         type: "external",
         actor: req.permission.type,
         actorId: req.permission.id,
@@ -200,8 +208,16 @@ export const registerOidcRouter = async (server: FastifyZodProvider) => {
     config: {
       rateLimit: writeLimit
     },
-    onRequest: verifyAuth([AuthMode.JWT]),
+    onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]),
     schema: {
+      hide: false,
+      tags: [ApiDocsTags.OidcSso],
+      description: "Update OIDC config",
+      security: [
+        {
+          bearerAuth: []
+        }
+      ],
       body: z
         .object({
           allowedEmailDomains: z
@@ -216,22 +232,26 @@ export const registerOidcRouter = async (server: FastifyZodProvider) => {
                 .split(",")
                 .map((id) => id.trim())
                 .join(", ");
-            }),
-          discoveryURL: z.string().trim(),
-          configurationType: z.nativeEnum(OIDCConfigurationType),
-          issuer: z.string().trim(),
-          authorizationEndpoint: z.string().trim(),
-          jwksUri: z.string().trim(),
-          tokenEndpoint: z.string().trim(),
-          userinfoEndpoint: z.string().trim(),
-          clientId: z.string().trim(),
-          clientSecret: z.string().trim(),
-          isActive: z.boolean(),
-          manageGroupMemberships: z.boolean().optional(),
-          jwtSignatureAlgorithm: z.nativeEnum(OIDCJWTSignatureAlgorithm).optional()
+            })
+            .describe(OidcSSo.UPDATE_CONFIG.allowedEmailDomains),
+          discoveryURL: z.string().trim().describe(OidcSSo.UPDATE_CONFIG.discoveryURL),
+          configurationType: z.nativeEnum(OIDCConfigurationType).describe(OidcSSo.UPDATE_CONFIG.configurationType),
+          issuer: z.string().trim().describe(OidcSSo.UPDATE_CONFIG.issuer),
+          authorizationEndpoint: z.string().trim().describe(OidcSSo.UPDATE_CONFIG.authorizationEndpoint),
+          jwksUri: z.string().trim().describe(OidcSSo.UPDATE_CONFIG.jwksUri),
+          tokenEndpoint: z.string().trim().describe(OidcSSo.UPDATE_CONFIG.tokenEndpoint),
+          userinfoEndpoint: z.string().trim().describe(OidcSSo.UPDATE_CONFIG.userinfoEndpoint),
+          clientId: z.string().trim().describe(OidcSSo.UPDATE_CONFIG.clientId),
+          clientSecret: z.string().trim().describe(OidcSSo.UPDATE_CONFIG.clientSecret),
+          isActive: z.boolean().describe(OidcSSo.UPDATE_CONFIG.isActive),
+          manageGroupMemberships: z.boolean().optional().describe(OidcSSo.UPDATE_CONFIG.manageGroupMemberships),
+          jwtSignatureAlgorithm: z
+            .nativeEnum(OIDCJWTSignatureAlgorithm)
+            .optional()
+            .describe(OidcSSo.UPDATE_CONFIG.jwtSignatureAlgorithm)
         })
         .partial()
-        .merge(z.object({ orgSlug: z.string() })),
+        .merge(z.object({ organizationId: z.string().describe(OidcSSo.UPDATE_CONFIG.organizationId) })),
       response: {
         200: SanitizedOidcConfigSchema.pick({
           id: true,
@@ -267,8 +287,16 @@ export const registerOidcRouter = async (server: FastifyZodProvider) => {
     config: {
       rateLimit: writeLimit
     },
-    onRequest: verifyAuth([AuthMode.JWT]),
+    onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]),
     schema: {
+      hide: false,
+      tags: [ApiDocsTags.OidcSso],
+      description: "Create OIDC config",
+      security: [
+        {
+          bearerAuth: []
+        }
+      ],
       body: z
         .object({
           allowedEmailDomains: z
@@ -283,23 +311,34 @@ export const registerOidcRouter = async (server: FastifyZodProvider) => {
                 .split(",")
                 .map((id) => id.trim())
                 .join(", ");
-            }),
-          configurationType: z.nativeEnum(OIDCConfigurationType),
-          issuer: z.string().trim().optional().default(""),
-          discoveryURL: z.string().trim().optional().default(""),
-          authorizationEndpoint: z.string().trim().optional().default(""),
-          jwksUri: z.string().trim().optional().default(""),
-          tokenEndpoint: z.string().trim().optional().default(""),
-          userinfoEndpoint: z.string().trim().optional().default(""),
-          clientId: z.string().trim(),
-          clientSecret: z.string().trim(),
-          isActive: z.boolean(),
-          orgSlug: z.string().trim(),
-          manageGroupMemberships: z.boolean().optional().default(false),
+            })
+            .describe(OidcSSo.CREATE_CONFIG.allowedEmailDomains),
+          configurationType: z.nativeEnum(OIDCConfigurationType).describe(OidcSSo.CREATE_CONFIG.configurationType),
+          issuer: z.string().trim().optional().default("").describe(OidcSSo.CREATE_CONFIG.issuer),
+          discoveryURL: z.string().trim().optional().default("").describe(OidcSSo.CREATE_CONFIG.discoveryURL),
+          authorizationEndpoint: z
+            .string()
+            .trim()
+            .optional()
+            .default("")
+            .describe(OidcSSo.CREATE_CONFIG.authorizationEndpoint),
+          jwksUri: z.string().trim().optional().default("").describe(OidcSSo.CREATE_CONFIG.jwksUri),
+          tokenEndpoint: z.string().trim().optional().default("").describe(OidcSSo.CREATE_CONFIG.tokenEndpoint),
+          userinfoEndpoint: z.string().trim().optional().default("").describe(OidcSSo.CREATE_CONFIG.userinfoEndpoint),
+          clientId: z.string().trim().describe(OidcSSo.CREATE_CONFIG.clientId),
+          clientSecret: z.string().trim().describe(OidcSSo.CREATE_CONFIG.clientSecret),
+          isActive: z.boolean().describe(OidcSSo.CREATE_CONFIG.isActive),
+          organizationId: z.string().trim().describe(OidcSSo.CREATE_CONFIG.organizationId),
+          manageGroupMemberships: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe(OidcSSo.CREATE_CONFIG.manageGroupMemberships),
           jwtSignatureAlgorithm: z
             .nativeEnum(OIDCJWTSignatureAlgorithm)
             .optional()
             .default(OIDCJWTSignatureAlgorithm.RS256)
+            .describe(OidcSSo.CREATE_CONFIG.jwtSignatureAlgorithm)
         })
         .superRefine((data, ctx) => {
           if (data.configurationType === OIDCConfigurationType.CUSTOM) {

backend/src/ee/routes/v1/saml-router.ts

@@ -13,6 +13,7 @@ import { FastifyRequest } from "fastify";
 import { z } from "zod";
 
 import { SamlProviders, TGetSamlCfgDTO } from "@app/ee/services/saml-config/saml-config-types";
+import { ApiDocsTags, SamlSso } from "@app/lib/api-docs";
 import { getConfig } from "@app/lib/config/env";
 import { BadRequestError } from "@app/lib/errors";
 import { logger } from "@app/lib/logger";
@@ -149,8 +150,8 @@ export const registerSamlRouter = async (server: FastifyZodProvider) => {
             firstName,
             lastName: lastName as string,
             relayState: (req.body as { RelayState?: string }).RelayState,
-            authProvider: (req as unknown as FastifyRequest).ssoConfig?.authProvider as string,
-            orgId: (req as unknown as FastifyRequest).ssoConfig?.orgId as string,
+            authProvider: (req as unknown as FastifyRequest).ssoConfig?.authProvider,
+            orgId: (req as unknown as FastifyRequest).ssoConfig?.orgId,
             metadata: userMetadata
           });
           cb(null, { isUserCompleted, providerAuthToken });
@@ -262,25 +263,31 @@ export const registerSamlRouter = async (server: FastifyZodProvider) => {
     config: {
       rateLimit: readLimit
     },
-    onRequest: verifyAuth([AuthMode.JWT]),
+    onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]),
     schema: {
+      hide: false,
+      tags: [ApiDocsTags.SamlSso],
+      description: "Get SAML config",
+      security: [
+        {
+          bearerAuth: []
+        }
+      ],
       querystring: z.object({
-        organizationId: z.string().trim()
+        organizationId: z.string().trim().describe(SamlSso.GET_CONFIG.organizationId)
       }),
       response: {
-        200: z
-          .object({
-            id: z.string(),
-            organization: z.string(),
-            orgId: z.string(),
-            authProvider: z.string(),
-            isActive: z.boolean(),
-            entryPoint: z.string(),
-            issuer: z.string(),
-            cert: z.string(),
-            lastUsed: z.date().nullable().optional()
-          })
-          .optional()
+        200: z.object({
+          id: z.string(),
+          organization: z.string(),
+          orgId: z.string(),
+          authProvider: z.string(),
+          isActive: z.boolean(),
+          entryPoint: z.string(),
+          issuer: z.string(),
+          cert: z.string(),
+          lastUsed: z.date().nullable().optional()
+        })
       }
     },
     handler: async (req) => {
@@ -302,15 +309,23 @@ export const registerSamlRouter = async (server: FastifyZodProvider) => {
     config: {
       rateLimit: writeLimit
     },
-    onRequest: verifyAuth([AuthMode.JWT]),
+    onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]),
     schema: {
+      hide: false,
+      tags: [ApiDocsTags.SamlSso],
+      description: "Create SAML config",
+      security: [
+        {
+          bearerAuth: []
+        }
+      ],
       body: z.object({
-        organizationId: z.string(),
-        authProvider: z.nativeEnum(SamlProviders),
-        isActive: z.boolean(),
-        entryPoint: z.string(),
-        issuer: z.string(),
-        cert: z.string()
+        organizationId: z.string().trim().describe(SamlSso.CREATE_CONFIG.organizationId),
+        authProvider: z.nativeEnum(SamlProviders).describe(SamlSso.CREATE_CONFIG.authProvider),
+        isActive: z.boolean().describe(SamlSso.CREATE_CONFIG.isActive),
+        entryPoint: z.string().trim().describe(SamlSso.CREATE_CONFIG.entryPoint),
+        issuer: z.string().trim().describe(SamlSso.CREATE_CONFIG.issuer),
+        cert: z.string().trim().describe(SamlSso.CREATE_CONFIG.cert)
       }),
       response: {
         200: SanitizedSamlConfigSchema
@@ -341,18 +356,26 @@ export const registerSamlRouter = async (server: FastifyZodProvider) => {
     config: {
       rateLimit: writeLimit
     },
-    onRequest: verifyAuth([AuthMode.JWT]),
+    onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]),
     schema: {
+      hide: false,
+      tags: [ApiDocsTags.SamlSso],
+      description: "Update SAML config",
+      security: [
+        {
+          bearerAuth: []
+        }
+      ],
       body: z
         .object({
-          authProvider: z.nativeEnum(SamlProviders),
-          isActive: z.boolean(),
-          entryPoint: z.string(),
-          issuer: z.string(),
-          cert: z.string()
+          authProvider: z.nativeEnum(SamlProviders).describe(SamlSso.UPDATE_CONFIG.authProvider),
+          isActive: z.boolean().describe(SamlSso.UPDATE_CONFIG.isActive),
+          entryPoint: z.string().trim().describe(SamlSso.UPDATE_CONFIG.entryPoint),
+          issuer: z.string().trim().describe(SamlSso.UPDATE_CONFIG.issuer),
+          cert: z.string().trim().describe(SamlSso.UPDATE_CONFIG.cert)
         })
         .partial()
-        .merge(z.object({ organizationId: z.string() })),
+        .merge(z.object({ organizationId: z.string().trim().describe(SamlSso.UPDATE_CONFIG.organizationId) })),
       response: {
         200: SanitizedSamlConfigSchema
       }