Implementation:Langgenius Dify UseOAuth

Knowledge Sources	Langgenius_Dify
Domains	Frontend, Authentication
Last Updated	2026-02-08 00:00 GMT

Overview

Provides a React hook and utility function for managing OAuth authorization flows via popup windows with cross-window message passing.

Description

This module implements a two-part OAuth popup flow. The useOAuthCallback hook is used in the popup (callback) page: on mount, it reads query parameters (subscription_id, error, error_description) from the URL and sends the result back to the opener window via window.postMessage using a structured message with type 'oauth_callback'. It uses window.opener.origin as the target origin for security rather than the wildcard '*'. After posting the message, the popup closes itself.

The openOAuthPopup utility function is used in the parent page to initiate the flow. It validates the authorization URL using validateRedirectUrl (allowing only HTTP/HTTPS protocols), opens a centered popup window, and sets up a message event listener to receive the OAuth callback data. It also includes a fallback polling mechanism that checks every second whether the popup was closed by the user (without completing the OAuth flow), in which case it invokes the callback with no data. The message listener is cleaned up after receiving a response or detecting popup closure.

Usage

Use openOAuthPopup in parent pages to launch an OAuth authorization popup, and mount useOAuthCallback in the popup callback page to relay the result. This pattern is used for third-party integrations such as subscription-based provider authorization.

Code Reference

Source Location

• Repository: Langgenius_Dify
• File: web/hooks/use-oauth.ts

Signature

export const useOAuthCallback = () => void

export const openOAuthPopup = (
  url: string,
  callback: (data?: any) => void,
) => Window | null

Import

import { useOAuthCallback, openOAuthPopup } from '@/hooks/use-oauth'

I/O Contract

Inputs

useOAuthCallback:

Name	Type	Required	Description
(none)	-	-	Reads subscription_id, error, and error_description from URL query parameters automatically

openOAuthPopup:

Name	Type	Required	Description
url	string	Yes	The OAuth authorization URL to open in the popup; must be HTTP or HTTPS
callback	(data?: any) => void	Yes	Function called with the OAuth result data (or undefined if the popup was closed without completing)

Outputs

useOAuthCallback:

Name	Type	Description
(none)	void	Side-effect only: posts message to opener and closes the popup window

openOAuthPopup:

Name	Type	Description
popup	null	Reference to the opened popup window (null if blocked by browser)

Callback data shape:

Name	Type	Description
type	'oauth_callback'	Message type identifier
success	boolean	Whether the OAuth flow succeeded (present when subscription_id or error is found)
subscriptionId	string	The subscription identifier returned on success
error	string	Error code returned on failure
errorDescription	string	Human-readable error description

Usage Examples

// In the parent page - initiating OAuth
import { openOAuthPopup } from '@/hooks/use-oauth'

function ConnectProviderButton({ authUrl }: { authUrl: string }) {
  const handleConnect = () => {
    openOAuthPopup(authUrl, (data) => {
      if (!data) {
        console.log('Popup closed without completing OAuth')
        return
      }
      if (data.success) {
        console.log('OAuth succeeded, subscription:', data.subscriptionId)
      } else {
        console.error('OAuth failed:', data.error, data.errorDescription)
      }
    })
  }

  return <button onClick={handleConnect}>Connect Provider</button>
}

// In the callback page - relaying OAuth result
import { useOAuthCallback } from '@/hooks/use-oauth'

function OAuthCallbackPage() {
  useOAuthCallback()
  return <div>Processing authorization...</div>
}

Related Pages

• Implementation:Langgenius_Dify_URL_Validation - validateRedirectUrl used to ensure the OAuth URL is safe
• Implementation:Langgenius_Dify_UseAsyncWindowOpen - Alternative hook for async window management
• Implementation:Langgenius_Dify_UsePay - Payment hooks that also handle third-party callback flows