Edit

Call a custom API as a user with the Auth SDK sidecar

Use the OAuth On-Behalf-Of (OBO) flow when an upstream client calls an agent for a signed-in user and the agent calls a custom API for that user.

The agent first validates the inbound access token, then forwards the same authorization header to the sidecar. The sidecar uses its configured credential to get a downstream authorization header for that user.

Prerequisites

  • Completion of Authenticate users with the Auth SDK sidecar, including consent for the upstream client to call the agent.
  • A delegated scope exposed by the downstream API.
  • Consent for the agent to call that API for the user.

Configure access

  1. Expose a delegated scope on the custom API.
  2. Declare the scope in the blueprint's requiredResourceAccess.
  3. Obtain user or administrator consent for the agent identity to use that scope.
  4. Configure the API and scope in the sidecar.

Configure the sidecar

Add a delegated profile for the custom API:

{
  "DownstreamApis": {
    "custom-api": {
      "BaseUrl": "https://api.contoso.com/",
      "Scopes": [
        "api://<custom-api-client-id>/<delegated-scope>"
      ]
    }
  }
}

Use the shared client ID and keep identity overrides disabled as described in Configure the Auth SDK sidecar.

Get a downstream token

Forward the token issued for the agent API:

GET /AuthorizationHeader/custom-api
Authorization: ******

Send the returned authorizationHeader to the custom API. The custom API must validate the token and enforce the required scope and user authorization.

Don't send the inbound token directly to the custom API. It is intended for the agent, not the downstream resource. Don't return or log either authorization header.

Call the sidecar and custom API

The following example forwards the inbound user authorization header to the sidecar, reads the downstream authorization header, and calls the custom API:

import requests

SIDECAR_URL = "http://localhost:5000"

inbound_auth_header = "<authorization-header-from-agent-request>"

sidecar_response = requests.get(
    f"{SIDECAR_URL}/AuthorizationHeader/custom-api",
    headers={"Authorization": inbound_auth_header},
    timeout=5,
)

if sidecar_response.status_code in (401, 403):
    raise PermissionError("The sidecar rejected the user token or OBO request.")

sidecar_response.raise_for_status()
authorization_header = sidecar_response.json()["authorizationHeader"]

api_response = requests.get(
    "https://api.contoso.com/user-data",
    headers={"Authorization": authorization_header},
    timeout=10,
)
api_response.raise_for_status()
response_body = api_response.json()

Keep SIDECAR_URL on loopback in the shared network namespace. Replace the authorization-header placeholder with the complete Authorization header received by the agent. Process responseBody according to the custom API's response contract.

Treat the sidecar response as a credential. Don't log or return authorizationHeader.

Verify that the API enforces the delegated scope and the user's access. If OBO reports missing consent, check upstream access to the agent separately from downstream consent; the OBO exchange can't display a consent prompt.