@slates/provider-handler 1.0.0-rc.40 → 1.0.0-rc.42

package/dist/index.cjs

@@ -124,7 +124,8 @@ var mapAuthMethod = (slate, m) => ({
     handleChangedInput: {
       enabled: !!m.onInputChanged
     },
-    getProfile: { enabled: !!m.getProfile }
+    getProfile: { enabled: !!m.getProfile },
+    ..."adminSetup" in m && m.adminSetup ? { adminSetup: { enabled: true, required: m.adminSetup.required === true } } : {}
   },
   docs: m.docs ?? []
 });
@@ -548,6 +549,57 @@ var createProviderHandler = (slate, listeners) => (0, import_proto.createSlatesP
     let requestTraces = context.getHttpTraces();
     return requestTraces.length > 0 ? { ...result, requestTraces } : result;
   };
+  let buildAuthorizationUrlContext = (params) => ({
+    redirectUri: params.redirectUri,
+    state: params.state,
+    input: params.input,
+    clientId: params.clientId,
+    clientSecret: params.clientSecret,
+    scopes: params.scopes,
+    config: getAuthConfig()
+  });
+  let buildCallbackContext = (params) => ({
+    state: params.state,
+    redirectUri: params.redirectUri,
+    input: params.input,
+    clientId: params.clientId,
+    clientSecret: params.clientSecret,
+    scopes: params.scopes,
+    callbackParams: params.callbackParams || {},
+    callbackState: params.callbackState || {},
+    config: getAuthConfig()
+  });
+  let getTracedAuthorizationUrl = async (params, authenticationMethodName, trace, getAuthorizationUrl) => {
+    let context = getEmptyContext();
+    let urlRes = await traceProviderCall(
+      {
+        component: "auth",
+        functionName: trace.functionName,
+        message: trace.message,
+        successMessage: trace.successMessage,
+        metadata: {
+          authenticationMethodId: params.authenticationMethodId,
+          authenticationMethodName,
+          scopeCount: params.scopes.length,
+          inputKeyCount: getObjectKeyCount(params.input),
+          ...trace.metadata
+        },
+        onSuccess: (result) => ({
+          returnedInput: !!result.input,
+          hasCallbackState: !!result.callbackState
+        })
+      },
+      () => (0, import_provider2.runWithContext)(
+        context,
+        () => getAuthorizationUrl(buildAuthorizationUrlContext(params))
+      )
+    );
+    return withRequestTraces(context, {
+      authorizationUrl: urlRes.url,
+      input: urlRes.input,
+      callbackState: urlRes.callbackState
+    });
+  };
   manager.onNotification("slates/hello", async ({ params }) => {
     protocol.set(params.protocol);
   });
