Secure User-Delegated Tool Access

When an agent calls a remote tool, it needs credentials for that system. The tool might be a Model Context Protocol (MCP) server such as Jira, Stripe, or Cloudflare, an OpenAPI-described API, or a custom tool from a toolset. The simplest option is a single shared service account: every user's request authenticates as the same identity. Secure user-delegated tool access replaces that shared account with per-user credentials. Each user consents once through the remote system's own OAuth login, and from then on their tool calls run as them. Actions are attributable to a real person, access follows the permissions that person already has on the remote system, and revoking one user's access never disrupts anyone else's.

Delegated access builds directly on single sign-on: the logged-in identity established at login is the identity a delegated credential is bound to. If you have not enabled login yet, start with Enabling Single Sign-On (SSO). The cryptographic trust chain that lets an agent accept a delegated request safely is described in JWT Signing and Trust; this page is the operational guide to turning delegation on.

How Delegated Tool Access Works

The first time a user invokes a tool that needs delegated credentials, the agent has nothing stored for them, so it asks them to authorize. The user consents at the remote system's login page, the browser returns to the Entrypoint, and the agent stores a token scoped to that user. Every later call reuses the stored token until it expires.

Diagram: How Delegated Tool Access Works

The stored token is isolated per user and per agent, encrypted at rest, and reused on subsequent calls. When it expires or the remote system reports that the granted scopes are insufficient, the agent clears it and prompts the user to authorize again.

Before You Begin

Delegated access has three prerequisites:

  • Single sign-on is enabled. The delegated credential is bound to the authenticated user, so the Entrypoint must perform OpenID Connect (OIDC) login. See Enabling Single Sign-On (SSO).

  • A database-backed session store is configured. Per-user credentials persist in the session store. With the in-memory store, credentials are lost on restart and are not shared across replicas — use sql persistence in production (see Per-User Credential Storage and Time-to-Live).

  • The Trust Manager is enabled. Delegation is safe only when agents can verify that a request genuinely came from the Entrypoint. See Enable the Trust Manager.

On the remote system, register an OAuth 2.0 client (or confirm the server supports dynamic client registration) and record its authorization and token endpoints, client ID, and client secret. For Microsoft Entra ID, see Using Microsoft Entra ID. Add the Entrypoint's callback URL — https://<your-dns-name>/api/v1/auth/tool/callback — to the client's list of allowed redirect URIs.

Enabling Per-User OAuth for a Remote MCP Tool

Delegated access is configured per tool. For an MCP tool, you set it on the auth block of the tool entry in an agent's configuration. For OpenAPI tools, see OpenAPI Tools. For custom tools, see Enabling Delegated Access for Custom Tools. Set the authentication type to oauth2; the runtime handles the prompt, callback, token exchange, and storage.

There are two ways to supply the OAuth details.

Discovery Mode

If the MCP server publishes OAuth 2.0 metadata (RFC 8414 / RFC 9728) and supports dynamic client registration (RFC 7591), omit the scheme and credential blocks entirely. The runtime discovers the endpoints from the server URL and registers a client at runtime:

# agent config
tools:
  - tool_type: "mcp"
    connection_params:
      type: "streamable-http"
      url: "https://mcp.example.com/mcp"
    auth:
      type: "oauth2"
      display_name: "Example"

If the server requires a pre-registered client, supply one through the environment variables in the Environment Variable Reference rather than inline.

Explicit Mode

When the server does not support discovery, declare the endpoints and client credentials directly:

# agent config
tools:
  - tool_type: "mcp"
    connection_params:
      type: "streamable-http"
      url: "https://mcp.example.com/mcp"
    auth:
      type: "oauth2"
      display_name: "Example"
      scheme:
        authorization_url: "https://mcp.example.com/oauth/authorize"
        token_url: "https://mcp.example.com/oauth/token"
        scopes: ["read", "write"]
        token_endpoint_auth_method: "client_secret_post"
      credential:
        client_id: "${EXAMPLE_CLIENT_ID}"
        client_secret: "${EXAMPLE_CLIENT_SECRET}"

The auth block accepts these keys:

