Szenario: Teams-Bot greift im Benutzerkontext auf Azure Ressourcen zu

Im Entwicklungsverlauf eines Teams–Bots zeigt sich folgendes Anforderungsszenario: Der Bot soll im Kontext der angemeldeten Person auf weitere Azure–Ressourcen zugreifen.

Dieser Beitrag behandelt die dafür notwendige Grundlage in Azure: Single SignOn (SSO)-, sowie die korrekte Einrichtung des OnBehalfOf(OBO)Flows. Neben dem Rollenverständnis und konkreten Konfigurationsschritten werden kompakte Codebeispiele aus einer Referenzimplementierung erläutert, einschließlich der Integration von Azure AI Search mit Zugriffskontrolle auf Dokumentebene (RBAC) über den Bot. 

Warum in diesem Szenario die Tokenbeschaffung via OBO zwingend erforderlich ist

Das Teams–SSO stellt dem Bot ein Token bereit, dessen Audience auf die BotAPI (App Registration: ExposeanAPI, z. B. api://botid-<CLIENT_ID>/access_as_user) gerichtet ist. Dieses Token ist nicht für nachgelagerte Dienste wie Azure AI Search verwendbar, da die Audience und Scopes nicht passen.

Azure AI Search verlangt für Abfragen im Benutzerkontext ein delegiertes Zugriffstoken mit Audience https://search.azure.com und Scope .default. Nur mit einem solchen Ressourcentoken kann der Dienst den Identitätskontext der angemeldeten Person auswerten und RowLevel Security zuverlässig erzwingen.

Der OBOFlow löst genau dieses Problem:

Das vom TeamsClient gelieferte SSOToken, dessen Audience auf die App zeigt, die das OBO-Token anfordert wird serverseitig, sicher und ohne erneute Benutzerinteraktion gegen ein AzureAISearchToken mit korrekter Audience und Scope getauscht. Dieses Token wird anschließend im Header x-ms–query–source-authorization an Azure AI Search übergeben, damit der Dienst die Anfrage der konkreten Person zuordnen und gegen im Index hinterlegte ACLInformationen (z. B. userIds, groupIds) prüfen kann. 

Warum Alternativen nicht geeignet sind 

Optionen wie reine Query– oder AdminKeys des SearchDienstes sind für dieses Anforderungsszenario ungeeignet. Ein Key authentifiziert nur die Anwendung, nicht die Person, und würde die Durchsetzung von dokumentenbezogenen Berechtigungen im Sinne von LeastPrivilege und Compliance unterlaufen.  

Auch reine Anwendungsberechtigungen (Application Permissions) ohne Delegation sind problematisch, da sie den individuellen Kontext der angemeldeten Person nicht abbilden. Das OBOMuster stellt dagegen sicher, dass der Bot als vertraulicher Client agiert, die Identität delegiert und alle Downstream–Aufrufe, wie etwa Microsoft Graph oder Azure AI Search, mit der tatsächlichen Benutzeridentität stattfinden.  

Ausgangslage und Zielsetzung 

Ziel ist ein Teams-Bot, der: 

• ein SSO-Token aus dem Teams-Client erhält, 

• dieses Token mittels OBO-Flow gegen Ressourcentokens (z.B. Microsoft Graph, Azure AI Search) eintauscht, 

• Downstream-Aufrufe im Benutzerkontext ausführt (z.B. Row-Level Security in Azure AI Search wirksam macht). 

Dabei sind drei Elemente entscheidend: die App-Registrierung (Expose an API + API Permissions), die Bot OAuth Connection im Azure Bot Service und der OBO-Flow in der Applogik. 

Architekturüberblick und Rollen 

1. Teams-Client: initiiert SSO und liefert das SSO-Token an den Bot. Das SSO Token muss, damit der OBO-Flow funktioniert, auf die App von der aus der Flow aufgerufen wird, ausgestellt sein.
2. Azure Entra ID (Azure AD): stellt Tokens aus, verwaltet App-Registrierungen, Scopes und Clientautorisierungen. 
3. Bot (Azure Bot Service + App Service): nimmt das SSO-Token entgegen, tauscht es via OBO gegen Tokens für Ziel-APIs (mit dem entsprechenden Scopes. Im Falle von AI Search: https://search.azure.com/.default). 
4. Downstream-APIs können mit dem OBO Token verwendet werden: 

• • Microsoft Graph (z. B. Gruppenmitgliedschaftsprüfung), 

• • Azure AI Search (das Access Token wird im Header x-ms-query-source-authorization übertragen, damit Row-Level Security wirksam wird). 
  • uvm. 

Konfiguration in Azure (SSO-Grundlage) 

1) App-Registrierung: Expose an API 

• Application ID URI setzen: 
  • Format: api://botid-<CLIENT_ID> 
• Scope anlegen: 
  • Name: access_as_user 
  • Who can consent: Admins and users 
  • State: Enabled 
• Autorisierte Clientanwendungen hinzufügen (Mindestens die Teams-Clients): 
  • Mindestens die Teams-Clients
    • 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams Mobile/Desktop) 
    • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams Web)

• • Scope-Zuordnung: access_as_user

Hinweis: Die autorisierten Clients verhindern wiederholte Zustimmungsprompts und stellen eine reibungslose SSO-Erfahrung sicher. 

2) App-Registrierung: API-Berechtigungen (Delegated) 

API Berechtigunge hinzufügen, auf welche der Bot Zugriff haben soll. Bspw.: 

• Azure Cognitive Search: 
  • user_impersonation (Delegated) 

 Nach dem ersten Deployment ist ggf. der Admin-Consent zu erteilen, damit OBO-gestützte Graph-Aufrufe funktionieren. 

3) Azure Bot Service: OAuth Connection (AAD v2) 

Im Azure Bot Service muss unter Settings -> Configuration -> Add OAuth Connection Settings eine OAuth Connection registriert werden: 

• Name: api (muss mit der App-Konfiguration im Code übereinstimmen)  

• Service Provider: Azure Active Directory v2 

• Client ID: Client-ID der App-Registrierung 

• Client secret: Secret der App-Registrierung 

• Tenant ID: common (Multi-Tenant) oder die feste Tenant-ID 

• Token Exchange URL: api://botid-<BOT_ID> 

• Scopes: api://botid-<BOT_ID>/access_as_user 

Diese Connection liefert das SSO-Token an die App. 

Codebeispiele aus der Referenzimplementierung 

Die folgenden Auszüge zeigen, wie ein SSO-Token empfangen und persistiert wird, ein OBO-Token für Zielressourcen bezogen wird und wie nachgelagerte APIs im Benutzerkontext aufgerufen werden. Der Bot wurde mithilfe der Teams AI Library erstellt. 

SSO Token: 

In Teams AI gibt es die Möglichkeit bestimmte Events, wie das Sign-In-Event zu subscriben. Dort lässt sich dann eine eigne Logik implementieren, um das Token bspw. in einem globalen State zu speichern. 

OBO-Flow:  

Um im Namen der angemeldeten Person auf Ressourcen (z. B. Azure AI Search) zuzugreifen, wird das SSO-Token per OBO-Flow gegen ein Access Token mit passendem Scope der entsprechenden Ressource (bspw.: https://search.azure.com/.default) getauscht: 

Aufruf von Downstream APIs: 

Mithilfe des erhaltenen OBO-Token lassen sich nun Downstream APIs aufrufen wie eine Vektor-Suche in Azure AI Search. Der Benutzerkontext wird über den Header x-ms-query-source-authorization an Azure AI Search übergeben. Dadurch greift Row-Level-Security anhand der im Index hinterlegten Benutzer-/Gruppen-IDs.