Sichere OpenAPI-Toolaufrufe vom Foundry Agent Service

Foundry Agent Service kann einen App Service OpenAPI-Endpunkt anonym oder mit verwalteter Identität aufrufen. Verwenden Sie eine verwaltete Identität, wenn die App Service-Authentifizierung den Endpunkt schützt.

Dieses Szenario enthält zwei unabhängige Managed-Identity-Richtungen:

• Wenn App Service Foundry aufruft, ist der Anrufer die vom App Service System zugewiesene verwaltete Identität. Azure Role-Based Access Control (RBAC) auf der Foundry-Ressource oder im Projekt autorisiert den Aufruf.
• Wenn Foundry den OpenAPI-Endpunkt von App Service aufruft, ist der Aufrufer die systemseitig zugewiesene verwaltete Identität der übergeordneten Foundry-Ressource. App Service Authentifizierungstoken-Validierung und Erlaubnislisten autorisieren den Anruf.

Die Microsoft Entra-Anwendung für die App Service-Authentifizierung ist die geschützte API-Ressource. Es ersetzt keinen der beiden Aufrufe für Managed Identity.

Die folgende Tabelle fasst die Identitäten und Anwendungen in diesem Szenario zusammen.

Voraussetzungen

• Eine App Service-App mit OpenAPI-Endpunkten. Wenn Sie Ihrer App OpenAPI-Funktionen hinzufügen müssen, lesen Sie eines der folgenden Lernprogramme:

  • Hinzufügen einer App Service-App als Tool im Foundry Agent Service (.NET)
  • Hinzufügen einer App Service-App als Tool im Foundry Agent Service (Java)
  • Hinzufügen einer App Service-App als Tool im Foundry Agent Service (Python)
  • Hinzufügen einer App Service-App als Tool im Foundry Agent Service (Node.js)

• Ein Microsoft Foundry-Projekt, bei dem du deine App als OpenAPI-Tool hinzufügst.

Finden Sie die verwalteten Identitäts-IDs der übergeordneten Foundry-Ressource

Der Foundry Agent Service verwendet die systemzugewiesene verwaltete Identität der übergeordneten Foundry-Ressource , wenn ein OpenAPI-Tool aufgerufen wird. Für diese Anfrage wird die verwaltete Identität des Foundry-Projekts nicht verwendet.

Sie benötigen zwei Bezeichner für die Identität der übergeordneten Ressource:

• Anwendungs-ID (Client-ID): Erscheint im Claim azp des Zugriffstokens und wird für die Prüfung zulässiger Clientanwendungen bei der App Service-Authentifizierung verwendet.
• Objekt-(Haupt-)ID: Erscheint im Anspruch des Tokens oid und wird verwendet, wenn die App Service-Authentifizierung den Zugriff auf bestimmte Identitäten beschränkt.

1. Im Foundry-Portal öffnen Sie Ihr Projekt und wählen Sie dann im oberen Menü "Verwalten ".

2. Wählen Sie die übergeordnete Ressource in Project Details aus und wählen Sie dann im Azure-Portal Öffnen.

3. Wählen Sie im linken Menü der Foundry-Ressource die Option "Ressourcenverwaltungsidentität>" aus.

4. Kopieren Sie unter "System zugewiesen" den Wert der Objekt-ID (Prinzipal-ID) für einen späteren Zeitpunkt.

5. Suchen Sie im Azure-Portal nach Microsoft Entra-ID, und wählen Sie sie aus.

6. Suchen Sie im Suchfeld nach der objekt-ID, die Sie kopiert haben, und wählen Sie sie in den Suchergebnissen aus.

7. Kopieren Sie auf der Seite "Übersicht " den Wert der Anwendungs-ID.

   Die Objekt-ID ist dieselbe wie die, die für die systemzugewiesene verwaltete Identität angezeigt wird. Speichere sowohl die Anwendungs-ID als auch die Objekt-ID für die Konfiguration der App Service-Authentifizierung.

Konfigurieren der Microsoft Entra-Authentifizierung für Ihre App

1. Navigieren Sie im Azure-Portal zu Ihrer App Service-App.

2. Wählen Sie im linken Menü Ihrer App Einstellungen>Authentifizierungaus, und wählen Sie dann Identitätsanbieter hinzufügenaus.

3. Wählen Sie auf der Seite " Identitätsanbieter hinzufügen " Microsoft als Identitätsanbieter aus, um eine neue App-Registrierung zu erstellen.

4. Wählen Sie unter Zugriff einschränken die Option Authentifizierung erforderlich aus.

