Merge pull request #990 from Max-Health-Inc/develop

🧪 Auto-PR: Merge `develop` → `test`

Author: proxy-smart-releaser[bot]

backend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "proxy-smart-backend",
   "displayName": "Proxy Smart Backend",
-  "version": "0.3.7-beta.202608091534.25d7f9a8e",
+  "version": "0.3.8-alpha.202608120751.92961df39",
   "type": "module",
   "scripts": {
     "test": "bun test --isolate",

backend/src/lib/admin-error-handler.ts

@@ -65,8 +65,15 @@ export function handleAdminError(error: unknown, set: Context['set']) {
 /**
  * Sanitize error details before sending in HTTP response.
  * Removes stack traces and internal file paths to prevent information disclosure.
+ *
+ * Prefers Keycloak's own response body over `error.message`. The admin client throws
+ * with the message set to just the error CODE, so a failed provider create surfaced as
+ * the bare word `unknown_error` while the body carried the actual reason. Reporting the
+ * code alone is indistinguishable from reporting nothing.
  */
 function sanitizeErrorForResponse(error: unknown): string {
+  const fromKeycloak = keycloakErrorDetail(error)
+  if (fromKeycloak) return fromKeycloak
   if (error instanceof Error) {
     return error.message
   }
@@ -76,4 +83,31 @@ function sanitizeErrorForResponse(error: unknown): string {
   return 'An unexpected error occurred'
 }
 
+/**
+ * The most specific description Keycloak returned, across the field names its various
+ * endpoints use (`error_description`, `errorMessage`, `error`) and the two places the
+ * admin client stashes the parsed body.
+ */
+function keycloakErrorDetail(error: unknown): string | null {
+  if (!error || typeof error !== 'object') return null
+  const err = error as Record<string, unknown>
+  const response = err.response as Record<string, unknown> | undefined
+  const bodies = [err.responseData, response?.data, response?.body].filter(
+    (b): b is Record<string, unknown> => !!b && typeof b === 'object',
+  )
+
+  const parts: string[] = []
+  for (const body of bodies) {
+    for (const field of ['error_description', 'errorMessage', 'error']) {
+      const value = body[field]
+      if (typeof value === 'string' && value.trim() && !parts.includes(value)) parts.push(value)
+    }
+  }
+  if (parts.length === 0) return null
+
+  // A message plus the code reads better than either alone, and the code is what
+  // Keycloak's own docs are searchable by.
+  return parts.join(': ')
+}
+
 

backend/src/lib/idp-required-config.ts

@@ -0,0 +1,59 @@
+// SPDX-FileCopyrightText: Max Health Inc.
+// SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Commercial
+
+/**
+ * Config keys Keycloak requires before it will accept an identity provider.
+ *
+ * WHY THIS EXISTS. Keycloak does not validate an incomplete provider into a useful
+ * message — `POST identity-provider/instances` for an `oidc` provider with no
+ * `clientId`/`authorizationUrl` answers 500 `{"error":"unknown_error"}`. That reached
+ * callers verbatim, so the only signal anyone got was the word "unknown_error": no
+ * indication that a field was missing, which field, or that the request was the
+ * problem at all. Checking here turns it into a 400 that names the keys.
+ *
+ * These are the keys the provider CANNOT work without, not every key it accepts.
+ * Anything else a provider supports still passes through untouched.
+ */
+
+/** Keycloak's own generic OIDC/OAuth2 brokers. */
+const OIDC_REQUIRED = ['clientId', 'clientSecret', 'authorizationUrl', 'tokenUrl'] as const
+
+/**
+ * Social brokers ship their endpoints in the provider factory, so a caller only
+ * supplies credentials. Listed explicitly rather than matched by a fallback, so an
+ * unknown providerId is left to Keycloak instead of being silently under-checked.
+ */
+const SOCIAL_PROVIDERS = [
+  'google', 'github', 'facebook', 'microsoft', 'gitlab', 'bitbucket',
+  'linkedin', 'linkedin-openid-connect', 'twitter', 'instagram',
+  'paypal', 'stackoverflow', 'openshift-v3', 'openshift-v4',
+] as const
+
+const REQUIRED_CONFIG: Record<string, readonly string[]> = {
+  oidc: OIDC_REQUIRED,
+  'keycloak-oidc': OIDC_REQUIRED,
+  oauth2: OIDC_REQUIRED,
+  saml: ['singleSignOnServiceUrl'],
+  ...Object.fromEntries(SOCIAL_PROVIDERS.map((id) => [id, ['clientId', 'clientSecret']])),
+}
+
+/** The keys `providerId` needs, or an empty list when the type is not known here. */
+export function requiredConfigFor(providerId: string): readonly string[] {
+  return REQUIRED_CONFIG[providerId] ?? []
+}
+
+/**
+ * Which required keys are absent or blank.
+ *
+ * Blank counts as absent: Keycloak treats `clientId: ""` exactly as it treats a
+ * missing one, and a form that submits empty inputs is the common way to get here.
+ */
+export function missingConfigKeys(
+  providerId: string,
+  config: Record<string, unknown> | undefined,
+): string[] {
+  return requiredConfigFor(providerId).filter((key) => {
+    const value = config?.[key]
+    return value === undefined || value === null || (typeof value === 'string' && value.trim() === '')
+  })
+}

backend/src/routes/admin/identity-providers.ts

@@ -21,6 +21,7 @@ import {
 import { handleAdminError } from '@/lib/admin-error-handler'
 import { extractBearerToken } from '@/lib/admin-utils'
 import { ensureIdpAttributeMappers } from '@/lib/idp-mappers'
+import { missingConfigKeys } from '@/lib/idp-required-config'
 import { logger } from '@/lib/logger'
 import type IdentityProviderRepresentation from '@keycloak/keycloak-admin-client/lib/defs/identityProviderRepresentation.js'
 
@@ -137,6 +138,17 @@ export const identityProvidersRoutes = new Elysia({ prefix: '/idps' })
         return { error: 'Alias and providerId are required' }
       }
 
+      // Keycloak answers 500 `unknown_error` for an incomplete provider, naming nothing.
+      // Refuse first, and say which keys are missing.
+      const missing = missingConfigKeys(payload.providerId, payload.config as Record<string, unknown>)
+      if (missing.length > 0) {
+        set.status = 400
+        return {
+          error: `Missing required config for providerId "${payload.providerId}": ${missing.join(', ')}. ` +
+            `Supply them under "config".`,
+        }
+      }
+
       await admin.identityProviders.create({
         ...payload,
         config: payload.config ?? {}

backend/src/schemas/admin/identity-providers.ts

@@ -11,33 +11,66 @@ import { t, type Static } from 'elysia'
 /**
  * Identity Provider configuration schema for OIDC/SAML providers
  */
+/**
+ * The Keycloak identity-provider `config` map.
+ *
+ * TWO DEFECTS THIS FIXES, both of which made an OIDC provider impossible to create
+ * through any caller — the admin UI, the generated client, and the MCP tool alike.
+ *
+ * 1. `clientId` and `authorizationUrl` were absent. Two of the four keys Keycloak
+ *    requires for `oidc` could not be named at all, so every create reached Keycloak
+ *    without them and came back 500 `unknown_error`.
+ * 2. The object was closed, and Elysia STRIPS undeclared body properties rather than
+ *    rejecting them. So a caller that sent `clientId` anyway had it removed silently,
+ *    before the handler ran — no error, no warning, nothing in a log.
+ *
+ * Hence `additionalProperties`: the named keys below document what a provider commonly
+ * needs, and anything else Keycloak supports still travels. The old `additionalConfig`
+ * sub-object was not that escape hatch — Keycloak has no `additionalConfig` key, so
+ * anything nested under it was passed to Keycloak and ignored, which reads as an escape
+ * hatch while being a dead end.
+ *
+ * Values are strings because Keycloak stores this map as strings; the few booleans it
+ * accepts are declared explicitly below.
+ */
 export const IdentityProviderConfig = t.Object({
-  // Common fields
-  displayName: t.Optional(t.String({ description: 'Display name for UI' })),
-  enabled: t.Optional(t.Boolean({ description: 'Whether the provider is enabled', default: true })),
-  
-  // OIDC/OAuth2 specific fields
-  clientSecret: t.Optional(t.String({ description: 'OAuth2 client secret' })),
-  tokenUrl: t.Optional(t.String({ description: 'Token endpoint URL' })),
+  // ── OIDC / OAuth2 ──
+  clientId: t.Optional(t.String({ description: 'OAuth2 client id issued by the provider. REQUIRED for oidc, oauth2, keycloak-oidc and the social providers.' })),
+  clientSecret: t.Optional(t.String({ description: 'OAuth2 client secret. REQUIRED for oidc, oauth2, keycloak-oidc and the social providers.' })),
+  authorizationUrl: t.Optional(t.String({ description: "The provider's authorization endpoint URL. REQUIRED for oidc, oauth2 and keycloak-oidc." })),
+  tokenUrl: t.Optional(t.String({ description: "The provider's token endpoint URL. REQUIRED for oidc, oauth2 and keycloak-oidc." })),
   userInfoUrl: t.Optional(t.String({ description: 'UserInfo endpoint URL' })),
-  issuer: t.Optional(t.String({ description: 'OIDC issuer URL' })),
-  defaultScopes: t.Optional(t.String({ description: 'Default OAuth2 scopes' })),
+  issuer: t.Optional(t.String({ description: 'OIDC issuer URL, validated against the id token iss claim' })),
+  defaultScopes: t.Optional(t.String({ description: 'Space-separated OAuth2 scopes to request (e.g. "openid profile email")' })),
   logoutUrl: t.Optional(t.String({ description: 'Logout endpoint URL' })),
-  
-  // SAML specific fields
+  clientAuthMethod: t.Optional(t.String({ description: 'Client authentication method (client_secret_post, client_secret_basic, client_secret_jwt, private_key_jwt)' })),
+  validateSignature: t.Optional(t.Boolean({ description: 'Validate signatures on tokens/assertions from this provider' })),
+  useJwksUrl: t.Optional(t.Boolean({ description: 'Fetch the signing keys from jwksUrl rather than using a static certificate' })),
+  jwksUrl: t.Optional(t.String({ description: "The provider's JWKS URL, used when useJwksUrl is true" })),
+  pkceEnabled: t.Optional(t.Boolean({ description: 'Send a PKCE challenge on the authorization request' })),
+  pkceMethod: t.Optional(t.String({ description: 'PKCE code challenge method (S256 or plain)' })),
+  syncMode: t.Optional(t.String({ description: 'How brokered user data is synced on later logins: IMPORT, LEGACY or FORCE' })),
+
+  // ── SAML ──
   entityId: t.Optional(t.String({ description: 'SAML entity ID' })),
-  singleSignOnServiceUrl: t.Optional(t.String({ description: 'SAML SSO URL' })),
+  singleSignOnServiceUrl: t.Optional(t.String({ description: 'SAML SSO URL. REQUIRED for saml.' })),
   singleLogoutServiceUrl: t.Optional(t.String({ description: 'SAML SLO URL' })),
   metadataDescriptorUrl: t.Optional(t.String({ description: 'SAML metadata URL' })),
   signatureAlgorithm: t.Optional(t.String({ description: 'SAML signature algorithm' })),
   nameIdPolicyFormat: t.Optional(t.String({ description: 'SAML NameID format' })),
   signingCertificate: t.Optional(t.String({ description: 'SAML signing certificate' })),
-  validateSignature: t.Optional(t.Boolean({ description: 'Validate SAML signatures' })),
   wantAuthnRequestsSigned: t.Optional(t.Boolean({ description: 'Require signed AuthN requests' })),
-  
-  // Allow additional configuration
-  additionalConfig: t.Optional(t.Record(t.String(), t.Any()))
-}, { title: 'IdentityProviderConfig' })
+
+  // ── Kept for the admin UI, which writes it alongside the real keys ──
+  displayName: t.Optional(t.String({ description: 'Display name for UI' })),
+}, {
+  title: 'IdentityProviderConfig',
+  // Any other key this provider type supports, passed through to Keycloak verbatim.
+  // Booleans and numbers are accepted as well as strings: Keycloak stores the map as
+  // strings and coerces, and restricting to strings would recreate the dead end this
+  // replaces for keys whose natural JSON form is not a string.
+  additionalProperties: t.Union([t.String(), t.Boolean(), t.Number()]),
+})
 
 export const IdentityProvider = t.Object({
   alias: t.Optional(t.String({ description: 'Provider alias (unique identifier)' })),