@@ -839,18 +891,7 @@ var createProviderHandler = (slate, listeners) => (0, import_proto.createSlatesP
         },
         () => (0, import_provider2.runWithContext)(
           context,
-          () => authMethod.handleCallback({
-            code: params.code,
-            state: params.state,
-            redirectUri: params.redirectUri,
-            input: params.input,
-            clientId: params.clientId,
-            clientSecret: params.clientSecret,
-            scopes: params.scopes,
-            callbackParams: params.callbackParams || {},
-            callbackState: params.callbackState || {},
-            config: getAuthConfig()
-          })
+          () => authMethod.handleCallback({ ...buildCallbackContext(params), code: params.code })
         )
       );
       return withRequestTraces(context, {
@@ -869,46 +910,93 @@ var createProviderHandler = (slate, listeners) => (0, import_proto.createSlatesP
     getContextBasic();
     let authMethod = getAuthMethod(slate, params.authenticationMethodId);
     if ("getAuthorizationUrl" in authMethod) {
-      let context = getEmptyContext();
-      let urlRes = await traceProviderCall(
+      return getTracedAuthorizationUrl(
+        params,
+        authMethod.name,
         {
-          component: "auth",
           functionName: "getAuthorizationUrl",
           message: "Getting authentication authorization URL",
-          successMessage: "Authentication authorization URL retrieved",
+          successMessage: "Authentication authorization URL retrieved"
+        },
+        (ctx) => authMethod.getAuthorizationUrl(ctx)
+      );
+    }
+    throw new import_error4.ServiceError(
+      (0, import_error4.preconditionFailedError)({
+        message: `Authentication method does not support authorization URL retrieval: ${params.authenticationMethodId}`
+      })
+    );
+  });
+  manager.onRequest("slates/auth.admin_authorization_url.get", async ({ params }) => {
+    getContextBasic();
+    let authMethod = getAuthMethod(slate, params.authenticationMethodId);
+    if (authMethod.type === "auth.oauth" && authMethod.adminSetup) {
+      let { adminSetup } = authMethod;
+      return getTracedAuthorizationUrl(
+        params,
+        authMethod.name,
+        {
+          functionName: "adminSetup.getAuthorizationUrl",
+          message: "Getting admin setup authorization URL",
+          successMessage: "Admin setup authorization URL retrieved",
+          metadata: { usesDefault: !adminSetup.getAuthorizationUrl }
+        },
+        (ctx) => adminSetup.getAuthorizationUrl ? adminSetup.getAuthorizationUrl(ctx) : authMethod.getAuthorizationUrl(ctx)
+      );
+    }
+    throw new import_error4.ServiceError(
+      (0, import_error4.preconditionFailedError)({
+        message: `Authentication method does not support admin setup: ${params.authenticationMethodId}`
+      })
+    );
+  });
+  manager.onRequest("slates/auth.admin_callback.handle", async ({ params }) => {
+    getContextBasic();
+    let authMethod = getAuthMethod(slate, params.authenticationMethodId);
+    if (authMethod.type === "auth.oauth" && authMethod.adminSetup) {
+      let { adminSetup } = authMethod;
+      let ctx = { ...buildCallbackContext(params), code: params.code };
+      let handleCallback = async () => {
+        if (adminSetup.handleCallback) return adminSetup.handleCallback(ctx);
+        let code = ctx.code;
+        if (!code) {
+          throw new import_error4.ServiceError(
+            (0, import_error4.badRequestError)({
+              message: `Admin setup callback did not include an authorization code: ${params.authenticationMethodId}`
+            })
+          );
+        }
+        await authMethod.handleCallback({ ...ctx, code });
+        return {};
+      };
+      let context = getEmptyContext();
+      let callbackRes = await traceProviderCall(
+        {
+          component: "auth",
+          functionName: "adminSetup.handleCallback",
+          message: "Handling admin setup callback",
+          successMessage: "Admin setup callback handled",
           metadata: {
             authenticationMethodId: params.authenticationMethodId,
             authenticationMethodName: authMethod.name,
             scopeCount: params.scopes.length,
-            inputKeyCount: getObjectKeyCount(params.input)
+            hasCode: !!params.code,
+            hasCallbackState: !!params.callbackState,
+            usesDefault: !adminSetup.handleCallback
           },
           onSuccess: (result) => ({
-            returnedInput: !!result.input,
-            hasCallbackState: !!result.callbackState
+            returnedInstructions: !!result.instructions
           })
         },
-        () => (0, import_provider2.runWithContext)(
-          context,
-          () => authMethod.getAuthorizationUrl({
-            redirectUri: params.redirectUri,
-            state: params.state,
-            input: params.input,
-            clientId: params.clientId,
-            clientSecret: params.clientSecret,
-            scopes: params.scopes,
-            config: getAuthConfig()
-          })
-        )
+        () => (0, import_provider2.runWithContext)(context, handleCallback)
       );
       return withRequestTraces(context, {
-        authorizationUrl: urlRes.url,
-        input: urlRes.input,
-        callbackState: urlRes.callbackState
+        instructions: callbackRes.instructions
       });
     }
     throw new import_error4.ServiceError(
       (0, import_error4.preconditionFailedError)({
-        message: `Authentication method does not support authorization URL retrieval: ${params.authenticationMethodId}`
+        message: `Authentication method does not support admin setup: ${params.authenticationMethodId}`
       })
     );
   });

package/dist/index.module.js

@@ -108,7 +108,8 @@ var mapAuthMethod = (slate, m) => ({
     handleChangedInput: {
       enabled: !!m.onInputChanged
     },
-    getProfile: { enabled: !!m.getProfile }
+    getProfile: { enabled: !!m.getProfile },
+    ..."adminSetup" in m && m.adminSetup ? { adminSetup: { enabled: true, required: m.adminSetup.required === true } } : {}
   },
   docs: m.docs ?? []
 });
@@ -532,6 +533,57 @@ var createProviderHandler = (slate, listeners) => createSlatesProviderProtoHandl
     let requestTraces = context.getHttpTraces();
     return requestTraces.length > 0 ? { ...result, requestTraces } : result;
   };