5. Wählen Sie unter Zusätzliche Prüfungen bei Anforderungen für die Clientanwendung die Option Anfragen von bestimmten Clientanwendungen zulassen aus.

6. Wählen Sie das Bleistiftsymbol aus und konfigurieren Sie die erlaubten Client-Anwendungen:

   • Füge die Anwendungs-ID hinzu, die du in Die verwalteten Identitäts-IDs der übergeordneten Foundry-Ressource suchen kopiert hast. Diese ID erlaubt Token, die von der übergeordneten Foundry-Ressourcenidentität angefordert werden.
   • Wenn die App eine interaktive Browseranmeldung unterstützt, fügen Sie auch die eigene Anwendungs-ID (Client-ID) der Microsoft Entra-Anwendung für die App Service-Authentifizierung hinzu. Diese ID ermöglicht es, während der Benutzeranmeldung Token an die Webanwendung auszustellen. Wenn du eine neue App-Registrierung erstellst, füge diese ID hinzu, nachdem du den Identitätsanbieter erstellt hast.

7. Konfiguration der Identitätsanforderung:

   • Für die restriktivste Richtlinie für einen Endpunkt, der nur von Foundry aufgerufen wird, wählen Sie Anfragen von bestimmten Identitäten zulassen. Wählen Sie das Bleistiftsymbol aus und fügen Sie die Objekt-ID der übergeordneten Foundry-Ressourcenidentität hinzu.
   • Wenn die App auch die interaktive Browseranmeldung unterstützt, wählen Sie Anforderungen von jeder Identität zulassen, damit Mandantenbenutzer nicht blockiert werden. Diese Einstellung erlaubt keinen anonymen Zugriff. Anfragen müssen weiterhin ein gültiges Token von einer erlaubten Client-Anwendung und dem konfigurierten Tenant enthalten.

8. Für die Mandantenanforderung wählen Sie Nur Anforderungen vom ausstellenden Mandanten zulassen. Die übergeordnete Foundry-Ressourcenidentität und alle Benutzer, die sich anmelden, müssen in diesem Tenant sein.

9. Konfigurieren Sie nicht authentifizierte Anfragen:

   • Wenn die App nur API-Clients bedient, wähle HTTP 401 Unauthorized: empfohlen für APIs.
   • Wenn die App eine interaktive Browseranmeldung unterstützt, wählen Sie Umleitung „HTTP 302 Found“ aus, und wählen Sie dann Microsoft als Umleitungsanbieter aus.

10. Wählen Sie "Hinzufügen" aus, um den Identitätsanbieter zu erstellen.

    Das folgende Bild zeigt die schmalste Konfiguration, die nur für eine Gießerei gilt.

    

11. Wenn die App interaktive Browser-Anmeldung unterstützt, bearbeite den Anbieter und stelle sicher, dass der Token-Store aktiviert ist. Wenn du eine neue App-Registrierung erstellt hast, füge deren Anwendungs-ID zu den erlaubten Client-Anwendungen hinzu.

Du brauchst beide Anwendungs-IDs, wenn die App interaktive Browser-Anmeldung unterstützt. Eine reine Foundry-API benötigt nur die Anwendungs-ID der übergeordneten Foundry-Ressourcenidentität.

Aktualisieren Sie die Anwendungs-ID-URI der App-Registrierung.

Eine Anwendungs-ID-URI identifiziert die geschützte API als OAuth-Ressource. Für ein OpenAPI-Tool mit verwalteter Identität muss die Zielgruppe genau mit einer Anwendungs-ID-URI übereinstimmen, die in der App Service-Authentifizierungsanwendung Microsoft Entra registriert ist. Foundry verwendet diesen Wert als Zielgruppe, wenn es einen Zugriffstoken mit der übergeordneten Foundry-Ressourcenidentität anfordert.

Die Anwendungs-ID und die Anwendungs-ID-URI sind unterschiedliche Eigenschaften:

• Die Anwendungs-ID, auch Client-ID genannt, ist eine generierte GUID.
• Eine Anwendungs-ID-URI ist eine URI, die eine API oder Ressource identifiziert, die der Anwendung gehört. Es muss nicht unbedingt die Client-ID der Anwendung enthalten.

Wählen Sie eine stabile Anwendungs-ID-URI und behandeln Sie sie als Teil des API-Vertrags:

Die URI muss gültig, einzigartig für den Mieter sein und von der Anwendungs-ID-URI-Richtlinie des Mieters akzeptiert werden. Eine einfache Zeichenkette wie wie some-random-string ist keine gültige Anwendungs-ID-URI.

