fix(docs): group the app reference by client id, not by provider

One OAuth app is one client id, and more than one connector can register
against it. `manageengine-sdp` reads `ZOHO_CLIENT_ID`
(`lib/auth/connectors/providers.ts:1267`) while being its own provider
entry, so grouping by provider left it off the Zoho section entirely: a
self-hoster following that page registered one redirect URI, missed
`/api/auth/oauth2/callback/manageengine-sdp`, and that connector's connect
flow then failed redirect-URI validation. Same class as the Salesforce
sandbox URI, from the same wrong assumption that a capability id maps to
exactly one provider.

Connectors sharing an app's client id are now read from the registrations
themselves, which is where the runtime decides which credentials a
connector uses, and attached to that app. Additive rather than a
replacement: Instagram, Salesforce, Shopify and Trello run custom flows
that declare no `clientId: env.X` line, so a pure registration scrape would
have dropped four apps off the page.

Also generalized the admin-consent warning, which named only `microsoft-ad`
while Teams and Planner both request `Group.ReadWrite.All`. It now points at
Microsoft's reference rather than implying every `.All` permission needs an
admin, since `Sites.Read.All` does not.

Author: mzxchandra

apps/docs/content/docs/platform/self-hosting/integrations-oauth.mdx

@@ -57,7 +57,7 @@ https://sim.yourdomain.com/api/auth/oauth2/callback/google-email
 https://sim.yourdomain.com/api/auth/oauth2/callback/google-drive
 ```
 
-Most providers let Sim request scopes at authorization time, but several need them declared on the app before anyone can connect. Microsoft Entra requires every delegated permission to be added to the registration, and the `microsoft-ad` connector's directory permissions additionally need tenant admin consent. Bitbucket fixes permissions on the consumer rather than per request. Google needs the matching API enabled on the Cloud project (Gmail API, Drive API, Calendar API, and so on) as well as the scopes on the consent screen.
+Most providers let Sim request scopes at authorization time, but several need them declared on the app before anyone can connect. Microsoft Entra requires every delegated permission to be added to the registration, and some of them cannot be granted by the connecting user at all: a tenant admin has to consent on the directory's behalf. The directory and group permissions are where this bites: `microsoft-ad` asks for several, and Teams and Planner both request `Group.ReadWrite.All`. Check each permission against [Microsoft's reference](https://learn.microsoft.com/en-us/graph/permissions-reference) rather than assuming a user can approve it, since not every `.All` permission needs an admin (`Sites.Read.All`, for one, does not). Bitbucket fixes permissions on the consumer rather than per request. Google needs the matching API enabled on the Cloud project (Gmail API, Drive API, Calendar API, and so on) as well as the scopes on the consent screen.
 
 The [provider reference](#provider-reference) below lists the exact scopes each connector asks for, grouped by the app that covers it.
 
@@ -386,9 +386,12 @@ Trello is API-key based rather than OAuth 2.0 and calls back to `/api/auth/trell
 
 `ZOHO_CLIENT_ID` / `ZOHO_CLIENT_SECRET`
 
+Every connector below also requests `aaaserver.profile.READ`.
+
 | Connector | Provider ID | Scopes to grant |
 | --- | --- | --- |
-| Zoho Desk | `zoho-desk` | `Desk.tickets.READ`, `Desk.tickets.UPDATE`, `Desk.contacts.READ`, `Desk.articles.READ`, `Desk.organization.READ`, `Desk.agents.READ`, `Desk.basic.READ`, `Desk.webhooks.CREATE`, `Desk.webhooks.DELETE`, `aaaserver.profile.READ` |
+| Zoho Desk | `zoho-desk` | `Desk.tickets.READ`, `Desk.tickets.UPDATE`, `Desk.contacts.READ`, `Desk.articles.READ`, `Desk.organization.READ`, `Desk.agents.READ`, `Desk.basic.READ`, `Desk.webhooks.CREATE`, `Desk.webhooks.DELETE` |
+| ManageEngine ServiceDesk Plus | `manageengine-sdp` | `SDPOnDemand.requests.CREATE`, `SDPOnDemand.requests.READ`, `SDPOnDemand.requests.UPDATE`, `SDPOnDemand.requests.DELETE`, `SDPOnDemand.problems.CREATE`, `SDPOnDemand.problems.READ`, `SDPOnDemand.problems.UPDATE`, `SDPOnDemand.problems.DELETE`, `SDPOnDemand.changes.CREATE`, `SDPOnDemand.changes.READ`, `SDPOnDemand.changes.UPDATE`, `SDPOnDemand.changes.DELETE`, `SDPOnDemand.assets.CREATE`, `SDPOnDemand.assets.READ`, `SDPOnDemand.assets.UPDATE`, `SDPOnDemand.assets.DELETE`, `SDPOnDemand.solutions.CREATE`, `SDPOnDemand.solutions.READ`, `SDPOnDemand.solutions.UPDATE`, `SDPOnDemand.solutions.DELETE` |
 
 ### Zoom
 

scripts/generate-docs.test.ts

