Add external browser support for OAuth2 authorization (#375)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

plugins/auth-oauth2/src/index.ts

@@ -5,7 +5,9 @@ import type {
   JsonPrimitive,
   PluginDefinition,
 } from '@yaakapp/api';
+import { DEFAULT_LOCALHOST_PORT, HOSTED_CALLBACK_URL } from './callbackServer';
 import {
+  type CallbackType,
   DEFAULT_PKCE_METHOD,
   genPkceCodeVerifier,
   getAuthorizationCode,
@@ -134,8 +136,6 @@ export const plugin: PluginDefinition = {
         defaultValue: defaultGrantType,
         options: grantTypes,
       },
-
-      // Always-present fields
       {
         type: 'text',
         name: 'clientId',
@@ -169,11 +169,105 @@ export const plugin: PluginDefinition = {
         completionOptions: accessTokenUrls.map((url) => ({ label: url, value: url })),
       },
       {
-        type: 'text',
-        name: 'redirectUri',
-        label: 'Redirect URI',
-        optional: true,
-        dynamic: hiddenIfNot(['authorization_code', 'implicit']),
+        type: 'banner',
+        inputs: [
+          {
+            type: 'checkbox',
+            name: 'useExternalBrowser',
+            label: 'Use External Browser',
+            description:
+              'Open authorization URL in your system browser instead of the embedded browser. ' +
+              'Useful when the OAuth provider blocks embedded browsers or you need existing browser sessions.',
+            dynamic: hiddenIfNot(['authorization_code', 'implicit']),
+          },
+          {
+            type: 'text',
+            name: 'redirectUri',
+            label: 'Redirect URI',
+            description:
+              'URI the OAuth provider redirects to after authorization. Yaak intercepts this automatically in its embedded browser so any valid URI will work.',
+            optional: true,
+            dynamic: hiddenIfNot(
+              ['authorization_code', 'implicit'],
+              ({ useExternalBrowser }) => !useExternalBrowser,
+            ),
+          },
+          {
+            type: 'h_stack',
+            inputs: [
+              {
+                type: 'select',
+                name: 'callbackType',
+                label: 'Callback Type',
+                description:
+                  '"Hosted Redirect" uses an external Yaak-hosted endpoint. "Localhost" starts a local server to receive the callback.',
+                defaultValue: 'hosted',
+                options: [
+                  { label: 'Hosted Redirect', value: 'hosted' },
+                  { label: 'Localhost', value: 'localhost' },
+                ],
+                dynamic: hiddenIfNot(
+                  ['authorization_code', 'implicit'],
+                  ({ useExternalBrowser }) => !!useExternalBrowser,
+                ),
+              },
+              {
+                type: 'text',
+                name: 'callbackPort',
+                label: 'Callback Port',
+                placeholder: `${DEFAULT_LOCALHOST_PORT}`,
+                description:
+                  'Port for the local callback server. Defaults to ' +
+                  DEFAULT_LOCALHOST_PORT +
+                  ' if empty.',
+                optional: true,
+                dynamic: hiddenIfNot(
+                  ['authorization_code', 'implicit'],
+                  ({ useExternalBrowser, callbackType }) =>
+                    !!useExternalBrowser && callbackType === 'localhost',
+                ),
+              },
+            ],
+          },
+          {
+            type: 'banner',
+            color: 'info',
+            inputs: [
+              {
+                type: 'markdown',
+                content: 'Redirect URI to Register',
+                async dynamic(_ctx, { values }) {
+                  const grantType = String(values.grantType ?? defaultGrantType);
+                  const useExternalBrowser = !!values.useExternalBrowser;
+                  const callbackType = (stringArg(values, 'callbackType') ||
+                    'localhost') as CallbackType;
+
+                  // Only show for authorization_code and implicit with external browser enabled
+                  if (
+                    !['authorization_code', 'implicit'].includes(grantType) ||
+                    !useExternalBrowser
+                  ) {
+                    return { hidden: true };
+                  }
+
+                  // Compute the redirect URI based on callback type
+                  let redirectUri: string;
+                  if (callbackType === 'hosted') {
+                    redirectUri = HOSTED_CALLBACK_URL;
+                  } else {
+                    const port = intArg(values, 'callbackPort') || DEFAULT_LOCALHOST_PORT;
+                    redirectUri = `http://127.0.0.1:${port}/callback`;
+                  }
+
+                  return {
+                    hidden: false,
+                    content: `Register \`${redirectUri}\` as a redirect URI with your OAuth provider.`,
+                  };
+                },
+              },
+            ],
+          },
+        ],
       },
       {
         type: 'text',
@@ -182,12 +276,8 @@ export const plugin: PluginDefinition = {
         optional: true,
         dynamic: hiddenIfNot(['authorization_code', 'implicit']),
       },
-      {
-        type: 'text',
-        name: 'audience',
-        label: 'Audience',
-        optional: true,
-      },
+      { type: 'text', name: 'scope', label: 'Scope', optional: true },
+      { type: 'text', name: 'audience', label: 'Audience', optional: true },
       {
         type: 'select',
         name: 'tokenName',
@@ -203,44 +293,54 @@ export const plugin: PluginDefinition = {
         dynamic: hiddenIfNot(['authorization_code', 'implicit']),
       },
       {
-        type: 'checkbox',
-        name: 'usePkce',
-        label: 'Use PKCE',
-        dynamic: hiddenIfNot(['authorization_code']),
-      },
-      {
-        type: 'select',
-        name: 'pkceChallengeMethod',
-        label: 'Code Challenge Method',
-        options: [
-          { label: 'SHA-256', value: PKCE_SHA256 },
-          { label: 'Plain', value: PKCE_PLAIN },
+        type: 'banner',
+        inputs: [
+          {
+            type: 'checkbox',
+            name: 'usePkce',
+            label: 'Use PKCE',
+            dynamic: hiddenIfNot(['authorization_code']),
+          },
+          {
+            type: 'select',
+            name: 'pkceChallengeMethod',
+            label: 'Code Challenge Method',
+            options: [
+              { label: 'SHA-256', value: PKCE_SHA256 },
+              { label: 'Plain', value: PKCE_PLAIN },
+            ],
+            defaultValue: DEFAULT_PKCE_METHOD,
+            dynamic: hiddenIfNot(['authorization_code'], ({ usePkce }) => !!usePkce),
+          },
+          {
+            type: 'text',
+            name: 'pkceCodeChallenge',
+            label: 'Code Verifier',
+            placeholder: 'Automatically generated when not set',
+            optional: true,
+            dynamic: hiddenIfNot(['authorization_code'], ({ usePkce }) => !!usePkce),
+          },
         ],
-        defaultValue: DEFAULT_PKCE_METHOD,
-        dynamic: hiddenIfNot(['authorization_code'], ({ usePkce }) => !!usePkce),
       },
       {
-        type: 'text',
-        name: 'pkceCodeChallenge',
-        label: 'Code Verifier',
-        placeholder: 'Automatically generated when not set',
-        optional: true,
-        dynamic: hiddenIfNot(['authorization_code'], ({ usePkce }) => !!usePkce),
-      },
-      {
-        type: 'text',
-        name: 'username',
-        label: 'Username',
-        optional: true,
-        dynamic: hiddenIfNot(['password']),
-      },
-      {
-        type: 'text',
-        name: 'password',
-        label: 'Password',
-        password: true,
-        optional: true,
-        dynamic: hiddenIfNot(['password']),
+        type: 'h_stack',
+        inputs: [
+          {
+            type: 'text',
+            name: 'username',
+            label: 'Username',
+            optional: true,
+            dynamic: hiddenIfNot(['password']),
+          },
+          {
+            type: 'text',
+            name: 'password',
+            label: 'Password',
+            password: true,
+            optional: true,
+            dynamic: hiddenIfNot(['password']),
+          },
+        ],
       },
       {
         type: 'select',
@@ -258,7 +358,6 @@ export const plugin: PluginDefinition = {
         type: 'accordion',
         label: 'Advanced',
         inputs: [
-          { type: 'text', name: 'scope', label: 'Scope', optional: true },
           {
             type: 'text',
             name: 'headerName',
@@ -321,6 +420,16 @@ export const plugin: PluginDefinition = {
       const credentialsInBody = values.credentials === 'body';
       const tokenName = values.tokenName === 'id_token' ? 'id_token' : 'access_token';
 
+      // Build external browser options if enabled
+      const useExternalBrowser = !!values.useExternalBrowser;
+      const externalBrowserOptions = useExternalBrowser
+        ? {
+            useExternalBrowser: true,
+            callbackType: (stringArg(values, 'callbackType') || 'localhost') as CallbackType,
+            callbackPort: intArg(values, 'callbackPort') ?? undefined,
+          }
+        : undefined;
+
       let token: AccessToken;
       if (grantType === 'authorization_code') {
         const authorizationUrl = stringArg(values, 'authorizationUrl');
@@ -348,6 +457,7 @@ export const plugin: PluginDefinition = {
               }
             : null,
           tokenName: tokenName,
+          externalBrowser: externalBrowserOptions,
         });
       } else if (grantType === 'implicit') {
         const authorizationUrl = stringArg(values, 'authorizationUrl');
@@ -362,6 +472,7 @@ export const plugin: PluginDefinition = {
           audience: stringArgOrNull(values, 'audience'),
           state: stringArgOrNull(values, 'state'),
           tokenName: tokenName,
+          externalBrowser: externalBrowserOptions,
         });
       } else if (grantType === 'client_credentials') {
         const accessTokenUrl = stringArg(values, 'accessTokenUrl');
@@ -414,3 +525,10 @@ function stringArg(values: Record<string, JsonPrimitive | undefined>, name: stri
   if (!arg) return '';
   return arg;
 }
+
+function intArg(values: Record<string, JsonPrimitive | undefined>, name: string): number | null {
+  const arg = values[name];
+  if (arg == null || arg === '') return null;
+  const num = parseInt(`${arg}`, 10);
+  return Number.isNaN(num) ? null : num;
+}