Dieser Leitfaden verwendet die vollständige HTTPS App Service URL:

https://<app-name>.azurewebsites.net

1. Nachdem die Konfiguration des Microsoft-Anbieters abgeschlossen ist, wählen Sie sie in der Spalte " Identitätsanbieter " aus, um die App-Registrierungsseite zu öffnen.

2. Wählen Sie im linken Menü die Option "Verwalten>API veröffentlichen" aus.

3. Wählen Sie neben dem Anwendungs-ID-URI"Bearbeiten" aus.

4. Ändern Sie den Wert der vollständigen HTTPS-URL Ihrer App Service-App, zum Beispiel https://<app-name>.azurewebsites.net.

   Sie finden den Hostnamen der App auf der Seite "Übersicht" in der Standarddomäne.

5. Für eine neue App-Registrierung stellen Sie sicher, dass die Access-Token-Version auf 2 gesetzt ist.

6. Wählen Sie Speichern aus.

Das spätere Ändern der Anwendungs-ID-URI erfordert das Aktualisieren der Foundry-Tool-Zielgruppe und alle anderen Kunden, die Token für die API anfordern.

Die entsprechende OpenAPI-Authentifizierungskonfiguration lautet:

{
  "type": "managed_identity",
  "security_scheme": {
    "audience": "https://<app-name>.azurewebsites.net"
  }
}

Du musst die Tool-Zielgruppe nicht unter Erlaubte Token-Zielgruppen auflisten. Die App Service-Authentifizierung erkennt Ressourcenkennungen, die Sie in seiner Microsoft Entra-Anwendung registrieren. Umgekehrt wird durch das ausschließliche Hinzufügen eines Werts zu Zulässige Tokenzielgruppen weder eine OAuth-Ressource registriert noch Microsoft Entra ermöglicht, dafür ein Token auszustellen.

Verwenden Sie nicht den Foundry-Projektendpunkt oder die App Service Client-ID als Zielgruppe, es sei denn, Sie konfigurieren diesen genauen Wert ebenfalls als Anwendungs-ID-URI. Andere gültige Anwendungs-ID-URI-Formate, einschließlich api:// URIs, funktionieren, wenn der registrierte Wert und die Zielgruppe exakt übereinstimmen. Für verwandte Randfälle siehe Häufig gestellte Fragen.

Konfigurieren Sie die geschützte API deklarativ

Verwenden Sie Bicep, um die geschützte API und die App Service-Authentifizierungsrichtlinie zu konfigurieren. Das folgende Muster geht davon aus:

• webApp ist die App Service-Ressource.
• entraApp ist ein Modul, das die Microsoft-Entra-Anwendung für die App Service-Authentifizierung erstellt.
• foundryAccountClientId ist die Anwendungs-ID der übergeordneten Ressourcenidentität von Foundry.
• appServiceAuthCredentialSettingName ist der Name der App-Einstellung, die das bestehende App-Service-Authentifizierungs-Clientgeheimnis enthält.

Im Microsoft Graph Bicep-Anwendungsmodul konfigurieren Sie die App Service URL als Identifier-URI und fordern die Zugriffstoken der Version 2 an:

extension microsoftGraphV1

param environmentName string
param appServiceUrl string

resource app 'Microsoft.Graph/applications@v1.0' = {
  uniqueName: 'my-app-${environmentName}'
  displayName: 'My app (${environmentName})'
  signInAudience: 'AzureADMyOrg'
  identifierUris: [
    appServiceUrl
  ]
  api: {
    requestedAccessTokenVersion: 2
  }
  web: {
    homePageUrl: appServiceUrl
    redirectUris: [
      '${appServiceUrl}/.auth/login/aad/callback'
    ]
  }
}

output clientId string = app.appId
output webAppUrl string = appServiceUrl

Das folgende authsettingsV2 Beispiel erlaubt sowohl interaktive Browser-Anmeldung als auch Foundry OpenAPI-Aufrufe:

@description('Parent Foundry resource identity application ID')
param foundryAccountClientId string = ''