@@ -10,6 +10,7 @@ import {
   extractToolInfo,
   extractUserSettableParamIds,
   getToolInfo,
+  loadClientIdEnvByProviderId,
   loadOAuthConnectCatalog,
   parseConstProperties,
   parsePropertiesContent,
@@ -1081,6 +1082,20 @@ describe('the self-hosting OAuth app reference', () => {
    * them and listing one would send the reader looking for a client id that
    * does not exist.
    */
+  /**
+   * One OAuth app is one client id, and more than one connector can be
+   * registered against it: `manageengine-sdp` reads `ZOHO_CLIENT_ID` despite
+   * being its own provider entry. Grouping by provider alone left its redirect
+   * URI and scopes off the page for the app that covers it.
+   */
+  it('groups a connector under the app whose client id it registers against', () => {
+    const clientIdEnv = loadClientIdEnvByProviderId()
+
+    expect(clientIdEnv.get('manageengine-sdp')).toBe('ZOHO_CLIENT_ID')
+    expect(clientIdEnv.get('zoho-desk')).toBe('ZOHO_CLIENT_ID')
+    expect(clientIdEnv.get('sharepoint')).toBe('MICROSOFT_CLIENT_ID')
+  })
+
   it('leaves out services that have no OAuth flow', () => {
     const { services } = loadOAuthConnectCatalog()
 

scripts/generate-docs.ts

@@ -52,6 +52,7 @@ const LANDING_INTEGRATIONS_DATA_PATH = path.join(
 )
 const TRIGGERS_PATH = path.join(rootDir, 'apps/sim/triggers')
 const OAUTH_CONFIG_PATH = path.join(rootDir, 'apps/sim/lib/oauth/oauth.ts')
+const OAUTH_REGISTRATION_PATH = path.join(rootDir, 'apps/sim/lib/auth/connectors/providers.ts')
 const SELF_HOSTING_OAUTH_DOC_PATH = path.join(
   rootDir,
   'apps/docs/content/docs/platform/self-hosting/integrations-oauth.mdx'
@@ -1536,6 +1537,42 @@ const NON_STANDARD_OAUTH_CALLBACKS: Readonly<Record<string, string>> = {
 const SELF_HOSTING_GENERATED_START = '{/* GENERATED-START:oauth-apps */}'
 const SELF_HOSTING_GENERATED_END = '{/* GENERATED-END:oauth-apps */}'
 
+/**
+ * Which client-id environment variable each connector registration reads.
+ *
+ * One OAuth app is one client id, and more than one connector can be
+ * registered against the same one: `manageengine-sdp` authenticates with
+ * `ZOHO_CLIENT_ID` even though it is its own provider entry. Grouping the
+ * reference by provider alone would leave that connector's redirect URI and
+ * scopes off the page of the app that covers it, and its connect flow would
+ * fail redirect-URI validation for anyone who registered from the docs.
+ *
+ * Read from the registrations themselves, since that is where the runtime
+ * decides which credentials a connector uses.
+ */
+export function loadClientIdEnvByProviderId(): Map<string, string> {
+  const byProviderId = new Map<string, string>()
+  const lines = readSourceFile(OAUTH_REGISTRATION_PATH).split('\n')
+
+  let providerId: string | null = null
+  for (const line of lines) {
+    const providerMatch = /^ {6}providerId: '([^']+)',$/.exec(line)
+    if (providerMatch) {
+      providerId = providerMatch[1]
+      continue
+    }
+    if (!providerId) continue
+
+    const clientIdMatch = /^ {6}clientId: env\.([A-Z0-9_]+) as string,$/.exec(line)
+    if (clientIdMatch) {
+      byProviderId.set(providerId, clientIdMatch[1])
+      providerId = null
+    }
+  }
+
+  return byProviderId
+}
+
 /**
  * Build the per-OAuth-app reference for the self-hosting page.
  *
@@ -1604,8 +1641,9 @@ export function sharedScopesAcrossConnectors(scopeLists: readonly (readonly stri
 }
 
 function buildSelfHostingOAuthReference(): string {
-  const { providers } = loadOAuthConnectCatalog()
+  const { providers, services } = loadOAuthConnectCatalog()
 
+  const clientIdEnvByProviderId = loadClientIdEnvByProviderId()
   const apps = Object.keys(OAUTH_CLIENT_CAPABILITIES)
     .map((capabilityId) => {
       const provider = providers.get(capabilityId)
@@ -1615,18 +1653,33 @@ function buildSelfHostingOAuthReference(): string {
             `lib/oauth/oauth.ts, so its app registration cannot be documented.`
         )
       }
-      return { capabilityId, provider }
+
+      // Connectors registered against this app's client id from some other
+      // provider entry. Additive rather than a replacement for the grouping
+      // above, because four capabilities (Instagram, Salesforce, Shopify,
+      // Trello) run custom flows that declare no `clientId: env.X` line.
+      const [clientIdEnv] =
+        OAUTH_CLIENT_CAPABILITIES[capabilityId as keyof typeof OAUTH_CLIENT_CAPABILITIES]
+      const own = new Set(provider.services.map((service) => service.serviceId))
+      const sharedConnectors = [...services.values()].filter(
+        (service) =>
+          !own.has(service.serviceId) &&
+          !service.serviceAccountOnly &&
+          clientIdEnvByProviderId.get(service.providerId) === clientIdEnv
+      )
+
+      return { capabilityId, provider, sharedConnectors }
     })
     .sort((a, b) => compareCatalogNames(a.provider.name, b.provider.name))
 
-  const sections = apps.map(({ capabilityId, provider }) => {
+  const sections = apps.map(({ capabilityId, provider, sharedConnectors }) => {
     const envVars = OAUTH_CLIENT_CAPABILITIES[
       capabilityId as keyof typeof OAUTH_CLIENT_CAPABILITIES
     ]
       .map((name) => `\`${name}\``)
       .join(' / ')
 
-    const connectors = provider.services
+    const connectors = [...provider.services, ...sharedConnectors]
       .filter((service) => !service.serviceAccountOnly)
       .map((service) => ({
         service,