Configure OAuth and API keys for tools

Learning objective

Configure OAuth 2.0 authorization for agent tools; decide when API keys are acceptable and enforce their storage, scoping, and rotation controls.

Core idea

For an architect connecting agent tools, the credential choice determines whose permissions the downstream service evaluates. Choose that authority before configuring the connection. A tool that retrieves an employee’s records needs user-specific authorization; a background integration might need a service identity. A shared API key cannot preserve individual user authority merely because a user initiated the agent request.

Microsoft Foundry toolboxes separate the identity calling the toolbox from the credential used by the toolbox to call a downstream tool. Project connections carry the downstream authentication configuration. See 4.1.4 for application-only access, user identity passthrough, and on-behalf-of exchange. This lesson focuses on configuring tool connections and governing the credentials they hold.

How it works

Configure managed OAuth on the connection

Foundry documents oauth2 as an authentication type for tools that require an OAuth authorization flow. Configure the remote-tool connection with azd ai connection create, --kind remote-tool, the tool’s --target URL, and --auth-type oauth2. Supply the provider’s --authorization-url, --token-url, --client-id, --client-secret, and requested --scopes. These values describe the provider integration; they are not instructions for the language model to acquire credentials.

Request only the scopes required by the exposed operations. Foundry’s example includes offline_access to enable automatic token refresh. Requesting that scope does not grant permission to unrelated data: downstream consent and authorization still govern access. Treat changes to scopes as permission changes that require review, rather than a configuration repair for every failed call.

Foundry generates a consent link when a particular user first needs to authorize the tool. After consent, Foundry stores and refreshes that user’s credentials and isolates them from other users. A revoked or expired refresh token can require authorization again. Your application must support that consent outcome instead of falling back to a shared credential and silently changing whose access is used.

Attach the configured connection to the tool in the toolbox. For MCP-backed tools, the documented MCPToolboxTool(project_connection_id=...) identifies the project connection. The connection’s authentication type and the user’s downstream permissions both matter; exposing a tool name alone does not authorize its execution.

Hosted agents also need caller context for per-user resolution. Foundry documents FoundryToolbox in Python and AddFoundryToolboxes in .NET with the hosting integration, which forwards the hosted request’s x-agent-foundry-call-id. Do not hard-code or reuse that call ID across user requests. It supplies request context, not a reusable downstream access token.

Select a credential type deliberately

Foundry documents several connection authentication types. Their differences determine whether the tool executes with shared, service, or user authority:

oauth2 and user-entra-token both support user access, but obtain credentials differently. Select the type the downstream service requires. For managed identity authentication to an OpenAPI service, configure the target service’s audience, not the Foundry project endpoint; see 4.1.3 for token audience enforcement.

Accept API keys only with compensating controls

An API key is acceptable when the target requires key authentication and the operation can legitimately run under shared integration authority. Prefer a supported identity-based option when user-specific authorization or per-agent permissions are required. The acceptance decision must include who owns the key, what operations it permits, and how compromise is contained.

For Foundry OpenAPI tools, store the key in a project connection. The OpenAPI specification needs components.securitySchemes, a matching security reference, and the correct key header name. The connection supplies the matching key name and value. Do not put the credential value in the specification, source code, prompts, or tool arguments. Foundry injects credentials from custom-keys connections without exposing the secret to the agent.

Scope access at the target service and restrict the operations exposed by the integration. A restricted OpenAPI operation list limits the agent interface; it does not reduce the permissions of a stolen key. If the provider cannot issue a suitably restricted credential, record that limitation in the integration’s approval decision. Separate unrelated environments and workloads rather than making one shared credential their common failure point.

Foundry’s OpenAPI documentation requires regular rotation and immediate rotation after suspected exposure. Update the project connection when credentials change and verify an authenticated tool call before revoking the previous credential, where the provider supports overlap. See 4.1.7 for versioning and staged rotation. A Key Vault update alone does not establish that a separately stored Foundry connection has changed.

Key distinctions and trade-offs

Stored bearer token versus OAuth connection: An OpenAPI Custom keys connection can store an Authorization header whose value starts with Bearer, including the space. That injects a supplied token. It does not configure the oauth2 consent and refresh lifecycle.

Scope versus exposure: OAuth scopes constrain granted permissions at the provider. The tool definition constrains the operations available through the agent interface. Use both; neither replaces downstream authorization.

Shared key versus user attribution: A key can simplify an integration but aggregates users under shared authority. User-specific consent and permission checks require a suitable user credential path.

Architecture / decision scenario

An employee assistant calls a partner records MCP service and an OpenAPI service for public product availability. The records service requires each employee’s consent and access permissions; the product service supports only a restricted API key.

Configure the records connection as oauth2 with the partner’s authorization and token endpoints and read-only scope. Include offline_access when automatic refresh is required. Reference its connection through MCPToolboxTool, and use the hosted toolbox integration to forward request caller context. If consent is missing, return the consent flow rather than invoking the tool with an administrator’s shared key.

For product availability, approve the shared-key integration because the required operation carries no employee-specific authority. Put the key in a project connection and declare its header through the OpenAPI security scheme. Keep the provider credential restricted to the required service operations. During rotation, update the connection, test the tool against the replacement credential, and revoke the previous credential after the approved overlap period. Neither credential enters the model context.

Common exam traps

• Selecting an API key for an operation that must honor each user’s permissions.
• Treating oauth2 and user-entra-token as interchangeable token acquisition mechanisms.
• Assuming a stored Bearer header enables automatic OAuth refresh.
• Adding a security scheme without the matching connection credential and security reference.
• Rotating a secret elsewhere without updating the project connection that injects it.

What to remember

Choose the downstream authority first, configure authentication on the project connection, and connect the tool to that configuration. Managed OAuth carries consent and token lifecycle; API keys require explicit approval, protected storage, target-side scoping, and verified rotation.

Knowledge check

References

• Microsoft, Toolbox authentication in Microsoft Foundry
• Microsoft, Connect agents to OpenAPI tools