When a Dify tool plugin with OAuth is the right build
Build a Dify tool plugin with OAuth when an internal system must be called from workflows or agents on behalf of each user, so the target system sees the individual's identity and permissions rather than one shared service account. The typical case is a ticketing, document or HR system where the answer depends on who is asking. A plain API key stored in a tool configuration cannot express that, and an OpenAPI tool may not cover the consent and token refresh flow the target system requires. Confirm first that the system supports an OAuth authorization flow your Dify instance can reach, and that its scopes map to what each workflow needs.
In Dify, a tool plugin is the module that exposes callable actions to workflows and agents. It is one of several plugin types, and it is the one that carries OAuth configuration for the target system, including the authorization and token endpoints, client registration and the scopes requested. Dify handles the per-user authorization step in the console, so the plugin's job is to define the provider's credential schema and implement the tool calls against the token it receives. Confirm the exact OAuth configuration fields against the plugin documentation for your Dify version, since the schema is set by the plugin SDK rather than by this page.
Before committing to this build, compare it with the cheaper alternatives covered elsewhere in this group. If the target system has a well-defined REST API and a service identity is acceptable for the use case, a custom tool from an OpenAPI schema may be enough. If the need is to start workflows from events, or to index documents, a different plugin type fits better. Treat the OAuth build as justified when per-user identity, audit at the target system and revocation by the user are requirements, and plan for ongoing work: the client secret, redirect URLs and token lifetimes all need owners, and changes to the target system's API will require plugin releases.
What a Dify tool plugin with OAuth does
A Dify tool plugin with OAuth has four connected parts: the tool the workflow calls, the credential schema that collects connection settings, the OAuth flow that acts for each user, and the plugin runtime that executes the code inside a self-hosted Dify. Each part shapes the others, so decide them together before writing code. Confirm every interface name against the current Dify plugin developer documentation before you build.
The tool and its parameters
A tool plugin exposes one or more tools that a workflow or agent can call, each with named input parameters and a structured result. The parameter list is the contract the model and the workflow see, so it should describe only what the internal system needs. Check whether each parameter should be filled by the model, by a fixed workflow value or by the user, because that choice changes how the tool is called and what it may do.
Credential schema for connection settings
The credential schema declares the fields an administrator or user fills in before a tool can run, such as the base URL of the internal system and the OAuth client identifier. Keep secrets such as client secrets in fields the platform treats as sensitive, and keep the schema limited to what is needed to connect. Confirm which field types and validation hooks the current plugin SDK supports before you rely on them.
User-delegated OAuth flow
In the OAuth flow, each user authorizes the plugin to act against the internal system with that user's own permissions, so the tool cannot see more data than the person running it. The plugin must handle the authorization redirect, exchange the code for tokens, store them and refresh them before expiry. Verify with the internal identity provider which grant types, scopes and redirect URIs it supports, and whether refresh tokens are issued at all.
Per-workspace credential handling
Credentials belong to the workspace where they were entered, so one installed plugin can hold different tokens for different teams. Plan which identity owns each connection, who may create or revoke it and what happens when a user leaves the workspace. Confirm how the Dify version you run stores tokens and how SECRET_KEY affects existing encrypted credentials before any change to that key.
Plugin runtime inside the self-hosted stack
The plugin does not run inside the api service. It runs in the plugin daemon, which starts it, passes requests and returns results, and it sits beside the other core services in a Docker Compose deployment. Outbound calls to the internal system pass through the platform's outbound request controls, so the internal host may need an explicit allowance. Test that path in your own environment, since network rules differ by deployment.
Packaging and version changes
The finished plugin is packaged as a .difypkg file that you install and upgrade like any other plugin. Each release changes the manifest, the schema or the OAuth settings, so record which version holds which credentials and test the upgrade path on a copy first. Minor Dify releases arrive about monthly, so plugin compatibility should be rechecked against each target version.
Which OAuth and credential choices fit your internal system
This table compares the credential and grant choices that change how a Dify tool plugin is built, operated and revoked. Read each row against your internal system's identity model, then check the audit and revocation column before choosing a path. The main takeaway: user-delegated OAuth gives per-person audit trails but adds token storage work, while a workspace service credential is simpler to build and shifts accountability to the workspace.
| Choice | Best fit | Audit and revocation effect | When to avoid it |
|---|---|---|---|
| User-delegated OAuth (authorization code flow) | Internal system must act as the signed-in user and respect that user's permissions | Actions are logged under each person; revoking one user's grant cuts only that user's access | Shared mailboxes or batch jobs with no human owner |
| Workspace service credential (client credentials flow) | Automated tool calls that need one fixed system identity across the workspace | Logs show one service identity; revocation affects every workspace user at once | Anything that must enforce per-user record-level permissions |
| Refresh token storage in the plugin credential store | Long-lived user sessions where users should not re-consent often | Refresh tokens extend access; confirm how the target system lets you revoke them centrally | Target system issues long-lived refresh tokens with no revocation API |
| Short-lived access tokens with re-consent on expiry | Sensitive systems where stolen tokens must age out quickly | Smaller exposure window; more user prompts and more failed calls to triage | High-frequency tools where users would be prompted constantly |
| Custom tool or OpenAPI tool with an API key | Simple read-only internal REST API with a static, scoped key already approved by your security team | Single key shared by workspace; rotation is manual and changes are not tied to users | Anything needing user identity, consent screens or fine-grained scopes |
| Full plugin with OAuth handling | Multi-step auth, token refresh, per-workspace credentials and custom error handling | Your team owns token lifecycle, logging and revocation logic in code | Teams without a maintainer for the plugin after launch |
How the build runs from OAuth registration to a verified package
The sequence turns an internal system that needs per-user authorization into a signed-off .difypkg that has been installed in a test workspace and shown to keep each workspace's credentials separate. Each step hands a named artifact to the next, so the team can stop at any gate and know what exists.
Register the OAuth client with the identity provider
The identity or platform team registers an OAuth client for the plugin in the internal identity provider, using the redirect URI that Dify's plugin callback will use in your environment. Confirm the exact redirect format, the grant type and the token lifetimes with the identity provider's documentation and your security team before anything else is built. Output: a client ID and secret stored in your secrets manager, a written list of scopes, and a short record of who approved them. The step is done when a manual authorization test returns a token for a test user.
Define the tool and credential schema
The plugin author writes the tool definitions, their input parameters and the credential fields the workspace administrator fills in, such as the OAuth client settings and the base URL of the internal API. Keep the parameters narrow so the model cannot pass arbitrary paths or scopes into the request. Output: a manifest and provider YAML that declare each tool, its parameters and the credential schema, reviewed by the owner of the internal system. The step is done when a Dify plugin scaffold loads without schema errors.
Implement the token exchange and tool calls
The developer implements the authorization code exchange, stores the refresh token encrypted through the plugin's credential handling, refreshes access tokens before they expire and maps each tool to one internal API call. Errors such as revoked consent or expired refresh tokens should surface as clear messages that tell the user to reauthorize. Output: source code with unit tests for token refresh and error paths. The step is done when the tests pass against a mocked identity provider.
Test against a non-production instance
The team runs the plugin against a non-production Dify instance and a non-production copy of the internal system, with the plugin daemon configured the same way as production. Verify that calls to internal hosts pass through the outbound request controls you have set, including the SSRF proxy allowlist, and that the token never appears in logs or in workflow outputs. Output: a test record listing each tool, the scenarios run and the defects fixed. The step is done when every tool passes its scenarios with no credential leakage in logs.
Package the plugin as a .difypkg file
The developer builds the plugin into a .difypkg package using the packaging command from the Dify plugin toolchain, tags the release with a version number and records a checksum of the file. Confirm the signing approach your environment requires before distribution, since production instances may enforce signature checks. Output: a versioned .difypkg file, its checksum and a release note describing the scopes and credentials the plugin needs. The step is done when the package installs on the test instance from the file alone.
Install in a test workspace
An administrator installs the .difypkg into a test workspace and configures credentials there, using a test OAuth client or test tenant where possible. Confirm that the install does not expose the plugin to other workspaces unless that was intended. Output: an install record with the plugin version, the workspace name and the administrator who performed the install. The step is done when a workflow in the test workspace calls each tool and returns data for the authorized user only.
Verify per-workspace credential isolation
The tester configures a second workspace with different OAuth credentials and confirms that tokens, consent records and refresh behavior stay separate, and that removing a credential in one workspace does not affect the other. Check that the workspace encryption and SECRET_KEY settings are documented so that the encrypted credentials can be recovered after a restore. Output: a signed isolation test report with the scenarios, results and any open findings. The step is done when the report shows no cross-workspace credential use and the owners accept the residual risks in writing.
How credentials stay separate per workspace
The OAuth credentials your plugin uses are encrypted at rest with the instance's SECRET_KEY, according to the Dify environment reference, which also says that changing this key after deployment logs out all users. Treat SECRET_KEY as a value you generate once, store in your secrets manager and never rotate casually, because a change affects every workspace on the instance at the same moment. Workspace encryption keys are a separate control: the same reference says they can be stored locally or in Azure Key Vault, so decide before go-live which option meets your key custody requirements. Confirm in the target Dify version exactly which key protects tool credentials in each workspace, since the answer determines what a key rotation or a restore from backup actually requires.
Per-workspace separation depends on where the authorization grant lives. In a typical design, each workspace that authorizes the tool stores its own token set, so one team's connection to the internal system is not visible to another workspace. Test this rather than assume it: create the tool authorization in workspace A, confirm workspace B cannot use or read it, and check what happens to the stored token when a member who authorized it is removed from the workspace. Confirm whether the credential persists under the workspace, is revoked, or stops working until someone re-authorizes, and document the answer for your support team. Also confirm how refresh tokens are handled and whether a revoked grant on the internal identity provider is reflected in Dify without manual cleanup.
Decide the offboarding procedure before the first workspace uses the plugin. The safe default is to revoke the grant on the internal system's side and remove the stored authorization in Dify as part of the leaver process, not to rely on account deactivation alone. Ask your platform team to verify this in a staging workspace with a test identity: remove the user, confirm the token no longer calls the internal API, and check the audit trail on the internal system. Record the Dify version you tested, because credential handling changes between releases, and repeat the check after each upgrade.
What drives the effort and cost of an OAuth tool plugin
This table lists the factors that change how much work an OAuth tool plugin takes and who pays for it. Read each row as a question to answer in the written scope, because most of the cost comes from the number of APIs, identity provider behavior and the number of workspaces that must share one package.
| Driver | Why it changes effort or cost | What to ask for in a written scope |
|---|---|---|
| Number of internal APIs and scopes | Each endpoint needs its own tool definition, parameter schema and error handling, and each scope needs a consent path tested end to end. | A list of endpoints and OAuth scopes, with the tools each one maps to and who approves scope changes. |
| Identity provider complexity | Authorization endpoints, token formats, PKCE support, custom claims and tenant rules differ by provider, and each difference adds test cases. | The identity provider name and version, the grant type used, and whether a test tenant is available during build. |
| Token refresh and revocation behavior | Refresh logic, expiry handling and revoked-consent recovery must work when a user leaves or changes roles, which is often the hardest part to verify. | Documented token lifetimes, refresh rules, revocation method and the expected behavior when a refresh fails. |
| Number of workspaces | Credentials are stored per workspace, so each workspace needs its own authorization flow, and rollout is repeated for every workspace that uses the plugin. | The count of workspaces at launch, the process for adding new ones, and who authorizes each workspace's credentials. |
| SSRF proxy allowlist testing | Internal hosts are blocked by default in the outbound proxy path, so the allowlist entries, DNS names and ports must be set and tested in the same environment as production. | The internal hostnames and ports to allow, the change process owner, and a test that confirms the plugin reaches each host. |
| Release cadence against Dify minor releases | Dify ships minor releases roughly monthly, so the plugin must be retested against each supported version and any API or packaging change must be tracked. | The Dify versions in scope, the regression test set, the upgrade window and who pays for retesting after each Dify release. |
| Ownership after handover | Someone must rotate client secrets, respond to revoked consents and publish new packages, and that work recurs for as long as the plugin is in use. | Support hours, escalation contacts, who holds signing and client secret material, and the retainer terms if ongoing work is needed. |
Questions teams ask before building an OAuth tool plugin
How much does it cost to build a Dify tool plugin with OAuth?
Cost depends on how many internal systems the plugin calls, how complex the OAuth grant and token handling is, and how many workspaces will use it. Most of the spend goes to three things: the OAuth integration with your identity provider and the internal system, the tool schema and error handling, and testing across workspaces. Ongoing costs come from maintaining the plugin through Dify releases and rotating client credentials. DeployOpen does not publish a price list. Ask for a quote built from a written scope that names each internal API, each OAuth grant type and each workspace that will run the plugin.
How long does an OAuth tool plugin take to build?
Duration follows the scope. The main drivers are how many OAuth flows must work, whether your identity team can issue a client registration quickly, how well the internal API is documented, and how many review cycles your security team needs before release. A single read-only API behind one identity provider is a smaller job than several write-capable endpoints that must respect per-user permissions. Ask the partner to show the phases, the dependencies on your teams and the points where your sign-off is required.
What does our team need to provide for the engagement?
Plan to provide access and decisions rather than code alone. You will need a test instance of the internal system, an OAuth client registration from your identity provider with agreed redirect URLs, the scopes each tool may request, sample API responses including error cases, and a named owner who approves the permission model. You also need a self-hosted Dify test environment where the plugin can be installed. Confirm which of these your teams can supply and on what timeline before work starts.
Can our internal team build an OAuth tool plugin without a partner?
Yes, if the team has experience with Python or Node-based plugin development, OAuth 2.0 authorization code flows and the way your identity provider issues tokens. The harder parts are usually not the plugin code. They are token storage per workspace, refresh behavior, the Dify SSRF proxy allowlist for internal hosts, and the signing and distribution steps that keep production checks on. Assess these skills honestly, then decide whether a partner should cover the design and security review while your team builds the tool.
How does a partner scope a Dify plugin engagement?
A partner should start with a discovery session that inventories the internal APIs, the OAuth provider and grant types, the users and workspaces involved, and the data each tool can read or change. The output is a written scope with deliverables, acceptance tests, assumptions and the responsibilities of each party. Most engagements are fixed-scope, so the agreement should list the tools included, the workspaces covered, the packaging format and the handover materials. Anything outside that list should go through a change request.
How do Dify updates affect a custom OAuth tool plugin?
Dify ships minor releases roughly monthly, so a plugin needs a regression check against each target version before it is upgraded in production. Plugin interfaces, the plugin daemon and the way credentials are stored can change between releases, and the upgrade guide for each version should be read before you move. Keep the plugin versioned, test it on a staging instance first, and back up the instance before every upgrade. Also check the environment variable reference for new settings that affect the plugin, such as the secret key that encrypts OAuth credentials.
What security questions should we answer before building the plugin?
Settle the permission model first: whether tools act with the end user's delegated token or a service identity, which scopes are requested, how tokens are stored and refreshed, and who can revoke access. Changing the encryption secret after deployment logs out all users and affects stored OAuth credentials, so plan key management before go-live. Confirm that outbound requests to internal hosts pass through the SSRF proxy allowlist, and have your security team review the package before it reaches production.
Operating and upgrading the plugin after go-live
The plugin needs ongoing ownership from the day it reaches production, because three things change on their own: the OAuth client secret expires or is rotated, the internal system's token behavior drifts, and Dify itself moves forward. Plan a rotation procedure for the OAuth client secret before go-live, including where the new value is stored, which workspaces hold credentials for the plugin, and how the change is tested in a staging instance first. Confirm with the identity provider owner how refresh tokens are revoked on rotation, since a rotated secret that leaves old refresh tokens alive is a gap an auditor will ask about.
Token failures are the first signal that something has broken, and they often appear as tool errors inside user workflows rather than as platform alerts. Log the status codes returned by the internal system's token endpoint and by the protected API, group failures by workspace, and alert on spikes in 401 and 403 responses. Review the plugin daemon settings with the platform team as part of each upgrade, specifically the timeouts, package and file size limits, and any remote debugging port left open, because a plugin that calls a slow internal API can hit a daemon timeout that looks like an OAuth fault. Confirm the current names and defaults in the environment reference before changing anything.
Dify ships minor releases roughly monthly, so the plugin must be retested against each target version and re-packaged when the SDK or plugin interface it depends on changes. Before every Dify upgrade, take a backup as the Docker Compose documentation recommends, check .env.example for new variables, and follow the upgrade guide for the target release. Your team owns the OAuth client registration, secret rotation, workspace credential decisions, log review and the upgrade test, while a DeployOpen retainer can cover scheduled re-packaging, daemon review, monitoring setup and upgrade testing if the scope is agreed in writing. Ask any partner to state which of these tasks are included, how often they recur and what the response time is for a failed token refresh.
How the plugin connects to the rest of your Dify platform
A tool plugin that calls an internal system on behalf of users touches several other parts of your Dify platform. Each connection below is a dependency you must plan, own and verify before the plugin reaches production users.
Identity provider for OAuth
The OAuth flow needs an authorization server that issues tokens for your internal system, with a registered client, redirect URI and scopes that match what the tool calls. Confirm which identity provider holds those clients, who can register them, and whether it supports the grant type your plugin will use. Your identity team should also confirm how refresh tokens are rotated and revoked when a user leaves the organization, because the plugin cannot enforce that on its own.
Dify Enterprise SSO
If your deployment uses Dify Enterprise, SSO governs who can sign in to the console and to web apps, which is separate from the OAuth consent a user gives your internal system. Confirm whether the same identity provider serves both flows, how user identifiers map between them, and whether a user signed in through SSO still needs to authorize the plugin separately. Community edition deployments do not have this layer, so the design differs.
Private plugin distribution
The packaged .difypkg file has to reach each Dify instance through a route you control, whether that is a Marketplace listing, a Git repository or a local file. Decide who builds and signs the package, how versions are numbered, and how a credential or OAuth client change is rolled out without breaking existing installations. Confirm this process with your release owner before the first build is shared.
Plugin installation policy
Your administrators decide which plugins a workspace may install, so a private OAuth tool can be blocked before anyone uses it. Confirm the policy that applies to your deployment, whether plugins are approved centrally, and whether the tool needs an approved version installed in every workspace. Community edition has a single workspace, which simplifies approval but leaves no central control across tenants.
Internal API gateway and target systems
The plugin sends requests to an internal API, often through a gateway that validates tokens, enforces rate limits and logs calls. Confirm the hostname and path the plugin will reach, whether the target is inside the SSRF proxy allowlist, and whether the gateway accepts the token audience your identity provider issues. Internal hosts are blocked by default in the SSRF proxy, so this path needs an explicit decision.
Per-workspace credential storage
OAuth client secrets and user tokens are stored by Dify and encrypted with keys tied to the instance, so they must be handled in each workspace rather than shared across them. Confirm where the encryption key is held, who can read stored credentials, and how a rotated SECRET_KEY would affect saved authorizations. Changing SECRET_KEY after deployment logs out all users, so plan that event with the platform owner.
How DeployOpen scopes and delivers an OAuth tool plugin
DeployOpen approaches a Dify tool plugin with OAuth as a fixed-scope piece of work: the internal system, the OAuth grant model, the workspace credential boundary and the packaging path are agreed in writing before code is written. The plugin is then built, tested against your identity provider and internal API, packaged as a .difypkg and handed over with the operating notes your team needs.
How we scope
- Inventory the internal API the tool will call, its endpoints, scopes and token lifetimes
- Confirm the OAuth grant type, redirect handling and which identity provider issues tokens
- Agree in writing which workspaces receive the plugin and how each stores its own credentials
How we build
- Implement the tool and OAuth credential schema, then test the authorization flow end to end
- Verify outbound calls reach the internal host through the SSRF proxy allowlist you approve
- Package the plugin as a .difypkg and check that it installs cleanly on a staging Dify instance
How we hand over
- Deliver source, build steps, version notes and the test cases used for the OAuth flow
- Document the token refresh behavior, revocation steps and the secrets your team must rotate
- Walk your platform and security staff through install, upgrade and workspace credential setup
How we support
- Support after handover is available as a retainer covering plugin updates and Dify version checks
- Retesting after each Dify minor release, which arrive roughly monthly, can be included in scope
- Changes to the internal API or identity provider are scoped as new written work
