Edit

Access Microsoft 365 as an agent's user account with the Auth SDK sidecar

Some Microsoft 365 scenarios require a user object rather than an application identity. Use an agent's user account when an autonomous agent needs capabilities such as:

  • Membership in a Microsoft Teams team.
  • An Exchange Online mailbox.
  • Direct access to shared SharePoint or OneDrive content.
  • A Microsoft 365 license assigned to the agent.

Don't use an agent's user account when the service supports the required application permission. App-only access is easier to govern and doesn't consume a user license.

Configure the account

  1. Create an agent's user account and associate it with the Agent ID.
  2. Assign only the licenses and service access required by the scenario.
  3. Grant the Agent ID the delegated permissions required by the Microsoft 365 workload, such as Mail.ReadWrite or Files.ReadWrite.
  4. Configure the Microsoft 365 API in the sidecar.
  5. Record the Agent ID and the agent user's object ID or user principal name.

Configure the sidecar

Enable agent overrides for the unauthenticated authorization-header endpoint. Configure the Microsoft Graph delegated scopes required by the agent:

{
  "Sidecar": {
    "AllowOverrides": {
      "GetAuthorizationHeaderUnauthenticated": true
    }
  },
  "DownstreamApis": {
    "MsGraph": {
      "BaseUrl": "https://graph.microsoft.com/v1.0/",
      "Scopes": [
        "User.Read"
      ]
    }
  }
}

Replace User.Read with the delegated Microsoft Graph permissions required by the operation. Don't use the application-permission .default scope for the agent user pattern.

Enabling overrides lets a caller select the Agent ID and agent's user account used for token acquisition. Keep the sidecar on a private network that only trusted agent code can access. Don't populate AgentIdentity, AgentUserId, or AgentUsername directly from untrusted request input.

Get an authorization header

Request a token without an inbound human-user token:

GET /AuthorizationHeaderUnauthenticated/MsGraph?AgentIdentity={agent-id}&AgentUserId={agent-user-object-id}

The endpoint doesn't require an inbound Authorization header. You can use AgentUsername instead of AgentUserId when the user principal name is the stable identifier available to the application. Don't send both parameters.

Send the returned authorizationHeader to the configured Microsoft 365 API.

Call Microsoft Graph

The following example requests an authorization header for the agent's user account and uses it to call Microsoft Graph:

import requests

SIDECAR_URL = "http://localhost:5000"
AGENT_IDENTITY_CLIENT_ID = "<agent-identity-client-id>"
AGENT_USER_OBJECT_ID = "<agent-user-object-id>"

sidecar_response = requests.get(
    f"{SIDECAR_URL}/AuthorizationHeaderUnauthenticated/MsGraph",
    params={
        "AgentIdentity": AGENT_IDENTITY_CLIENT_ID,
        "AgentUserId": AGENT_USER_OBJECT_ID,
    },
    timeout=5,
)
sidecar_response.raise_for_status()
authorization_header = sidecar_response.json()["authorizationHeader"]

graph_response = requests.get(
    "https://graph.microsoft.com/v1.0/me",
    headers={"Authorization": authorization_header},
    timeout=10,
)
graph_response.raise_for_status()
profile = graph_response.json()

Keep SIDECAR_URL on loopback in the shared network namespace. Treat authorizationHeader as a credential, and don't log it.

Configure the Microsoft 365 resource

The access token doesn't add the agent user to a team, create a mailbox, share a file, or assign a license. Configure those resources through their supported administration or Microsoft Graph APIs:

Next step

Authenticate users if the agent also handles requests from signed-in users.