Key Required Purpose
type Yes Set to oauth2 for delegated access.
display_name No Name shown on the user's authorization prompt. Defaults to the server host.
scheme.authorization_url Explicit mode The remote system's authorization endpoint.
scheme.token_url Explicit mode The token endpoint.
scheme.refresh_url No Refresh endpoint. Defaults to token_url.
scheme.scopes No Scopes to request.
scheme.token_endpoint_auth_method No client_secret_post, client_secret_basic, or none.
scheme.audience No Non-standard audience parameter that some identity providers (for example, Auth0, Okta, or similar) require to issue a token the resource server accepts.
scheme.resource No RFC 8707 resource indicator, sent on the authorization, token, and refresh requests so the identity provider binds a matching aud claim. The runtime discovers this value from the MCP server's RFC 9728 protected-resource metadata; set it only to override the discovered value.
scheme.disable_pkce No Defaults to false. Leave Proof Key for Code Exchange (PKCE) on for MCP servers.
scheme.disable_consent_prompt No Defaults to false. When true, the runtime leaves prompt=consent off the authorization URL. Set it for Microsoft Entra ID; leave it unset for Google. See Using Microsoft Entra ID.
credential.client_id Explicit mode OAuth client ID.
credential.client_secret No OAuth client secret.
credential_key No Storage slot name. Defaults to a value derived from the MCP server so tools on the same server share one credential.
ca_cert_path No Certificate authority (CA) bundle for the runtime's calls to the OAuth endpoints.
insecure_skip_verify No Disables TLS verification for those calls. Development only.

An MCP server that requires authorization before listing its tools cannot be discovered live. For those servers, pre-declare the tool schemas with an inline manifest: list or an external manifest_file: on the tool entry. Servers that allow anonymous listing need neither.

Using Microsoft Entra ID

By default the runtime adds prompt=consent and access_type=offline to every tool authorization URL, because Google issues a refresh token again only when the user is forced through the consent screen. Microsoft Entra ID interprets prompt=consent as a request for the user's own consent, even when an administrator has already granted tenant-wide admin consent.

In a tenant that blocks user consent, which is common in enterprises, every user sees an "Approval required" screen and cannot sign in. To use the admin consent that is already in place, set disable_consent_prompt: true on the tool's scheme. The runtime then omits prompt=consent. Leave the setting unset for Google.

# agent config
tools:
  - tool_type: "mcp"
    connection_params:
      type: "streamable-http"
      url: "https://mcp.example.com/mcp"
    auth:
      type: "oauth2"
      display_name: "Power BI"
      scheme:
        authorization_url: "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize"
        token_url: "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token"
        scopes:
          - "https://analysis.windows.net/powerbi/api/Dataset.Read.All"
          - "offline_access"
        disable_consent_prompt: true
      credential:
        client_id: "${ENTRA_CLIENT_ID}"
        client_secret: "${ENTRA_CLIENT_SECRET}"

Consider the following Entra-specific details:

  • Include offline_access in scopes. On Entra, a refresh token is issued when you request the offline_access scope, not because of prompt=consent. Without it, users must sign in again each time their access token expires.

  • Set credential.client_secret. An Entra application registration with a Web redirect URI is a confidential client, and without a secret the token request fails with error AADSTS7000218.

  • Register the callback URL as a Web redirect URI. In the application registration, add https://<your-dns-name>/api/v1/auth/tool/callback under the Web platform, not the single-page application platform.

  • Grant tenant-wide admin consent for the delegated permissions in the Entra admin center before users sign in.

OpenAPI tools accept the same setting as a flat auth.disable_consent_prompt: true key. For more information, see OpenAPI Tools. Custom tools are covered in the next section.

Enabling Delegated Access for Custom Tools

A custom tool that you upload as part of a toolset can also act as the signed-in user. The work is split between the tool author and the person who deploys the toolset.

  • The tool author declares the protocol shape. In Go, the tool passes WithAuth an AuthSchemaConfig that names the auth type, the authorization URL, the token URL, the scopes, and the token endpoint authentication method. In Python, the tool class returns the equivalent dictionary from its auth_config property. For the declaration syntax, see Tool Options.

  • The deployer supplies the client identity. Each deployment registers its own OAuth client. The deployer provides its details in the toolset's reserved auth key, under spec.config.

# toolset configuration
kind: toolset
name: powerbi_query
spec:
  config:
    auth:
      credential:
        client_id: "${POWERBI_OAUTH_CLIENT_ID}"
        client_secret: "${POWERBI_OAUTH_CLIENT_SECRET}"
      scheme:
        disable_consent_prompt: true

The toolset's auth key accepts the fields in the following table.

