Bot Users Are Identified Only by Their Channel, Within the Bot's Own Tenant or Workspace
Context
packages/bot receives Bot Framework activities from Azure Bot Service and answers them by running an agent or an LLM chat as the platform user behind the message. That user is the Keycloak account found by email (ADR 2026_06_08_no_bot_first_keycloak_provisioning). Each endpoint is configured by a PathEntity holding the Azure bot's credentials (APP_ID, APP_PASSWORD, APP_TENANTID) and, for Slack, a bot token.
Three things were missing (aihub-core-private#378):
- No inbound authentication. Nothing validated the activity's JWT. The SDK's
CloudAdapterruns a turn with anonymous claims when no middleware has stored verified ones, and theKeycloakAuthHandlerpassed to the controllers was never a dependency of any route. The statement in ADR2026_06_08that the bot authenticates inbound activities with Azure Bot Service credentials did not hold. - Identity from a field the sender controls. On every channel except Teams, the email was taken from the activity's
from.name. - No access check. The bot never asked whether the resolved user may use the agent or model behind the endpoint.
Fixing the first is not enough on its own. The SDK's JwtTokenValidator checks only the signature and the audience, so the issuer, the caller and the service URL need checks of their own. And an email that a channel lookup returns is only as trustworthy as the tenant or workspace that issued it, while the platform maps a bot user to an account by email alone.
Decision Drivers
- The sender must not choose the identity. Only what Azure Bot Service and the channel vouch for may decide who a message comes from.
- Fail closed. When the bot cannot verify the sender, it refuses with a clear reply instead of guessing.
- Use the mapping the platform already has. Accounts are found by email (ADR
2026_06_08); no new provisioning or identity linking. - No new configuration. Only the existing
PathEntityfields; no environment keys, no schema change. - Teams and Slack keep working end to end.
Decision
Every activity is authenticated
All activity routes (agent, OpenAI, bot-in-the-loop) go through RoutesService.process_activity(), which runs BotActivityAuthenticator against the path's credentials before the adapter sees the activity:
- signature from Microsoft's published keys, audience equal to the path's
APP_ID; - issuer among the Bot Framework issuer and the path's tenant issuers;
- no agent-to-agent tokens, which other applications can obtain;
- the token's
serviceurlclaim equal to the activity'sserviceUrl, so a reply, and every lookup the bot makes through that URL, goes back to the channel that sent the message.
The verified claims are stored where the CloudAdapter reads them. A missing or invalid token gets 401, a path with no bot configured gets 404. The KeycloakAuthHandler remains only because the Controller constructor requires one.
The identity comes from the channel
- Teams: the email comes from the member roster (
get_conversation_member), called through the token-bound service URL. - Slack: the email comes from
users.infofor the user id infrom.id, called with the path's bot token (scopesusers:readandusers:read.email). - Every other channel (Web Chat, Direct Line, Emulator) has no such lookup and is not supported on the production bot. Its users get the localized reply
bot.error.unverified_user("cannot verify who you are"). The Emulator works only throughplayground/testing/main.py, which skips the token check and stubs the email.
from.name is never used.
Only the bot's own tenant or workspace
- Teams: the member's
tenant_id, as the roster returns it, must equal the path'sAPP_TENANTID. The member's tenant is used, not the conversation's: in a shared channel the conversation belongs to the host tenant while external members keep their home tenant. A path withoutAPP_TENANTIDrefuses Teams users. - Slack: the user's
team_idmust equal the workspace the path's token belongs to (auth.test, cached per token inSlackUtils).
Refusals use the same unverified_user reply and log the reason (foreign tenant, foreign workspace, missing scope, no tenant configured) for operators.
Access is enforced
AgentCompletionHandler checks has_access_to_agent and OpenaiCompletionHandler checks has_access_to_model for the resolved user. A refusal gets the localized reply bot.error.access_denied.
Considered Alternatives
Rejected: match Teams users by their Azure AD object id
The roster gives the object id, but Keycloak's azure-ad provider links accounts by the OIDC sub, which Entra ID issues per application. Matching the object id would mean changing the provider mapping and re-linking every user. Email within the bot's own tenant identifies the same person.
Deferred: a separate PathEntity field for the tenant a path serves
It would let a MultiTenant registration, which has no APP_TENANTID, serve Teams users. No deployment is known to need it. If one does, the field can be added on top, falling back to APP_TENANTID.
Rejected: pin the tenant only when APP_TENANTID is set
It would leave the check off on MultiTenant registrations, the paths that any tenant can reach.
Rejected: keep Web Chat and Direct Line
Their users are identified only by what the client sends, so no platform account can be verified for them.
Consequences
Positive
- A message reaches an agent only when Azure Bot Service sent it for that bot. It runs as the user the channel vouches for, inside the bot's own tenant or workspace, and only on an agent or model that user may use.
- No new configuration or environment keys.
- Rejected users get a localized, actionable reply; the log tells an operator what to fix.
Trade-offs
- Web Chat and Direct Line no longer work on the production bot.
- A MultiTenant Teams registration cannot serve Teams users. Filling in
APP_TENANTIDis not a field edit: it also changes the bot's outbound sign-in and the issuers it accepts, so the bot has to be registered as SingleTenant. - External users (shared channels, federated chat, Slack Connect) are refused. Guests in the bot's own tenant keep working.
- Slack Enterprise Grid users from a sibling workspace have a different
team_idand are refused. - Slack apps need the
users:readandusers:read.emailscopes and a reinstall before the change is deployed. - A
PathEntitywith wrong or empty credentials stops working. - Users need access to the endpoint's agent or model. Under the default
AIHubUserrole (aihub.user.>) everyone has it; deployments with scoped roles must grant it. - Each Slack message costs one
users.infocall;auth.testis cached per token for 30 days.
Related Decisions
2026_06_08_no_bot_first_keycloak_provisioning: the bot maps users to Keycloak accounts by email and does not create them. This ADR makes its statement about authenticated inbound activities true and restricts which emails count.2025_12_28_keycloak_as_identity_broker: Keycloak brokers the Azure AD identities the bot's emails are matched against.
