メインコンテンツへスキップ
⚠️ このドキュメントはAIによって自動翻訳されています。不正確な部分がある場合は、英語版を参照してください。
b0e673ba3e339b31ac36dc3cd004df04787bcaa64bb6d2cac6feb7152b7b515f.png このガイドでは、ツールプラグインにOAuthサポートを組み込む方法を説明します。 OAuthは、GmailやGitHubなどのサードパーティサービスからユーザーデータにアクセスする必要があるツールプラグインを認可するためのより優れた方法です。ユーザーがAPIキーを手動で入力する必要がなく、OAuthを使用することでツールはユーザーの明示的な同意のもとでユーザーに代わって動作できます。

​
背景

DifyにおけるOAuthには、開発者が理解し設計すべき2つの別々のフローがあります。

​
フロー1: OAuthクライアントセットアップ（管理者/開発者フロー）

Dify Cloudでは、Difyチームが人気のあるツールプラグイン用のOAuthアプリを作成し、OAuthクライアントをセットアップするため、ユーザーは自分で設定する手間が省けます。セルフホストDifyインスタンスの管理者は、このセットアップフローを実行する必要があります。
Difyインスタンスの管理者または開発者は、まずサードパーティサービスに信頼できるアプリケーションとしてOAuthアプリを登録する必要があります。これにより、DifyツールプロバイダーをOAuthクライアントとして設定するために必要な資格情報を取得できます。 例として、DifyのGmailツールプロバイダー用のOAuthクライアントをセットアップする手順を示します：
  1. Google Cloud Consoleにアクセスし、新しいプロジェクトを作成するか、既存のプロジェクトを選択します
  2. 必要なAPI（例：Gmail API）を有効にします
  1. APIs & Services > OAuth consent screenに移動します
  2. 公開プラグインの場合はExternalユーザータイプを選択します
  3. アプリケーション名、ユーザーサポートメール、開発者連絡先を入力します
  4. 必要に応じて承認済みドメインを追加します
  5. テストの場合：Test usersセクションでテストユーザーを追加します
  1. APIs & Services > Credentialsに移動します
  2. Create Credentials > OAuth 2.0 Client IDsをクリックします
  3. Web applicationタイプを選択します
  4. client_idとclient_secretが生成されます。これらを資格情報として保存します。
OAuthクライアント設定ポップアップにclient_idとclient_secretを入力して、ツールプロバイダーをクライアントとしてセットアップします。acd5f5057235c3a0c554abaedcf276fb48f80567f0231eae9158a795f8e1c45d.png
Difyが生成したリダイレクトURIをGoogle OAuthクライアントのページに登録します：dfe60a714a275c5bf65f814673bd2f0a0db4fda27573a2f0b28a1c39e4c61da2.png
Difyはredirect_uriをOAuthクライアント設定ポップアップに表示します。通常、次の形式に従います：
https://{your-dify-domain}/console/api/oauth/plugin/{plugin-id}/{provider-name}/{tool-name}/callback
セルフホストDifyの場合、your-dify-domainはCONSOLE_WEB_URLと一致する必要があります。
各サービスには固有の要件があるため、統合するサービスの特定のOAuthドキュメントを必ず参照してください。

​
フロー2: ユーザー認可（Difyユーザーフロー）

OAuthクライアントを設定した後、個々のDifyユーザーは、プラグインが自分の個人アカウントにアクセスすることを認可できるようになります。 833c205f5441910763b27d3e3ff0c4449a730a690da91abc3ce032c70da04223.png

​
実装

​
1. プロバイダーマニフェストでOAuthスキーマを定義する

プロバイダーマニフェストのoauth_schemaセクションは、プラグインのOAuthに必要な資格情報と、OAuthフローが生成するものをDifyに伝えます。OAuthをセットアップするには、2つのスキーマが必要です：

​
client_schema