+  let buildAuthorizationUrlContext = (params) => ({
+    redirectUri: params.redirectUri,
+    state: params.state,
+    input: params.input,
+    clientId: params.clientId,
+    clientSecret: params.clientSecret,
+    scopes: params.scopes,
+    config: getAuthConfig()
+  });
+  let buildCallbackContext = (params) => ({
+    state: params.state,
+    redirectUri: params.redirectUri,
+    input: params.input,
+    clientId: params.clientId,
+    clientSecret: params.clientSecret,
+    scopes: params.scopes,
+    callbackParams: params.callbackParams || {},
+    callbackState: params.callbackState || {},
+    config: getAuthConfig()
+  });
+  let getTracedAuthorizationUrl = async (params, authenticationMethodName, trace, getAuthorizationUrl) => {
+    let context = getEmptyContext();
+    let urlRes = await traceProviderCall(
+      {
+        component: "auth",
+        functionName: trace.functionName,
+        message: trace.message,
+        successMessage: trace.successMessage,
+        metadata: {
+          authenticationMethodId: params.authenticationMethodId,
+          authenticationMethodName,
+          scopeCount: params.scopes.length,
+          inputKeyCount: getObjectKeyCount(params.input),
+          ...trace.metadata
+        },
+        onSuccess: (result) => ({
+          returnedInput: !!result.input,
+          hasCallbackState: !!result.callbackState
+        })
+      },
+      () => runWithContext(
+        context,
+        () => getAuthorizationUrl(buildAuthorizationUrlContext(params))
+      )
+    );
+    return withRequestTraces(context, {
+      authorizationUrl: urlRes.url,
+      input: urlRes.input,
+      callbackState: urlRes.callbackState
+    });
+  };
   manager.onNotification("slates/hello", async ({ params }) => {
     protocol.set(params.protocol);
   });
