Salesforce Meta-Tool: Identity Propagation

One sign-on. Seven tools. Your entire Salesforce org, with the user's own identity enforced end-to-end.

📖 Identity Propagation series — this repo is part of a series on end-to-end user identity propagation for AI agents: no service accounts in the data path, every action traceable to a real user. Read the story: From Theory to Production: Salesforce Meta-Tool & Identity Propagation. Companion repos: propagate-id-entra · snow-meta-tool

Architecture

draw.io source

The Problem

1. Full CRM Access Without Tool-Per-Object

An agent should be able to do everything the user can do in Salesforce (query any object, update any record, run any approval workflow) without the server having to define a tool for each one. Most MCP servers take the opposite approach: one tool per object, which means every new custom object requires a code change, the tool list grows linearly, and the security model has to be reimplemented from scratch. The goal is to give the agent the user's full CRM surface while inheriting the permissions and security that Salesforce already enforces.

2. The User's Own Permissions, Not a Service Account's

If the agent can do everything in Salesforce, it must operate under the user's own identity, with their sharing rules, field-level security, and approval workflows, not a service account that sees all data. Most integrations solve this by reinventing a permissions layer in the middleware. The simpler answer is to propagate the user's identity end-to-end and let Salesforce enforce the rules it already has, even when that identity crosses boundaries from Azure AD to Salesforce, possibly through federated IdPs.

This Project

A metadata-driven MCP server that solves both problems: seven tools that let an AI agent discover objects, learn field schemas, and construct SOQL queries at runtime (the meta-tool pattern), with true On-Behalf-Of identity propagation that enforces the user's own permissions end-to-end. The user authenticates once to Azure AD; the system handles the rest.

azd up   # deploys the full stack in ~15 minutes

How It Works

The user asks a question. The agent discovers objects, learns schemas, and queries Salesforce — all through the same seven tools, all with the user's own identity.

Excalidraw source

On-Behalf-Of (OBO) Token Exchange

APIM handles a three-phase exchange: validate the Azure AD JWT, resolve the Salesforce username, and acquire a per-user Salesforce token. The MCP server never sees Azure AD credentials.

Deep dive: Detailed OBO exchange animation | Full detail PNG | Excalidraw source

The 7 Tools: ~1,300 Tokens for All of Salesforce

Note: The 1,235 tokens cover tool definitions. Each describe_object call returns field schemas at runtime. Schemas are loaded on demand rather than pre-loaded into the system prompt.

Deep Dive

For detailed technical explanations, see docs/deepdive.md:

• The Meta-Tool Pattern — Why seven tools beat one-per-object, with token cost comparison
• Tool Reference — Per-tool descriptions with Unix analogies
• Identity Propagation: End-to-End — Architecture, hop-by-hop token trace, caching layers, key guarantees
• IdP Flexibility — How to swap Azure AD for Okta, PingFed, or another OIDC provider
• Current Scope and Limitations — Production considerations
• Diagram Sources — Mermaid sources for both sequence diagrams

Deployment and Setup

New to this project? Follow the step-by-step installation guide for a complete walkthrough from a clean Azure subscription and Salesforce org.

Prerequisites

Quick Deploy

If you already have a configured Salesforce org and certificate:

git clone https://github.com/ozgurkarahan/salesforce-meta-tool-identity-propagation.git
cd salesforce-meta-tool-identity-propagation
pip install -r requirements.txt

azd env new obo
azd env set SF_INSTANCE_URL "https://your-org.my.salesforce.com"
azd env set SF_CONNECTED_APP_CLIENT_ID "<connected-app-consumer-key>"
azd env set SF_SERVICE_ACCOUNT_USERNAME "<[email protected]>"

azd up

The postprovision hook automatically uploads certs/sf-jwt-bearer.pfx to Key Vault, creates the APIM certificate binding, and sets SF_JWT_BEARER_CERT_THUMBPRINT. No manual thumbprint step needed.

After azd up completes, open the Chat App URL printed at the end. Sign in with your Azure AD account and send a message (e.g., "Show me my Salesforce accounts").

From Scratch

1. Generate certificate — see installation guide Phase 1
2. Salesforce setup — see installation guide Phase 2
3. Set environment variables (3 vars — no thumbprint needed):

   azd env set SF_INSTANCE_URL "https://your-org.my.salesforce.com"
   azd env set SF_CONNECTED_APP_CLIENT_ID "<consumer-key>"
   azd env set SF_SERVICE_ACCOUNT_USERNAME "<[email protected]>"
   

4. Deploy: azd up
5. Map user identities — see installation guide Phase 4

Environment Variables

Project Structure

salesforce-meta-tool-identity-propagation/
+-- azure.yaml                    # azd project: 2 services (chat-app, salesforce-mcp)
+-- src/
|   +-- salesforce-mcp/
|   |   +-- app.py                # The MCP server: 7 tools, bearer passthrough
|   |   +-- salesforce_client.py  # Async Salesforce REST client with auth
|   +-- chat-app/
|       +-- app.py                # FastAPI backend, MSAL to Foundry agent bridge
|       +-- static/               # Vanilla JS SPA with MSAL.js
+-- infra/
|   +-- main.bicep                # Orchestrator, all Azure resources
|   +-- modules/                  # APIM, Key Vault, Container Apps, AI Services, ...
|   +-- policies/
|       +-- sf-mcp-obo-policy.xml     # OBO three-phase exchange policy
|       +-- sf-mcp-obo-prm-policy.xml # RFC 9728 PRM for OBO endpoint
+-- hooks/
|   +-- postprovision.py          # Cert upload + Entra app + Foundry agent + OBO connection
+-- scripts/
|   +-- sf_utils.py               # Shared SF/CLI primitives
|   +-- setup-sf-org.py           # Complete 5-step SF org setup orchestrator
|   +-- test-salesforce-mcp.py    # E2E MCP server test
+-- docs/                         # Architecture diagrams (Excalidraw)

Common Issues

Related Projects

• snow-meta-tool — The ServiceNow counterpart: same meta-tool pattern and OBO identity propagation, applied to ServiceNow ITSM. Deploy both side-by-side to power a Customer 360 AI Foundry agent that correlates Salesforce CRM data with ServiceNow incidents, changes, and requests under the user's own identity in each system.

Contributing

Contributions are welcome. Please open an issue or submit a pull request.

This project uses azd for deployment. See Deployment and Setup to get a local environment running.

License

MIT License

Related article: The Meta-Tool Pattern Applied to Enterprise on LinkedIn.