OAuthクライアントセットアップの入力を定義します：
gmail.yaml
oauth_schema:
  client_schema:
    - name: "client_id"
      type: "secret-input"
      required: true
      url: "https://developers.google.com/identity/protocols/oauth2"
    - name: "client_secret"
      type: "secret-input" 
      required: true
urlフィールドはサードパーティサービスのヘルプドキュメントに直接リンクします。これは困っている管理者/開発者の助けになります。

​
credentials_schema

ユーザー認可フローが生成するものを指定します（Difyがこれらを自動的に管理します）： 
# also under oauth_schema
  credentials_schema:
    - name: "access_token"
      type: "secret-input"
    - name: "refresh_token"
      type: "secret-input"
    - name: "expires_at"
      type: "secret-input"
OAuth + APIキー認証オプションを提供するには、oauth_schemaとcredentials_for_providerの両方を含めてください。

​
2. ツールプロバイダーで必要なOAuthメソッドを完成させる

ToolProviderを実装している場所に、以下のインポートを追加します： 
from dify_plugin.entities.oauth import ToolOAuthCredentials
from dify_plugin.errors.tool import ToolProviderCredentialValidationError, ToolProviderOAuthError
ToolProviderクラスは、これら3つのOAuthメソッドを実装する必要があります（例としてGmailProviderを使用）：
いかなる場合でも、ToolOAuthCredentialsの資格情報にclient_secretを返してはなりません。これはセキュリティ上の問題につながる可能性があります。
def _oauth_get_authorization_url(self, redirect_uri: str, system_credentials: Mapping[str, Any]) -> str:
	"""
	Generate the authorization URL using credentials from OAuth Client Setup Flow. 
    This URL is where users grant permissions.
    """
    # Generate random state for CSRF protection (recommended for all OAuth flows)
    state = secrets.token_urlsafe(16)
    
    # Define Gmail-specific scopes - request minimal necessary permissions
    scope = "read:user read:data"  # Replace with your required scopes
    
    # Assemble Gmail-specific payload
    params = {
        "client_id": system_credentials["client_id"],    # From OAuth Client Setup
        "redirect_uri": redirect_uri,                    # Dify generates this - DON'T modify
        "scope": scope,                                  
        "response_type": "code",                         # Standard OAuth authorization code flow
        "access_type": "offline",                        # Critical: gets refresh token (if supported)
        "prompt": "consent",                             # Forces reauth when scopes change (if supported)
        "state": state,                                  # CSRF protection
    }
    
    return f"{self._AUTH_URL}?{urllib.parse.urlencode(params)}"

​
3. ツールでトークンにアクセスする

Tool実装でOAuth資格情報を使用して認証済みAPI呼び出しを行うことができます： 
class YourTool(BuiltinTool):
    def _invoke(self, user_id: str, tool_parameters: dict[str, Any]) -> ToolInvokeMessage:
        if self.runtime.credential_type == CredentialType.OAUTH:
            access_token = self.runtime.credentials["access_token"]
        
        response = requests.get("https://api.service.com/data",
                              headers={"Authorization": f"Bearer {access_token}"})
        return self.create_text_message(response.text)
self.runtime.credentialsは現在のユーザーのトークンを自動的に提供します。Difyはリフレッシュを自動的に処理します。 OAuthとAPI_KEY認証の両方をサポートするプラグインの場合、self.runtime.credential_typeを使用して2つの認証タイプを区別できます。

​
4. 正しいバージョンを指定する

以前のバージョンのプラグインSDKとDifyはOAuth認証をサポートしていません。そのため、プラグインSDKのバージョンを以下に設定する必要があります： 
dify_plugin>=0.4.2,<0.5.0.
manifest.yamlに、最小Difyバージョンを追加します： 
meta:
  version: 0.0.1
  arch:
    - amd64
    - arm64
  runner:
    language: python
    version: "3.12"
    entrypoint: main
  minimum_dify_version: 1.7.1
Edit this page | Report an issue