resource webAppAuthSettings 'Microsoft.Web/sites/config@2024-11-01' = {
  name: '${webApp.name}/authsettingsV2'
  properties: {
    platform: {
      enabled: true
    }
    globalValidation: {
      requireAuthentication: true
      unauthenticatedClientAction: 'RedirectToLoginPage'
      redirectToProvider: 'azureActiveDirectory'
    }
    identityProviders: {
      azureActiveDirectory: {
        enabled: true
        registration: {
          clientId: entraApp.outputs.clientId
          clientSecretSettingName: appServiceAuthCredentialSettingName
          openIdIssuer: 'https://login.microsoftonline.com/${tenant().tenantId}/v2.0'
        }
        validation: {
          allowedAudiences: [
            'api://${entraApp.outputs.clientId}'
          ]
          defaultAuthorizationPolicy: {
            allowedApplications: concat(
              [
                entraApp.outputs.clientId
              ],
              empty(foundryAccountClientId) ? [] : [foundryAccountClientId]
            )
            allowedPrincipals: {}
          }
        }
      }
    }
    login: {
      tokenStore: {
        enabled: true
      }
    }
    httpSettings: {
      requireHttps: true
    }
  }
}

Geben Sie die Foundry Resource Identity Application ID durch Azure Developer CLI (AZD) weiter:

{
  "foundryAccountClientId": {
    "value": "${AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID=}"
  }
}

Dann konfigurieren Sie die Umgebung und setzen Sie neu aus:

azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
azd provision

Konfigurieren des OpenAPI-Tools in Microsoft Foundry

1. Wählen Sie wieder im Foundry-Portal Ihren Agenten aus.

2. Suchen Sie das OpenAPI-Tool, und wählen Sie ...>Bearbeiten.

3. Überprüfen Sie, dass das OpenAPI 3.0+ Schema-Feld das Schema Ihrer App Service App enthält. Wenn nicht, füge dein OpenAPI-Schema ein. Weitere Informationen finden Sie unter Verwenden von OpenAPI mit Foundry Agent Service.

4. Wählen Sie für die Authentifizierungsmethodeverwaltete Identität aus.

5. Für Publikum geben Sie die zuvor konfigurierte Anwendungs-ID-URI ein. Für die Konfiguration in diesem Leitfaden verwenden Sie die vollständige HTTPS-URL Ihrer App Service App, zum Beispiel https://<app-name>.azurewebsites.net. Die Werte müssen exakt übereinstimmen.

6. Wählen Sie das Updatetool aus.

Testen des Agents

1. Wählen Sie im Foundry-Portal Ihren Agenten aus, und wählen Sie "Testen" im Playground aus.

2. Chatten Sie mit dem Agent, um Ihre OpenAPI-Endpunkte zu testen. Beispiel:

   • Alle Aufgaben anzeigen.
   • Erstellen Sie eine Aufgabe namens "Lebensmittel kaufen".
   • Aktualisieren Sie diese Aufgabe auf "Lebensmittel kaufen und Abendessen kochen".

Wenn Sie die Authentifizierung korrekt konfigurieren, ruft der Agent die APIs Ihrer App über das OpenAPI-Tool auf.

Häufig gestellte Fragen

Warum kann ich das OpenAPI-Tool vor der Konfiguration der App Service-Autorisierung speichern?

Wenn Sie ein OpenAPI-Tool speichern, validiert Foundry dessen Schema, Audience-Format und Definition. Es ruft den App Service-Endpunkt nicht auf. Sie können das Tool daher speichern, bevor Sie die übergeordnete Foundry-Ressourcenidentität zur App Service-Erlaubnisliste hinzufügen.

Konfigurieren Sie die Erlaubnisliste, bevor Sie das Tool im Playground oder zur Laufzeit aufrufen. Bis dahin lehnt App Service Toolaufrufe ab.

Warum scheitert die Standardzielgruppe api://<client-id> manchmal?

Das App Service-Portal erstellt in der Regel eine Microsoft Entra-Anwendung mit api://<application-client-id> als Anwendungs-ID-URI. In diesem Fall kann Foundry denselben Wert wie sein Publikum nutzen.

Eine benutzerdefinierte oder deklarative Bereitstellung kann die identifierUris-Sammlung der Microsoft Entra-Anwendung leer lassen, selbst wenn bei der App Service-Authentifizierung unter api://<client-id> etwas angezeigt wird. In diesem Zustand kann Foundry kein verwaltetes Identitätstoken für den Wert erhalten, da es sich nicht um eine registrierte Ressourcenkennung handelt.

Um das Problem zu beheben, nutzen Sie eine dieser Optionen:

• Registrieren Sie api://<client-id> als Anwendungs-ID-URI und verwenden Sie es als Foundry-Zielgruppe.
• Registrieren Sie die App Service HTTPS-URL als Application ID URI und verwenden Sie diese URL als Foundry-Audience.

Beheben Sie die Nichtübereinstimmung nicht, indem Sie beliebige Zeichenfolgen zu allowedAudiences hinzufügen.