Key Purpose
type The auth type: oauth2, basic, or bearer. It overrides the type the tool declared.
credential.client_id The OAuth client ID for this deployment.
credential.client_secret The client secret for confidential clients such as Microsoft Entra ID and Atlassian three-legged OAuth. The runtime sends it on the authorization code exchange and on every token refresh.
credential.username, credential.password, credential.token The static credentials for the basic and bearer types.
scheme.audience, scheme.resource, scheme.refresh_url, scheme.token_endpoint_auth_method The same meaning as in Explicit Mode.
scheme.disable_pkce, scheme.disable_consent_prompt Boolean values that change the authorization flow.

Secret values read back as <REDACTED>. Each user's own access and refresh tokens never appear in this configuration; the runtime keeps them in the per-user credential store.

The authorization URL, token URL, and scopes always come from the tool's declaration. If you try to override them in scheme, sam config apply rejects the change with HTTP 400, so the deployment cannot diverge from the tool's declared authorization settings.

When the tool runs, it reads the signed-in user's token and calls the remote API with it. If no token is available, the tool returns an authentication-required error, and the runtime starts the authorization prompt described in How Delegated Tool Access Works.

Rotating a Client Secret

To rotate auth.credential.client_secret, change the value of the environment variable the ${...} reference reads, then run sam config apply. The plan detects that the stored secret no longer matches and pushes a configuration-only update, even though the redacted value never appears in the plan diff.

The plan checks for a changed secret only on toolsets that have no other planned change. If the same sam config apply also uploads a new toolset bundle or changes the toolset's metadata, run sam config apply a second time to push the new secret.

Enable the Trust Manager

The Trust Manager is what makes delegation safe: each component publishes a signed trust card, and agents verify that an incoming task was signed by a legitimate Entrypoint before acting on the user's behalf. It is a deployment-wide capability, off by default. Enable it in the trust_manager block of every component's configuration:

# component runtime config
trust_manager:
  enabled: ${TRUST_MANAGER_ENABLED, false}
  verification_mode: "strict"
  card_publish_interval_seconds: 10
  card_expiration_days: 7

Set the TRUST_MANAGER_ENABLED environment variable to true so the interpolated enabled value resolves on every component — the Entrypoint and every agent. With the Trust Manager enabled, agents reject any task whose signature does not verify against a known trust card.

Trust cards are exchanged over a dedicated event broker topic, and the event broker's access control lists (ACLs) are load-bearing: a component's identity on the trust topic must match its event broker client username, which is what stops a compromised peer from publishing a forged card. Provision those ACLs when you deploy — see JWT Signing and Trust for the trust chain and topic conventions. This page does not restate them.

Per-User Credential Storage and Time-to-Live

Delegated credentials are stored in the session store, one slot per user per agent. The value is encrypted at rest with a key derived from the agent's identity, so credentials cannot be read from the database directly.

Persistence follows the session store's type. Configure a database-backed store so credentials survive restarts and are shared across replicas:

# agent config
session_service:
  type: "sql"
  database_url: "${AGENT_DATABASE_URL}"

With type: memory, credentials live only in the process and are lost on restart — acceptable for local testing, not for production.

Each stored credential carries a time-to-live (TTL) of 30 days, after which the agent treats it as absent and prompts the user to authorize again. The lifetime is fixed by the runtime and is not configured through an environment variable. When a user's access is revoked or a re-authorization replaces an existing credential, the old value is marked expired and no longer used.

A credential is refreshed when it is next used, not on a background schedule. A credential that Solace Agent Mesh holds can therefore still fail on first use, because the remote system rejects it before anything has cause to renew it. Plan for that on unattended work in particular: a stored credential being present is not the same as the remote system still honoring it.

The OAuth Callback and Redirect

The remote system returns the user to a fixed path on the Entrypoint: /api/v1/auth/tool/callback. This endpoint is intentionally unauthenticated — the browser arrives carrying only the authorization code and an opaque state value. The Entrypoint consumes the matching pending state and relays the code to the owning agent, which verifies the state before exchanging the code. Because the callback resolves its pending state against the shared gateway store, a login started against one Entrypoint replica can complete on another.

The full redirect URL is resolved in this order:

  1. OAUTH_TOOL_REDIRECT_URI, if set — used verbatim.

  2. Otherwise FRONTEND_REDIRECT_URI with /api/v1/auth/tool/callback appended.

  3. Otherwise a development default of http://127.0.0.1:8800/api/v1/auth/tool/callback.

