Dify MCP user identity forwarding: why tools should act as the person
When a Dify agent calls an MCP tool that reads or changes a business system, the central question is which identity that call carries. By default, many setups connect the tool with one service credential shared by everyone who uses the app, so the downstream system records every action against that account. Identity forwarding means passing the signed-in user's identity provider token along with the tool call, so the MCP server can authorize the request against that person's own permissions and write an audit entry under their name. The idea is simple. The execution path is where the work lies, and the supplied Dify sources do not document it in enough detail to rely on it without testing.
The Dify materials available to us confirm the building blocks around this problem but not the forwarding behavior itself. The Dify Enterprise SSO documentation lists OpenID Connect, SAML and OAuth2 and separate SSO scopes for workspace access and web app access, which establishes who signs in to Dify. The environment reference says SECRET_KEY signs session cookies and JWTs, and the 1.16.1 release notes describe token-based API authentication between services and agent sandbox network isolation through a Squid proxy. None of these sources states that a user's upstream IdP token is handed to an MCP server during a tool call. Ask the vendor directly whether the MCP tool configuration can pass an end-user token, which header or field carries it, how token refresh and expiry are handled, and whether it applies to published web apps as well as the builder's test chat.
A regulated team needs this when an agent's tools can change records, release payments, or expose customer data, and when the downstream system's audit trail must name the person who triggered the action. Regulators and internal auditors will ask who authorized each change, and a shared service account gives a weak answer. If the vendor confirms forwarding, plan to test that a user without rights in the target system is refused, that the audit log shows the person and not the service account, and that the token is not written to Dify logs. If forwarding is not available, the fallback is a per-user credential broker or narrower service accounts, with the trade-off documented before the build starts.
Which identity pattern fits each MCP server
This table compares three ways a Dify MCP tool call can carry identity: a workspace service credential, the signed-in user's token forwarded to the server, and a token exchange or gateway in front of the server. Read each column for who the tool sees, what the audit trail can prove, what the server must check and how the pattern usually fails. The main takeaway is that per-user forwarding only protects anything when each MCP server validates the token itself.
| Question | Workspace service credential | Per-user token forwarding | Token exchange or gateway layer |
|---|---|---|---|
| Who the tool sees | One workspace service account, so every caller looks identical | The signed-in employee, identified by the identity provider token | A gateway-issued token scoped to the user and the requested tool |
| What the audit log can prove | Workspace activity only, with no named employee behind each call | Which user triggered the call, if the MCP server logs the token subject | User, app and gateway decision for each call, if all three are logged |
| What the MCP server must validate | That the workspace credential is valid and the tool is allowed for it | Signature, issuer, audience, expiry and scopes on every call | Gateway audience and scopes, plus the original user subject carried in the exchanged token |
| Main failure mode | One over-scoped credential shared by every app and user in the workspace | Tokens reach logs or a server outside the intended audience | Gateway outage blocks all tools, or loose claim mapping widens scopes |
| Dify behavior to confirm | Where the credential is stored and who can edit it in your target version | Whether your target version passes the end-user token into tool calls for your app type | Whether Dify can call the gateway with the user's token in your target version |
| Best fit | Read-only tools with one shared data scope and low per-user risk | Tools that enforce each user's own permissions in a system of record | Several MCP servers or regulated tools that need central policy and one audit trail |
Risks to design for before forwarding tokens
Forwarding a signed-in user's token to an MCP server moves identity risk into prompts, logs, network paths and secret handling. The cards below are parallel risks, and each names the Dify control the supplied facts describe and what that control does not cover.
Token leakage into prompts and logs
A user token placed in a workflow variable, prompt template or node output can reach model providers, run logs and exported data. Dify's workflow and logging features record what flows through them, so a token passed as an ordinary variable may persist. Check every node that touches the token, restrict who can view run logs, and confirm which fields are retained. Dify's DSL export excludes third-party API keys, but that exclusion does not cover tokens you place in prompts or variables yourself.
Over-broad scopes reused across users
If the identity provider issues one broad scope and the workflow reuses it for every caller, one user's access becomes everyone's access. Per-user forwarding only helps when the scope requested matches the tool being called. Ask your identity team to define narrow scopes per MCP server and confirm that the token exchange, not a cached workspace credential, produces the token each run uses. Dify does not decide scopes for you.
Tokens reaching servers that should not receive them
A workflow can call any MCP server configured in the workspace, so a token meant for one tool may be sent to another. Map each token audience to the single MCP server allowed to receive it, and block forwarding to unlisted endpoints. Confirm how your Dify version selects the target server for a given tool call, because this control is a configuration decision rather than a platform default.
Outbound requests reaching internal addresses
An MCP server URL, or a redirect it returns, can point at internal or private addresses where token-bearing requests would land. Dify's SSRF_PROXY settings route outbound requests through a proxy that blocks internal and private IP ranges, which limits this path. The proxy does not validate token audience and does not cover traffic that bypasses it, so verify that MCP calls use the proxy and that egress rules at the network layer also block private ranges.
Sandbox network isolation scope
Agent code runs in a sandbox, and Dify 1.16.1 added network isolation for that sandbox through a Squid proxy. This limits what sandboxed code can reach, but it governs the sandbox only. Tokens handled by a workflow node outside the sandbox follow different paths. Confirm which execution paths your agents use, test whether sandboxed code can read forwarded credentials, and review the release notes for your target version before relying on the isolation.
Secret rotation and SECRET_KEY changes
SECRET_KEY signs session cookies and JWTs and encrypts OAuth credentials. Per the environment reference, changing it after deployment logs out all users, so rotation is a planned event with user impact. Plan how stored OAuth credentials for MCP sign-in are re-entered after a change, and separately plan token lifetime and refresh at the identity provider. SECRET_KEY governs Dify's own sessions, not the lifetime of tokens issued to downstream MCP servers.
Trust placed in the MCP server
Dify forwards the token, but the MCP server must check the token's audience, issuer and expiry before acting on it. A server that accepts any valid token from the identity provider will authorize requests meant for other services. Ask each MCP server owner to document which audience they accept, how they reject expired or mismatched tokens, and how they log the user identity they act for. Dify's token-based service API authentication protects Dify's internal calls and does not validate tokens on MCP servers.
How to set up per-user identity forwarding
This sequence sends each signed-in user's identity provider token from Dify to the MCP server, so every tool call is authorized and logged against that person. It is complete when two test users get different results from the same tool and a revoked session stops working.
Confirm the Dify version and MCP behavior
The platform team records the installed Dify version and reads the documentation for that version to confirm how the MCP client authenticates to remote servers. Check the 1.16.1 release notes for the security changes that affect service authentication, then confirm whether your version can forward a per-user access token, which header or field it uses, and whether it supports only static credentials. If per-user tokens are not supported, stop here and decide between an upgrade or a gateway that performs the exchange. Done when a written note records the version, the documented behavior and the header name to use in later steps.
Register the MCP server audience and scopes
The identity administrator registers the MCP server as a protected resource in your identity provider, sets its audience identifier and defines scopes for each group of tools. Assign those scopes to the groups that should use each tool. Confirm the exact registration steps in your provider's documentation, since the terms and screens vary by product. Check: sign in as a test user in the permitted group and inspect the issued access token to confirm the audience and scopes are present. Then repeat with a test user outside the group and confirm the expected scopes are missing.
Validate tokens and record the user subject
The MCP server team configures the server to verify each incoming token against the identity provider's published signing keys. It checks the issuer, audience, expiry and required scopes, rejects any request that fails one of these checks, and writes the token's subject claim and client identifier to its audit log for every tool call. Check three requests: a call with no token must fail, a call with a token for a different audience must fail, and a call with a valid token must succeed and produce a log entry that names the user.
Configure Dify to pass the user token
The Dify administrator configures the MCP connection so the signed-in user's access token is sent in the header agreed in step one. Keep any static workspace credential out of the request path for these tools. Confirm with the vendor documentation how long Dify retains tokens and whether they appear in logs, and restrict log access accordingly. Check: capture one request at a proxy or at the MCP server and confirm it carries the user's token and not the workspace credential.
Test with two users
Two test users sign in to the same published app, each with a different group membership, and run a workflow that calls the same MCP tool with the same inputs. The user with the scope should receive the result, and the user without it should receive an authorization error from the MCP server, not a result from a shared account. Check the MCP audit log for two entries with different subject values, each tied to the correct tool call. If both users get the same outcome, the token is not being forwarded or the server is not enforcing scopes, so return to step four.
Test a revoked session
The tester ends one user's session or revokes that user's sessions in the identity provider, then runs the workflow again. Calls should fail once Dify can no longer obtain a valid token. Access tokens that were already issued may remain valid until they expire, so review the token lifetime in your identity provider and record the window in which a revoked user could still call a tool. Check: the post-revocation call is denied at the MCP server, and the test record states the token lifetime and the accepted residual window for your deployment.
Setup differences for MCP servers you own and third-party servers
When your organization runs the MCP server inside its own network, your team controls token validation, tool authorization and log retention. The server can check the forwarded identity token against your identity provider's signing keys, apply per-user rules to each tool, and write audit events that name the signed-in user. The trade-off is that every check is code your team owns, builds and tests.
- Token validation: Verify the signature, issuer, expiry and audience on every request. Reject tokens whose audience names another service, and do not pass them on.
- Tool-level authorization: Map each tool to the scopes or groups it requires, and deny by default when a claim is missing.
- Audit records: Log the subject, tool name, a request identifier, the decision and argument metadata, then ship the events to your central log store.
- Downstream calls: Confirm that any service the MCP server calls uses the user's delegated access, not a shared service account, and test that a revoked user loses access.
Before go-live, confirm that your test suite covers expired tokens, wrong audiences and missing scopes, and check whether your JWT library validates audience by default.
With a vendor-hosted MCP server, you cannot read its validation code or inspect its logs. Whether it accepts your identity provider's tokens, which scopes it honors, which audience value it expects and whether it records per-user audit entries are all vendor decisions. Your part is to request those answers in writing and test the behavior your controls depend on.
- Accepted token types: Ask whether the server accepts OAuth 2.0 access tokens from your identity provider, and which audience value it requires.
- Scope model: Request the list of scopes, what each one permits, and whether a scope grants access to the signed-in user's data or to the whole organization's.
- Audit log access: Ask whether per-user events are recorded, how long they are kept, whether you can export them to your security monitoring tools, and who at the vendor can view tool arguments.
- Token handling: Confirm whether the vendor stores forwarded tokens, whether it passes them to other services it calls, and how it handles revocation.
You cannot verify internal validation logic, vendor-side log retention or breach handling from outside the service. Get those answers from the vendor's security documentation and contract terms, then confirm them with a revoked test user.
Whichever kind of server you use, the Dify side determines which identity reaches the tool call. Confirm in your Dify version how the signed-in user's identity is passed to MCP tools, and whether the identity differs between workspace members, published web app users and service API calls. Dify's own documentation and release notes are the place to confirm these behaviors for your version.
- Identity source: Determine which request types carry a user identity at all, since a call made with a service API key may not represent any end user.
- Token storage: Confirm where forwarded tokens are held. The environment reference says SECRET_KEY encrypts OAuth credentials, so check whether that also covers tokens forwarded to tools.
- Token lifetime: Confirm what happens when a token expires during a long-running workflow, and whether the call fails cleanly or retries with stale credentials.
- Outbound network path: The SSRF_PROXY settings block internal and private IP ranges by default, so confirm that your internal MCP server hostname is reachable through the proxy configuration.
- Regression after upgrades: Retest identity forwarding after each Dify minor release, since the 1.16.1 release notes describe sandbox network isolation changes that can affect outbound calls.
After any change, test with two users and one revoked user, and record the token claims each tool actually receives.
Limits to confirm in your environment
MCP identity forwarding depends on details that differ by release, edition and identity provider, and the supplied facts do not settle them. The cards below list what to confirm against the target Dify version and your own identity setup before you commit to a design.
Whether the release forwards user tokens
Confirm that the Dify version you plan to run passes the signed-in user's identity provider token to MCP tools at all. Many setups only send a workspace or app-level credential, and the supplied release facts do not describe this behavior. Ask for the feature in writing for your exact version, then test it with two named users calling the same tool and check which identity reaches the MCP server logs.
Token expiry during long agent runs
An agent workflow can run longer than a single access token lifetime, so a token captured at the start may expire mid-run. Confirm whether Dify refreshes the token, re-requests it, or fails the tool call, and what the MCP server returns in each case. Also confirm how SECRET_KEY rotation or a session reset affects tokens already held by queued workers.
Identity providers the MCP server accepts
Dify's Enterprise SSO documentation names OpenID Connect, SAML and OAuth2 with providers such as Microsoft Entra ID, Okta and GitHub, but that does not mean every MCP server will validate tokens from each one. Check that your MCP server verifies the issuer, audience and signature for the provider you use, and that the token type Dify forwards is one the server accepts. SAML assertions are not bearer tokens for most MCP servers.
Per-user permissions at the tool level
Forwarding a user token only helps if each MCP tool checks it against its own permission model. Confirm that your tool servers map identity claims or groups to allowed actions, and that a denied call returns a clear error to the agent rather than silently falling back to a shared service account. Test a read-only user and an admin user against the same tool before rollout.
Community and Enterprise SSO differences
Enterprise SSO is a paid feature of the self-hosted Enterprise edition, while the Community edition is free and limited to a single workspace. Confirm which sign-in methods your edition supports before designing per-user forwarding, because a Community instance may only offer local accounts or OAuth buttons. Ask the vendor which identity source the forwarded token comes from in each edition.
Behavior changes across monthly upgrades
Minor Dify releases arrive roughly monthly, so identity forwarding can change between versions. Read the release notes for each step, test token flow in staging after every upgrade, and check .env.example for new variables that affect authentication or service-to-service calls. Keep a rollback plan that includes a database backup taken before the upgrade.
How token lifetime and refresh affect agent runs
The core design question is what an agent run does when the user's access token expires partway through. A workflow or agent can keep running for longer than a short-lived access token stays valid, so the design has to choose one of three behaviors before go-live: stop the run when the token expires, reuse the token until it expires and then fail the tool call, or request a new token through a refresh grant and continue under the same user. Each choice changes the audit trail. Stopping keeps every call tied to a token issued for a known sign-in. Reusing lets a run finish, but calls made after the token's nominal lifetime may be hard to explain. Refreshing keeps the run alive, yet every refreshed token is another point where the identity provider decides whether the user still has access, so the audit log should record the token's issue time and the session it came from.
Accountability after sign-out needs its own decision. If a user signs out or is deprovisioned while a long agent run is still calling MCP tools, the organization must decide whether those calls are still made on the user's behalf. The safer position is that revocation ends the run's ability to call user-scoped tools, and that calls after revocation are rejected by the MCP server rather than merely logged. Whether this is possible depends on the identity provider and the MCP server. Confirm with your identity provider whether it supports refresh token rotation, how long refresh tokens live, and whether it can revoke a session immediately. Confirm with each MCP server whether it validates token expiry on every call or caches token validation, and whether it can check revocation status at all. Some servers accept a self-contained token until it expires, which means a revoked user can keep acting for the remaining lifetime.
Test revocation as a scripted scenario before relying on it. Start a long-running agent run as a test user, sign that user out or disable the account, then confirm that the next tool call fails at the MCP server and that the audit log shows the rejection with the correct user identity. Repeat the test for token expiry without refresh and for refresh after a session has ended. Keep the results with your design record, because an auditor will ask how the organization knows a departed user cannot keep acting through an agent. The same test should be rerun after any change to the identity provider's session settings, the MCP server version or the Dify version that sends the token.
What do buyers ask about per-user MCP identity?
How much does per-user MCP identity forwarding cost to build?
The cost follows from the written scope, and DeployOpen does not publish a price list. The work is paid for in discovery of each MCP server and its current authentication, Dify configuration, identity provider integration, token validation changes on the server side, audit logging design, testing and handover. Most of this is one-time, while upgrade support and continuous testing recur if you buy a retainer. The main cost drivers are the number of MCP servers, the identity provider in use and how strict the audit requirements are. Dify's own licensing is separate: the Community edition is free and limited to a single workspace, and the Enterprise edition is custom priced according to the Dify pricing page. Ask for a quote that lists each server, the token path for each, the audit destination, the test plan and which items recur.
What sets the timeline for a scoped MCP identity build?
The timeline is set in the written scope before work starts, so the number of MCP servers and their readiness decide most of it. A server that already validates bearer tokens and checks audience claims needs less work than one that uses a shared service account. Other factors include how quickly your identity provider administrators can register the applications and approve scopes, whether the audit sink already exists, and how many test users and group combinations you need to cover. Confirm early whether the Dify version you run supports the token path you intend to use, because that can change the sequence. Ask the partner to show the phases, the dependencies on your teams and the points where your sign-off is required.
What must our organization provide for the build?
Four inputs decide whether the build moves on schedule. First, identity provider administrator access to create or review the application registrations, scopes and token settings used for the MCP path. Second, named owners for each MCP server who can approve changes to how the server validates tokens and logs calls. Third, test users with the group memberships your access model relies on, including at least one user who should be denied. Fourth, a Dify environment, a destination for audit logs and a security reviewer who signs off on the design. Without these, the work stalls at the points where a decision is needed, so agree on who fills each role before the scope is signed.
Can our internal team build per-user MCP identity without a partner?
An internal team can build it if it already runs the identity provider, owns the MCP servers and has engineers who can work with OAuth2 and OpenID Connect tokens. The difficult parts are rarely the Dify settings. They include checking token audience and expiry on every MCP server, deciding how refresh and revocation behave, keeping tokens out of logs, and proving that each tool call is recorded against the right user. Outbound calls from Dify also pass through the SSRF proxy, which blocks internal and private IP ranges, so MCP servers on private networks need a deliberate allow path. Write down the design, run the same tests on each Dify upgrade and compare the result with your own checklist before opening the feature to users.
What changes at each Dify upgrade for MCP identity?
Each upgrade can change behavior that the identity path depends on, so the token test should run again every time. Dify minor releases arrive roughly monthly: 1.16.0 on July 17, 2026, 1.17.0 on August 25, 2026 and 1.17.1 on September 10, 2026, according to the GitHub releases page. Follow the upgrade guide for the target version, take a backup before every upgrade and check .env.example for new variables. After the upgrade, repeat the user-to-server test, confirm the audit records still carry the user identity and check that the security settings from the 1.16.1 changes, including the agent sandbox proxy and sandboxed template rendering, still behave as intended. Recurring upgrade support can be covered by a retainer.
How do auditors check that each MCP tool call is tied to a user?
Auditors look for evidence that a tool call can be traced to the signed-in user, the MCP server, the tool and the time. DeployOpen prepares that evidence, including the configuration record, the token settings, the audit log samples and the test results, but independent auditors and certification bodies issue any assessment outcome. Ask your auditor which of your controls cover AI tool access and what sample of logs they expect to see. Confirm how long your audit logs are retained, who can read them and whether they hold tool inputs that contain personal data. Those answers determine what must be logged and where it goes, so settle them before the logging design is fixed.
Does Dify forward the signed-in user's identity token to MCP servers?
Confirm this for the exact Dify version you run, because the supplied documentation does not settle it. Check the Dify release notes and docs for a supported way to pass the user's identity provider token to a tool call, and test it with a real user and a real MCP server. If the built-in path does not carry the token, the design may need a gateway or a small service that performs the token exchange, and that adds an owner, a deployment and a security review. Whichever path you choose, verify that tokens are not stored in plain text in Dify logs, that the SECRET_KEY used for encryption is protected, and that outbound calls to the MCP server are allowed by the SSRF proxy settings.
How do we ask for a fixed-scope quote for this work?
Most DeployOpen engagements are fixed-scope, with the scope, deliverables and timelines agreed in writing before work starts. Send an inventory of your MCP servers with the auth method each one uses, the identity provider and version, the Dify version and deployment type, the audit destination and the retention rule, and the number of test users and groups. Ask for the deliverables to be listed one by one, with acceptance criteria for the user-to-server test and the audit records. Ask which items are one-time and which are recurring, and whether upgrade support or continuous testing should be a retainer. A written scope gives you a quote you can compare with your internal estimate.
How DeployOpen scopes and supports MCP identity work
DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside your own infrastructure, including Dify. For MCP identity forwarding, we start from a written scope that defines which identity provider tokens reach which MCP servers, then build and verify the path before handing it over with runbooks.
How we scope
- Inventory every MCP server and tool that would receive a user's identity provider token, and record what each one needs to authorize.
- Agree in writing which Dify apps, workspaces and user groups are in the forwarding path and which must keep a service credential.
- Define the audit fields each MCP server must log so per-user actions can be traced back to a signed-in person.
How we build
- Configure the identity provider client, token audience and scopes for the Dify app and each MCP server, then test token exchange in a staging instance.
- Protect secrets with SECRET_KEY handling, outbound SSRF_PROXY filtering and network isolation for the agent sandbox before tokens leave the platform.
- Test denied-access cases for expired, revoked and out-of-scope tokens so failures stop the tool call rather than falling back to a shared credential.
How we hand over
- Deliver a written design, configuration records, test results and a list of identity claims each MCP server relies on.
- Document the upgrade steps for Dify and MCP server changes, including checks against the .env.example file after each version change.
- Walk your security, identity and platform teams through the audit trail so they can review per-user tool activity independently.
How we support
- Support is available as a retainer for monitoring identity changes, rotating credentials and testing forwarding after Dify minor releases.
- Re-run access tests when identity provider policies, MCP server versions or Dify workspace roles change, under the agreed scope.
- Confirm with your identity provider and each MCP server vendor which token formats, audience values and claims they support before build starts.