Kann die App Service-Authentifizierung ohne eine Anwendungs-ID-URI funktionieren?

Interaktive Browser-Anmeldung kann ohne Anwendungs-ID-URI funktionieren, da der Browserfluss ein ID-Token für die Client-ID der Webanwendung verwendet.

Der OpenAPI-Flow der Foundry Managed Identity benötigt ein Zugriffstoken für eine registrierte API-Ressource. Für diesen Flow konfigurieren Sie eine Anwendungs-ID-URI und verwenden Sie denselben Wert wie die Tool-Audience.

Fehlerbehebung bei Authentifizierung und Autorisierung

Das OpenAPI-Tool erhält HTTP 401

Eine HTTP-401-Antwort bedeutet, dass die App Service-Authentifizierung die Anfrage nicht authentifizieren konnte. Zu den möglichen Ursachen gehören:

• Du hast die verwaltete Identität für das OpenAPI-Tool nicht ausgewählt.
• Die Zielgruppe entspricht nicht genau der Microsoft Entra Application ID URI.
• Der Token-Aussteller oder Tenant stimmt nicht mit der App Service-Authentifizierung überein.
• Du hast die Anwendungs-ID-URI in der Microsoft Entra-Anwendung nicht konfiguriert.

Überprüfen Sie, ob die OpenAPI-Audience genau mit einer registrierten Anwendungs-ID übereinstimmt. Für die Konfiguration in diesem Leitfaden ist der Wert die vollständige HTTPS-URL von App Service.

Das OpenAPI-Tool erhält HTTP 403

Eine HTTP-403-Antwort bedeutet, dass die Authentifizierung erfolgreich war, aber die Autorisierungsprüfungen haben den Anrufer abgelehnt. Zu den möglichen Ursachen gehören:

• Du hast die Identität des Foundry-Projekts zur Zulassungsliste hinzugefügt, anstelle der Identität der übergeordneten Foundry-Ressource.
• Du hast die Objekt-ID eingegeben, bei der die App Service-Authentifizierung eine Anwendungs-ID erfordert.
• Du hast die Anwendungs-ID der übergeordneten Ressource nicht zu allowedApplications hinzugefügt.
• Du hast die übergeordnete Ressourcenobjekt-ID nicht zur Liste der erlaubten Identitäten für eine Foundry-Only-Konfiguration hinzugefügt.

Inspizieren Sie die Zugriffstoken-Behauptungen:

• azp sollte der Anwendungs-ID der übergeordneten Ressourcenidentität von Foundry entsprechen.
• oid sollte der Objekt-ID der übergeordneten Ressourcenidentität von Foundry entsprechen.

Browser-Nutzer erhalten nach der Anmeldung HTTP 403

Für eine App, die interaktive Browser-Anmeldung unterstützt, überprüfen Sie diese Einstellungen:

• Die eigene Client-ID der Web-App bleibt in allowedApplications.
• Die Anforderung an die Identität erlaubt reguläre Mandantenbenutzer.
• Unauthentifizierte Browseranfragen verwenden HTTP 302 statt HTTP 401.

Das Tool funktioniert anonym, scheitert jedoch nach Aktivierung der Authentifizierung

Aktualisieren Sie das Tool von Anonym auf Verwaltete Identität, legen Sie die Zielgruppe auf eine registrierte Anwendungs-ID-URI fest, und lassen Sie die Identität der übergeordneten Foundry-Ressource zu.

Bereinigen von Ressourcen

Wenn Sie Ressourcen aus diesem Szenario löschen oder ersetzen:

• Entferne die übergeordnete Foundry-Ressourcenidentität aus der App Service-Authentifizierung, wenn du die Foundry-Ressource löschst oder ersetzt.
• Löschen Sie die Microsoft Entra-Anwendung für die App Service-Authentifizierung, wenn Sie die App Service-App dauerhaft löschen. Dieser Schritt verhindert auch das zuvor beschriebene Risiko der verwaisten Anwendungs-ID-URI.
• Wenn Sie für die App Service-Authentifizierung ohne Geheimnis eine benutzerzugewiesene Identität und eine Anmeldeinformation für eine föderierte Identität verwenden, löschen Sie diese Identität und diese Anmeldeinformation zusammen mit der App.

Verwandte Inhalte

• Konfigurieren Sie Ihre App Service- oder Azure Functions-App für die Nutzung der Microsoft Entra-Anmeldung
• Integrieren von KI in Ihre Azure App Service-Anwendungen
• Was ist Foundry Agent Service?