@@ -823,18 +875,7 @@ var createProviderHandler = (slate, listeners) => createSlatesProviderProtoHandl
         },
         () => runWithContext(
           context,
-          () => authMethod.handleCallback({
-            code: params.code,
-            state: params.state,
-            redirectUri: params.redirectUri,
-            input: params.input,
-            clientId: params.clientId,
-            clientSecret: params.clientSecret,
-            scopes: params.scopes,
-            callbackParams: params.callbackParams || {},
-            callbackState: params.callbackState || {},
-            config: getAuthConfig()
-          })
+          () => authMethod.handleCallback({ ...buildCallbackContext(params), code: params.code })
         )
       );
       return withRequestTraces(context, {
@@ -853,46 +894,93 @@ var createProviderHandler = (slate, listeners) => createSlatesProviderProtoHandl
     getContextBasic();
     let authMethod = getAuthMethod(slate, params.authenticationMethodId);
     if ("getAuthorizationUrl" in authMethod) {
-      let context = getEmptyContext();
-      let urlRes = await traceProviderCall(
+      return getTracedAuthorizationUrl(
+        params,
+        authMethod.name,
         {
-          component: "auth",
           functionName: "getAuthorizationUrl",
           message: "Getting authentication authorization URL",
-          successMessage: "Authentication authorization URL retrieved",
+          successMessage: "Authentication authorization URL retrieved"
+        },
+        (ctx) => authMethod.getAuthorizationUrl(ctx)
+      );
+    }
+    throw new ServiceError4(
+      preconditionFailedError({
+        message: `Authentication method does not support authorization URL retrieval: ${params.authenticationMethodId}`
+      })
+    );
+  });
+  manager.onRequest("slates/auth.admin_authorization_url.get", async ({ params }) => {
+    getContextBasic();
+    let authMethod = getAuthMethod(slate, params.authenticationMethodId);
+    if (authMethod.type === "auth.oauth" && authMethod.adminSetup) {
+      let { adminSetup } = authMethod;
+      return getTracedAuthorizationUrl(
+        params,
+        authMethod.name,
+        {
+          functionName: "adminSetup.getAuthorizationUrl",
+          message: "Getting admin setup authorization URL",
+          successMessage: "Admin setup authorization URL retrieved",
+          metadata: { usesDefault: !adminSetup.getAuthorizationUrl }
+        },
+        (ctx) => adminSetup.getAuthorizationUrl ? adminSetup.getAuthorizationUrl(ctx) : authMethod.getAuthorizationUrl(ctx)
+      );
+    }
+    throw new ServiceError4(
+      preconditionFailedError({
+        message: `Authentication method does not support admin setup: ${params.authenticationMethodId}`
+      })
+    );
+  });
+  manager.onRequest("slates/auth.admin_callback.handle", async ({ params }) => {
+    getContextBasic();
+    let authMethod = getAuthMethod(slate, params.authenticationMethodId);
+    if (authMethod.type === "auth.oauth" && authMethod.adminSetup) {
+      let { adminSetup } = authMethod;
+      let ctx = { ...buildCallbackContext(params), code: params.code };
+      let handleCallback = async () => {
+        if (adminSetup.handleCallback) return adminSetup.handleCallback(ctx);
+        let code = ctx.code;
+        if (!code) {
+          throw new ServiceError4(
+            badRequestError3({
+              message: `Admin setup callback did not include an authorization code: ${params.authenticationMethodId}`
+            })
+          );
+        }
+        await authMethod.handleCallback({ ...ctx, code });
+        return {};
+      };
+      let context = getEmptyContext();
+      let callbackRes = await traceProviderCall(
+        {
+          component: "auth",
+          functionName: "adminSetup.handleCallback",
+          message: "Handling admin setup callback",
+          successMessage: "Admin setup callback handled",
           metadata: {
             authenticationMethodId: params.authenticationMethodId,
             authenticationMethodName: authMethod.name,
             scopeCount: params.scopes.length,
-            inputKeyCount: getObjectKeyCount(params.input)
+            hasCode: !!params.code,
+            hasCallbackState: !!params.callbackState,
+            usesDefault: !adminSetup.handleCallback
           },
           onSuccess: (result) => ({
-            returnedInput: !!result.input,
-            hasCallbackState: !!result.callbackState
+            returnedInstructions: !!result.instructions
           })
         },
-        () => runWithContext(
-          context,
-          () => authMethod.getAuthorizationUrl({
-            redirectUri: params.redirectUri,
-            state: params.state,
-            input: params.input,
-            clientId: params.clientId,
-            clientSecret: params.clientSecret,
-            scopes: params.scopes,
-            config: getAuthConfig()
-          })
-        )
+        () => runWithContext(context, handleCallback)
       );
       return withRequestTraces(context, {
-        authorizationUrl: urlRes.url,
-        input: urlRes.input,
-        callbackState: urlRes.callbackState
+        instructions: callbackRes.instructions
       });
     }
     throw new ServiceError4(
       preconditionFailedError({
-        message: `Authentication method does not support authorization URL retrieval: ${params.authenticationMethodId}`
+        message: `Authentication method does not support admin setup: ${params.authenticationMethodId}`
       })
     );
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slates/provider-handler",
-  "version": "1.0.0-rc.40",
+  "version": "1.0.0-rc.42",
   "publishConfig": {
     "access": "public"
   },
@@ -32,8 +32,8 @@
   },
   "dependencies": {
     "@lowerdeck/error": "^1.1.0",
-    "@slates/proto": "1.0.0-rc.25",
-    "@slates/provider": "1.0.0-rc.30",
+    "@slates/proto": "1.0.0-rc.27",
+    "@slates/provider": "1.0.0-rc.32",
     "p-queue": "^6.6.2",
     "zod": "^4.2.1"
   },

package/src/adminSetup.test.ts

@@ -0,0 +1,189 @@
+import { SLATES_PROTOCOL_VERSION, SlatesProviderProtoHandlerManager } from '@slates/proto';
+import { describe, expect, it, vi } from 'vitest';
+import { z } from 'zod';
+import { createProviderHandler } from './index';
+
+let createManager = async (method: Record<string, any>) => {
+  let slate = {
+    spec: {
+      key: 'test',
+      name: 'Test',
+      auth: {
+        authStack: [
+          {
+            type: 'auth.oauth',
+            key: 'oauth',
+            name: 'OAuth',
+            scopes: [],
+            ...method
+          }
+        ],
+        outputSchema: z.object({ token: z.string() })
+      }
+    },
+    adapters: [],
+    actions: [],
+    triggerGroups: []
+  };
+  let manager = await createProviderHandler(slate as any, []).run();
+
+  await SlatesProviderProtoHandlerManager.handleInput(manager, {
+    jsonrpc: '2.0',
+    method: 'slates/hello',
+    params: { protocol: SLATES_PROTOCOL_VERSION }
+  });
+  await SlatesProviderProtoHandlerManager.handleInput(manager, {
+    jsonrpc: '2.0',
+    method: 'slates/participant.set',
+    params: { participants: [] }
+  });
+
+  return manager;
+};
+
+let baseParams = {
+  authenticationMethodId: 'oauth',
+  state: 'state-123',
+  redirectUri: 'https://hub.example/callback',
+  input: { tenant: 'acme' },
+  clientId: 'client-id',
+  clientSecret: 'client-secret',
+  scopes: ['read']
+};
+
+let getAdminAuthorizationUrl = (manager: SlatesProviderProtoHandlerManager) =>
+  SlatesProviderProtoHandlerManager.handleInput(manager, {
+    jsonrpc: '2.0',
+    id: 'url',
+    method: 'slates/auth.admin_authorization_url.get',
+    params: baseParams
+  });
+
+let handleAdminCallback = (
+  manager: SlatesProviderProtoHandlerManager,
+  params: { code?: string; callbackParams?: Record<string, string> } = {}
+) =>
+  SlatesProviderProtoHandlerManager.handleInput(manager, {
+    jsonrpc: '2.0',
+    id: 'callback',
+    method: 'slates/auth.admin_callback.handle',
+    params: { ...baseParams, ...params }
+  });
+
+let regularMethod = () => ({
+  getAuthorizationUrl: vi.fn(async () => ({
+    url: 'https://provider.example/authorize',
+    callbackState: { verifier: 'regular' }
+  })),
+  handleCallback: vi.fn(async () => ({ output: { token: 'user-token' } }))
+});
+
+describe('slates/auth.admin_authorization_url.get', () => {
+  it('falls back to the regular authorization URL', async () => {
+    let method = regularMethod();
+    let manager = await createManager({ ...method, adminSetup: {} });
+
+    expect(await getAdminAuthorizationUrl(manager)).toEqual({
+      jsonrpc: '2.0',
+      id: 'url',
+      result: {
+        authorizationUrl: 'https://provider.example/authorize',
+        callbackState: { verifier: 'regular' }
+      }
+    });
+    let { authenticationMethodId: _, ...ctx } = baseParams;
+    expect(method.getAuthorizationUrl).toHaveBeenCalledWith({ ...ctx, config: {} });
+  });
+
+  it('uses the admin authorization URL override', async () => {
+    let method = regularMethod();
+    let adminGetAuthorizationUrl = vi.fn(async () => ({
+      url: 'https://provider.example/adminconsent',
+      input: { tenant: 'acme' }
+    }));
+    let manager = await createManager({
+      ...method,
+      adminSetup: { getAuthorizationUrl: adminGetAuthorizationUrl }
+    });
+
+    expect(await getAdminAuthorizationUrl(manager)).toMatchObject({
+      result: {
+        authorizationUrl: 'https://provider.example/adminconsent',
+        input: { tenant: 'acme' }
+      }
+    });
+    expect(adminGetAuthorizationUrl).toHaveBeenCalledWith(
+      expect.objectContaining({ clientId: 'client-id', state: 'state-123', config: {} })
+    );
+    expect(method.getAuthorizationUrl).not.toHaveBeenCalled();
+  });
+
+  it('rejects methods without admin setup', async () => {
+    let manager = await createManager(regularMethod());
+
+    expect(await getAdminAuthorizationUrl(manager)).toMatchObject({
+      error: { code: 'request.precondition_failed' }
+    });
+  });
+});
+
+describe('slates/auth.admin_callback.handle', () => {
+  it('runs the regular callback and discards its output by default', async () => {
+    let method = regularMethod();
+    let manager = await createManager({ ...method, adminSetup: {} });
+
+    expect(await handleAdminCallback(manager, { code: 'admin-code' })).toEqual({
+      jsonrpc: '2.0',
+      id: 'callback',
+      result: {}
+    });
+    expect(method.handleCallback).toHaveBeenCalledWith(
+      expect.objectContaining({
+        code: 'admin-code',
+        clientId: 'client-id',
+        callbackParams: {},
+        callbackState: {},
+        config: {}
+      })
+    );
+  });
+
+  it('requires a code when falling back to the regular callback', async () => {
+    let method = regularMethod();
+    let manager = await createManager({ ...method, adminSetup: {} });
+
+    expect(await handleAdminCallback(manager)).toMatchObject({
+      error: { code: 'request.bad', message: expect.stringContaining('authorization code') }
+    });
+    expect(method.handleCallback).not.toHaveBeenCalled();
+  });
+
+  it('uses the admin callback override without a code', async () => {
+    let method = regularMethod();
+    let adminHandleCallback = vi.fn(async () => ({ instructions: '1. Trust the app.' }));
+    let manager = await createManager({
+      ...method,
+      adminSetup: { handleCallback: adminHandleCallback }
+    });
+
+    expect(
+      await handleAdminCallback(manager, { callbackParams: { admin_consent: 'True' } })
+    ).toMatchObject({ result: { instructions: '1. Trust the app.' } });
+    expect(adminHandleCallback).toHaveBeenCalledWith(
+      expect.objectContaining({
+        code: undefined,
+        callbackParams: { admin_consent: 'True' },
+        callbackState: {}
+      })
+    );
+    expect(method.handleCallback).not.toHaveBeenCalled();
+  });
+
+  it('rejects methods without admin setup', async () => {
+    let manager = await createManager(regularMethod());
+
+    expect(await handleAdminCallback(manager, { code: 'admin-code' })).toMatchObject({
+      error: { code: 'request.precondition_failed' }
+    });
+  });
+});

package/src/index.ts

@@ -7,6 +7,8 @@ import {
 import {
   createSlatesProviderProtoHandler,
   SLATES_PROTOCOL_VERSION,
+  type SlatesMessageAuthAdminCallbackHandleRequest,
+  type SlatesMessageAuthAuthorizationUrlGetRequest,
   type SlatesParticipant
 } from '@slates/proto';
 import {
@@ -344,6 +346,77 @@ export let createProviderHandler = <ConfigType extends {}, AuthType extends {}>(
       return requestTraces.length > 0 ? { ...result, requestTraces } : result;
     };
 
+    let buildAuthorizationUrlContext = (
+      params: SlatesMessageAuthAuthorizationUrlGetRequest['params']
+    ) => ({
+      redirectUri: params.redirectUri,
+      state: params.state,
+      input: params.input,
+      clientId: params.clientId,
+      clientSecret: params.clientSecret,
+      scopes: params.scopes,
+      config: getAuthConfig()
+    });
+
+    let buildCallbackContext = (
+      params: Omit<SlatesMessageAuthAdminCallbackHandleRequest['params'], 'code'>
+    ) => ({
+      state: params.state,
+      redirectUri: params.redirectUri,
+      input: params.input,
+      clientId: params.clientId,
+      clientSecret: params.clientSecret,
+      scopes: params.scopes,
+      callbackParams: params.callbackParams || {},
+      callbackState: params.callbackState || {},
+      config: getAuthConfig()
+    });
+
+    let getTracedAuthorizationUrl = async (
+      params: SlatesMessageAuthAuthorizationUrlGetRequest['params'],
+      authenticationMethodName: string,
+      trace: {
+        functionName: string;
+        message: string;
+        successMessage: string;
+        metadata?: Record<string, unknown>;
+      },
+      getAuthorizationUrl: (
+        ctx: ReturnType<typeof buildAuthorizationUrlContext>
+      ) => Promise<{ url: string; input?: any; callbackState?: Record<string, any> }>
+    ) => {
+      let context = getEmptyContext();
+      let urlRes = await traceProviderCall(
+        {
+          component: 'auth',
+          functionName: trace.functionName,
+          message: trace.message,
+          successMessage: trace.successMessage,
+          metadata: {
+            authenticationMethodId: params.authenticationMethodId,
+            authenticationMethodName,
+            scopeCount: params.scopes.length,
+            inputKeyCount: getObjectKeyCount(params.input),
+            ...trace.metadata
+          },
+          onSuccess: result => ({
+            returnedInput: !!result.input,
+            hasCallbackState: !!result.callbackState
+          })
+        },
+        () =>
+          runWithContext(context, () =>
+            getAuthorizationUrl(buildAuthorizationUrlContext(params))
+          )
+      );
+
+      return withRequestTraces(context, {
+        authorizationUrl: urlRes.url,
+        input: urlRes.input,
+        callbackState: urlRes.callbackState
+      });
+    };
+
     manager.onNotification('slates/hello', async ({ params }) => {
       protocol.set(params.protocol);
     });
@@ -681,18 +754,7 @@ export let createProviderHandler = <ConfigType extends {}, AuthType extends {}>(
           },
           () =>
             runWithContext(context, () =>
-              authMethod.handleCallback({
-                code: params.code,
-                state: params.state,
-                redirectUri: params.redirectUri,
-                input: params.input,
-                clientId: params.clientId,
-                clientSecret: params.clientSecret,
-                scopes: params.scopes,
-                callbackParams: params.callbackParams || {},
-                callbackState: params.callbackState || {},
-                config: getAuthConfig()
-              })
+              authMethod.handleCallback({ ...buildCallbackContext(params), code: params.code })
             )
         );
 
@@ -715,48 +777,108 @@ export let createProviderHandler = <ConfigType extends {}, AuthType extends {}>(
       let authMethod = getAuthMethod(slate, params.authenticationMethodId);
 
       if ('getAuthorizationUrl' in authMethod) {
-        let context = getEmptyContext();
-        let urlRes = await traceProviderCall(
+        return getTracedAuthorizationUrl(
+          params,
+          authMethod.name,
           {
-            component: 'auth',
             functionName: 'getAuthorizationUrl',
             message: 'Getting authentication authorization URL',
-            successMessage: 'Authentication authorization URL retrieved',
+            successMessage: 'Authentication authorization URL retrieved'
+          },
+          ctx => authMethod.getAuthorizationUrl(ctx)
+        );
+      }
+
+      throw new ServiceError(
+        preconditionFailedError({
+          message: `Authentication method does not support authorization URL retrieval: ${params.authenticationMethodId}`
+        })
+      );
+    });
+
+    manager.onRequest('slates/auth.admin_authorization_url.get', async ({ params }) => {
+      getContextBasic();
+      let authMethod = getAuthMethod(slate, params.authenticationMethodId);
+
+      if (authMethod.type === 'auth.oauth' && authMethod.adminSetup) {
+        let { adminSetup } = authMethod;
+        return getTracedAuthorizationUrl(
+          params,
+          authMethod.name,
+          {
+            functionName: 'adminSetup.getAuthorizationUrl',
+            message: 'Getting admin setup authorization URL',
+            successMessage: 'Admin setup authorization URL retrieved',
+            metadata: { usesDefault: !adminSetup.getAuthorizationUrl }
+          },
+          ctx =>
+            adminSetup.getAuthorizationUrl
+              ? adminSetup.getAuthorizationUrl(ctx)
+              : authMethod.getAuthorizationUrl(ctx)
+        );
+      }
+
+      throw new ServiceError(
+        preconditionFailedError({
+          message: `Authentication method does not support admin setup: ${params.authenticationMethodId}`
+        })
+      );
+    });
+
+    manager.onRequest('slates/auth.admin_callback.handle', async ({ params }) => {
+      getContextBasic();
+      let authMethod = getAuthMethod(slate, params.authenticationMethodId);
+
+      if (authMethod.type === 'auth.oauth' && authMethod.adminSetup) {
+        let { adminSetup } = authMethod;
+        let ctx = { ...buildCallbackContext(params), code: params.code };
+
+        let handleCallback = async (): Promise<{ instructions?: string }> => {
+          if (adminSetup.handleCallback) return adminSetup.handleCallback(ctx);
+
+          let code = ctx.code;
+          if (!code) {
+            throw new ServiceError(
+              badRequestError({
+                message: `Admin setup callback did not include an authorization code: ${params.authenticationMethodId}`
+              })
+            );
+          }
+
+          await authMethod.handleCallback({ ...ctx, code });
+          return {};
+        };
+
+        let context = getEmptyContext();
+        let callbackRes = await traceProviderCall(
+          {
+            component: 'auth',
+            functionName: 'adminSetup.handleCallback',
+            message: 'Handling admin setup callback',
+            successMessage: 'Admin setup callback handled',
             metadata: {
               authenticationMethodId: params.authenticationMethodId,
               authenticationMethodName: authMethod.name,
               scopeCount: params.scopes.length,
-              inputKeyCount: getObjectKeyCount(params.input)
+              hasCode: !!params.code,
+              hasCallbackState: !!params.callbackState,
+              usesDefault: !adminSetup.handleCallback
             },
             onSuccess: result => ({
-              returnedInput: !!result.input,
-              hasCallbackState: !!result.callbackState
+              returnedInstructions: !!result.instructions
             })
           },
-          () =>
-            runWithContext(context, () =>
-              authMethod.getAuthorizationUrl({
-                redirectUri: params.redirectUri,
-                state: params.state,
-                input: params.input,
-                clientId: params.clientId,
-                clientSecret: params.clientSecret,
-                scopes: params.scopes,
-                config: getAuthConfig()
-              })
-            )
+          () => runWithContext(context, handleCallback)
         );
 
         return withRequestTraces(context, {
-          authorizationUrl: urlRes.url,
-          input: urlRes.input,
-          callbackState: urlRes.callbackState
+          instructions: callbackRes.instructions
         });
       }
 
       throw new ServiceError(
         preconditionFailedError({
-          message: `Authentication method does not support authorization URL retrieval: ${params.authenticationMethodId}`
+          message: `Authentication method does not support admin setup: ${params.authenticationMethodId}`
         })
       );
     });

package/src/spec.test.ts

@@ -222,4 +222,25 @@ describe('mapAuthMethod', () => {
       expect(mapAuthMethod(slate, method)).not.toHaveProperty('syncTokensAcrossConnections');
     }
   });
+
+  it('omits the adminSetup capability when undeclared so existing spec hashes stay stable', () => {
+    expect(
+      mapAuthMethod(slate, { ...oauthMethod, adminSetup: {} }).capabilities
+    ).toMatchObject({ adminSetup: { enabled: true } });
+    expect(mapAuthMethod(slate, oauthMethod).capabilities).not.toHaveProperty('adminSetup');
+  });
+
+  it('always advertises whether admin setup is required, defaulting to false', () => {
+    expect(
+      mapAuthMethod(slate, { ...oauthMethod, adminSetup: {} }).capabilities.adminSetup
+    ).toEqual({ enabled: true, required: false });
+    expect(
+      mapAuthMethod(slate, { ...oauthMethod, adminSetup: { required: false } }).capabilities
+        .adminSetup
+    ).toEqual({ enabled: true, required: false });
+    expect(
+      mapAuthMethod(slate, { ...oauthMethod, adminSetup: { required: true } }).capabilities
+        .adminSetup
+    ).toEqual({ enabled: true, required: true });
+  });
 });

package/src/spec.ts

@@ -66,7 +66,10 @@ export let mapAuthMethod = <ConfigType extends {}, AuthType extends {}>(
     handleChangedInput: {
       enabled: !!m.onInputChanged
     },
-    getProfile: { enabled: !!m.getProfile }
+    getProfile: { enabled: !!m.getProfile },
+    ...('adminSetup' in m && m.adminSetup
+      ? { adminSetup: { enabled: true, required: m.adminSetup.required === true } }
+      : {})
   },
 
   docs: m.docs ?? []