The development default uses the loopback IP 127.0.0.1 rather than localhost intentionally. Browsers can silently upgrade http://localhost to https:// through HTTP Strict Transport Security (HSTS) or an HTTPS-only mode, which breaks the plain-HTTP callback. A loopback IP is never upgraded.

In production, set one of the first two to your externally reachable HTTPS host. Real identity providers reject the loopback default. Whatever value resolves must exactly match a redirect URI registered on the OAuth client.

If you previously registered http://localhost:8800/api/v1/auth/tool/callback on a manually configured OAuth client, re-register it as http://127.0.0.1:8800/api/v1/auth/tool/callback to match the new default, or set OAUTH_TOOL_REDIRECT_URI to the value you registered. Clients created through Dynamic Client Registration re-register automatically and need no change.

Environment Variable Reference

The runtime reads these variables.

Variable Purpose
TRUST_MANAGER_ENABLED Resolves the trust_manager.enabled value. Set to true on every component.
TOOL_OAUTH_CLIENT_ID Static OAuth client ID used when the server does not support dynamic client registration.
TOOL_OAUTH_CLIENT_SECRET Static OAuth client secret paired with the client ID.
TOOL_OAUTH_INITIAL_ACCESS_TOKEN Initial access token presented during dynamic client registration, when the server requires one.
OAUTH_TOOL_REDIRECT_URI Explicit callback URL for delegated tool flows. Highest precedence.
FRONTEND_REDIRECT_URI Fallback base for the callback URL when OAUTH_TOOL_REDIRECT_URI is unset.
MCP_CLIENT_ID Legacy alias for TOOL_OAUTH_CLIENT_ID. Prefer the TOOL_OAUTH_ name.
MCP_CLIENT_SECRET Legacy alias for TOOL_OAUTH_CLIENT_SECRET. Prefer the TOOL_OAUTH_ name.

Verify

Start the deployment with the Trust Manager enabled and confirm the components exchange trust cards — each agent logs that it received the Entrypoint's trust card at startup. Then sign in and invoke a delegated tool:

  1. The first call surfaces an authorization prompt naming the remote system (the display_name).

  2. Completing the login redirects the browser back and the tool call resumes automatically.

  3. A second call from the same user runs without a prompt — the stored credential is reused.

  4. Signing in as a different user prompts again, confirming credentials are isolated per user.

Troubleshooting

Symptom Cause Fix
Authorization prompt never appears; the tool call fails outright The MCP tool's auth.type is not oauth2, or no client ID is available and the server does not support dynamic registration Set auth.type: oauth2; supply TOOL_OAUTH_CLIENT_ID / TOOL_OAUTH_CLIENT_SECRET if discovery is unavailable
Login completes but the browser shows a redirect-mismatch error The resolved redirect URL is not registered on the OAuth client Register the exact /api/v1/auth/tool/callback URL, or set OAUTH_TOOL_REDIRECT_URI to a registered value
Redirect lands on http://localhost:8800 in a deployed environment Neither OAUTH_TOOL_REDIRECT_URI nor FRONTEND_REDIRECT_URI is set, so the development default applies Set one of them to your externally reachable HTTPS host
Credentials are lost after every restart The session store is type: memory Switch to type: sql with a database_url
Users are prompted to authorize on every call No session_service block is configured, so credentials are never stored Add a session_service block; use type: sql in production
Agent rejects the task before the tool runs The Trust Manager is enabled on some components but not others, so signature verification fails Set TRUST_MANAGER_ENABLED=true on the Entrypoint and every agent
Entra sign-in shows "Approval required" even though an administrator granted consent The runtime sent prompt=consent, which Entra treats as a request for the user's own consent, and the tenant blocks user consent Set disable_consent_prompt: true in the tool's scheme (or auth.disable_consent_prompt: true for an OpenAPI tool)
Token exchange fails with AADSTS7000218 The Microsoft Entra application registration is a confidential client (it has a Web redirect URI), and no client secret was sent Set credential.client_secret on the tool's auth block
A private-CA OAuth endpoint cannot be reached, and it is a connector created in the UI The connector-generated configuration cannot yet emit ca_cert_path / insecure_skip_verify Configure the tool in agent YAML directly and set ca_cert_path on the auth block

What Next?

You have enabled per-user delegated access to remote tools. Most operators next add more remote systems — see MCP Connectors for the transports and authentication types agents support. To author custom tools, see Configuring Tools. To pin a private-CA certificate for the runtime's outbound calls, see Configuring TLS.