Säkra OpenAPI-verktygsanrop från Foundry Agent Service

Foundry Agent Service kan anropa en App Service OpenAPI-endpoint anonymt eller med hanterad identitet. Använd hanterad identitet när App Service-autentisering skyddar slutpunkten.

Detta scenario innehåller två oberoende styrda identitetsriktningar:

• När App Service anropar Foundry är anroparen App Services systemtilldelade hanterade identitet. Azure rollbaserad åtkomstkontroll (RBAC) på Foundry-resursen eller projektet auktoriserar anropet.
• När Foundry anropar App Service OpenAPI-slutpunkten är den anropande entiteten den överordnade Foundry-resursens systemtilldelade hanterade identitet. App Service-autentiseringstokenvalidering och tillåtslistor auktoriserar samtalet.

App Service-autentiseringen Microsoft Entra-applikationen är den skyddade API-resursen. Det ersätter inte heller att anropa managed identity.

Följande tabell sammanfattar identiteter och tillämpningar i detta scenario.

Förutsättningar

• En App Service-app med OpenAPI-slutpunkter. Om du behöver lägga till OpenAPI-funktioner i din app kan du läsa någon av följande självstudier:

  • Lägga till en App Service-app som ett verktyg i Foundry Agent Service (.NET)
  • Lägga till en App Service-app som ett verktyg i Foundry Agent Service (Java)
  • Lägga till en App Service-app som ett verktyg i Foundry Agent Service (Python)
  • Lägga till en App Service-app som ett verktyg i Foundry Agent Service (Node.js)

• Ett Microsoft Foundry-projekt där du lägger till din app som ett OpenAPI-verktyg.

Hitta den moderbaserade Foundry-resursens hanterade identitets-ID:n

Foundry Agent Service använder den överlägsna Foundry-resursens systemtilldelade hanterade identitet när den anropar ett OpenAPI-verktyg. Den använder inte Foundry-projektets hanterade identitet för denna förfrågan.

Du behöver två identifierare för den överordnade resursens identitet:

• Applikations-ID (klient-ID): Förekommer i åtkomsttokens azp anspråk och används för App Service-autentiseringskontrollen för klientapplikationen.
• Objekt (principal) ID: Förekommer i tokens oid krav och används när App Service-autentisering begränsar åtkomst till specifika identiteter.

1. I Foundry-portalen, öppna ditt projekt och välj sedan Hantera i toppmenyn.

2. Välj föräldraresursen i Project detaljer och välj sedan Öppna i Azure-portalen.

3. I den vänstra menyn för Foundry-resursen väljer du Resurshanteringsidentitet>.

4. Under Systemtilldelad kopierar du värdet för objekt-ID (huvudnamn) för senare.

5. I Azure-portalen söker du efter och väljer Microsoft Entra-ID.

6. I sökrutan söker du efter objekt-ID:t som du kopierade och markerar det i sökresultaten.

7. På sidan Översikt kopierar du värdet för program-ID.

   Objekt-ID:t är detsamma som det som visas för den systemtilldelade hanterade identiteten. Spara både applikations-ID:t och objekt-ID för att konfigurera App Service-autentisering.

Konfigurera Microsoft Entra-autentisering för din app

1. I Azure-portalen navigerar du till din App Service-app.

2. Välj Inställningar> på appens vänstra meny och välj sedan Lägg till identitetsprovider.

3. På sidan Lägg till en identitetsprovider väljer du Microsoft som identitetsprovider för att skapa en ny appregistrering.

4. För Begränsa åtkomst väljer du Kräv autentisering.

5. Under Ytterligare kontroller väljer du Tillåt begäranden från specifika klientprogram för krav på klientprogram.

6. Välj pennikonen och konfigurera de tillåtna klientapplikationerna:

   • Lägg till applikations-ID:t som du kopierade i Hitta ID:n för den överordnade Foundry-resursens hanterade identitet. Detta ID tillåter tokens som begärs av den moderliga Foundry-resursidentiteten.
   • Om appen stödjer interaktiv webbläsarinloggning, lägg även till App Service-autentiseringen för Microsoft Entra-applikationens eget applikations-ID (klient-ID). Detta ID tillåter tokens som utfärdas till webbapplikationen vid användarinloggning. Om du skapar en ny appregistrering lägger du till detta ID efter att du har skapat identitetsleverantören.

7. Konfigurera identitetskrav:

   • För den mest restriktiva policyn för en slutpunkt som endast anropas av Foundry väljer du Tillåt förfrågningar från specifika identiteter. Välj pennikonen och lägg till identiteten för den överordnade Foundry-resursens objekt-ID.
   • Om appen också stödjer interaktiv webbläsarinloggning, välj Tillåt förfrågningar från vilken identitet som helst så att hyresgästanvändare inte blockeras. Denna inställning tillåter inte anonym åtkomst. Förfrågningar måste fortfarande innehålla en giltig token från en tillåten klientapplikation och den konfigurerade tenanten.

8. För krav på hyresgäst, välj Tillåt endast förfrågningar från utfärdarens hyresgäst. Den överordnade Foundry-resursidentiteten och alla användare som loggar in måste finnas i den här klientorganisationen.

9. Konfigurera oautentiserade förfrågningar:

   • Om appen endast tjänar API-klienter, välj HTTP 401 Unauthorized: rekommenderat för API:er.
   • Om appen stödjer interaktiv webbläsarinloggning, välj HTTP 302 Found redirect, och välj sedan Microsoft som omdirigeringsleverantör.

10. Välj Lägg till för att skapa identitetsprovidern.

    Följande bild visar den smalaste konfigurationen endast för Foundry.

    

11. Om appen stödjer interaktiv webbläsarinloggning, redigera leverantören och se till att Token-lagret är aktiverat. Om du har skapat en ny appregistrering, lägg till dess applikations-ID i de tillåtna klientapplikationerna.

Du behöver båda applikations-ID:n när appen stödjer interaktiv webbläsarinloggning. Ett API endast för Foundry kräver bara applikations-ID:t för den överordnade Foundry-resursidentiteten.

Uppdatera appregistreringens program-ID-URI

En applikations-ID-URI identifierar det skyddade API:et som en OAuth-resurs. För ett OpenAPI-verktyg för hanterad identitet måste publiken exakt matcha en applikations-ID-URI som är registrerad i App Service-autentiseringsapplikationen Microsoft Entra. Foundry använder det värdet som målgrupp när det begär en åtkomsttoken med den överordnade Foundry-resursidentiteten.

Applikations-ID och applikations-ID URI är olika egenskaper:

• Applikations-ID:t, även kallat klient-ID, är en genererad GUID.
• En applikations-ID-URI är en URI som identifierar ett API eller en resurs som ägs av applikationen. Det behöver inte innehålla applikationsklient-ID:t.

Välj en stabil applikations-ID-URI och behandla den som en del av API-kontraktet:

URI:n måste vara giltig, unik för hyresgästen och accepteras av hyresgästens applikations-ID URI-policy. En vanlig sträng som till exempel some-random-string är inte en giltig applikations-ID URI.

Denna guide använder hela HTTPS App Service-URL:en:

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

1. När Konfigurationen av Microsoft-providern har slutförts väljer du den i kolumnen Identitetsprovider för att öppna appregistreringssidan.

2. I den vänstra menyn väljer du Hantera Exponera>ett API.

3. Bredvid Program-ID-URI väljer du Redigera.

4. Ändra värdet till din App Service-apps fullständiga HTTPS-URL, till exempel https://<app-name>.azurewebsites.net.

   Du hittar appens värdnamn på sidan Översikt i Standarddomän.

5. För en ny appregistrering, se till att Access-tokenversionen är inställd på 2.

6. Välj Spara.

Att senare ändra applikations-ID:s URI kräver att man uppdaterar Foundry-verktygets publik och alla andra klienter som begär tokens för API:et.

Den motsvarande autentiseringskonfigurationen för OpenAPI-verktyget är:

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

Du behöver inte lista verktygets målgrupp under Tillåtna token-publiker. App Service-autentisering känner igen resursidentifierare som du registrerar i dess Microsoft Entra-applikation. Omvänt innebär det inte att en OAuth-resurs registreras eller att Microsoft Entra kan utfärda en token för den om du bara lägger till ett värde i Tillåtna tokenmålgrupper.

Använd inte Foundry-projektets endpoint eller App Service-klient-ID som målgrupp om du inte också konfigurerar det exakta värdet som Application ID-URI. Andra giltiga applikations-ID-URI-format, inklusive api:// URI:er, fungerar när det registrerade värdet och målgruppen stämmer exakt överens. För relaterade undantagsfall, se Vanliga frågor.

Konfigurera det skyddade API:et deklarativt

Använd Bicep för att konfigurera det skyddade API:et och App Service-autentiseringspolicyn. Följande mönster antager:

• webApp är App Service-resursen.
• entraAppär en modul som skapar App Service-autentiseringsapplikationen Microsoft Entra.
• foundryAccountClientId är den moderliga Foundry-resursidentitetens applikations-ID.
• appServiceAuthCredentialSettingName är namnet på appinställningen som innehåller den befintliga App Service-autentiseringsklienthemligheten.

I Microsoft Graph Bicep applikationsmodulen, konfigurera App Service-URL:en som identifierar-URI och begär åtkomsttoken för version 2:

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

Följande authsettingsV2 exempel tillåter både interaktiv webbläsarinloggning och Foundry OpenAPI-anrop:

@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
    }
  }
}

Skicka med programm-ID:t för Foundry-resursidentiteten via Azure Developer CLI (AZD):

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

Konfigurera sedan miljön och omdistribuera:

azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
azd provision

Konfigurera OpenAPI-verktyget i Microsoft Foundry

1. Gå tillbaka till Foundry-portalen och välj din agent.

2. Leta upp OpenAPI-verktyget och välj ...>Redigera.

3. Kontrollera att schemarutan för OpenAPI 3.0+ innehåller schemat från din App Service-app. Om det inte gör det, klistra in ditt OpenAPI-schema. Mer information finns i Använda OpenAPI med Foundry Agent Service.

4. Som Autentiseringsmetod väljer du Hanterad identitet.

5. För Audience, ange applikations-ID-URI: n som du konfigurerade tidigare. För konfigurationen i denna guide, använd hela HTTPS-URL:en för din App Service-app, till exempel https://<app-name>.azurewebsites.net. Värdena måste stämma exakt överens.

6. Välj Uppdateringsverktyg.

Testa agenten

1. I Foundry-portalen väljer du din agent och väljer Prova på lekplatsen.

2. Chatta med agenten för att testa dina OpenAPI-slutpunkter. Till exempel:

   • Visa mig alla uppgifter.
   • Skapa en uppgift med namnet "Köp matvaror".
   • Uppdatera uppgiften till "Köp matvaror och laga middag".

Om du konfigurerar autentisering korrekt anropar agenten din apps API:er via OpenAPI-verktyget.

Vanliga frågor och svar

Varför kan jag spara OpenAPI-verktyget innan jag konfigurerar App Service-auktorisationen?

När du sparar ett OpenAPI-verktyg validerar Foundry dess schema, publikformat och definition. Den anropar inte App Service-endpointen. Du kan därför spara verktyget innan du lägger till identiteten för den överordnade Foundry-resursen i App Services tillåtelselista.

Konfigurera listan över tillåtna objekt innan du anropar verktyget i Playground eller under körning. Tills dess avvisar App Service verktygsanrop.

Varför misslyckas standardmålgruppen api://<client-id> ibland?

App Service-portalen skapar vanligtvis en Microsoft Entra-applikation med api://<application-client-id> som applikations-ID URI. I så fall kan Foundry använda samma värde som sin publik.

Anpassad eller deklarativ provisionering kan lämna Microsoft Entra-applikationens identifierUris samling tom även när App Service-autentisering visas api://<client-id> under Tillåtna token-målgrupper. I det tillståndet kan Foundry inte få tag på en hanterad identitetstoken för värdet eftersom det inte är en registrerad resursidentifierare.

För att lösa problemet, använd ett av dessa alternativ:

• Registrera api://<client-id> som programmets ID-URI och använd det som Foundry-målgrupp.
• Registrera App Service HTTPS-URL:n som Application ID URI och använd den URL:en som Foundry-målgrupp.

Åtgärda inte mismatchen genom att lägga till godtyckliga strängar i allowedAudiences.

Kan App Service-autentisering fungera utan en Application ID URI?

Interaktiv webbläsarinloggning kan fungera utan en applikations-ID-URI eftersom webbläsarflödet använder en ID-token för webbapplikationens klient-ID.

Foundrys hanterade identitetsflöde OpenAPI behöver en åtkomsttoken för en registrerad API-resurs. För detta flöde, konfigurera en applikations-ID-URI och använd samma värde som verktygspubliken.

Felsök autentisering och auktorisering

OpenAPI-verktyget tar emot HTTP 401

Ett HTTP 401-svar innebär att App Service-autentiseringen inte kunde autentisera förfrågan. Sannolika orsaker inkluderar:

• Du valde inte hanterad identitet för OpenAPI-verktyget.
• Målgruppen stämmer inte exakt överens med Microsoft Entra Application ID URI.
• Tokenutfärdaren eller hyresgästen matchar inte App Service-autentiseringen.
• Du konfigurerade inte applikations-ID-URI:n i Microsoft Entra-applikationen.

Verifiera att OpenAPI-publiken exakt matchar en registrerad applikations-ID URI. För konfigurationen i denna guide är värdet hela App Service HTTPS-URL:n.

OpenAPI-verktyget tar emot HTTP 403

Ett HTTP 403-svar innebär att autentiseringen lyckades, men auktorisationskontrollerna avvisade anroparen. Sannolika orsaker inkluderar:

• Du lade till Foundry-projektidentiteten i tillåtslistan istället för den överordnade Foundry-resursidentiteten .
• Du angav objekt-ID där App Service-autentisering kräver ett applikations-ID.
• Du lade inte till föräldraresursapplikationens ID i allowedApplications.
• Du lade inte till föräldraobjekt-ID:t i listan över tillåtna identiteter för en konfiguration endast för Foundry.

Inspektera åtkomsttoken-kraven:

• azp ska vara lika med applikations-ID:t för den överordnade Foundry-resursens identitet.
• oid ska vara lika med den föräldrabaserade Foundry-resursidentitetens objekt-ID.

Webbläsaranvändare får HTTP 403 efter inloggning

För en app som stödjer interaktiv inloggning i webbläsaren, kontrollera dessa inställningar:

• Webbappens eget klient-ID förblir i allowedApplications.
• Identitetskravet tillåter vanliga hyresgästanvändare.
• Oautentiserade webbläsarförfrågningar använder HTTP 302 istället för HTTP 401.

Verktyget fungerar anonymt men misslyckas efter att autentisering aktiverats

Uppdatera verktyget från Anonym till Managed identity, ställ in målgruppen till en registrerad Application ID URI och tillåt den moderliga Foundry-resursidentiteten.

Rensa resurser

När du tar bort eller ersätter resurser från detta scenario:

• Ta bort den föräldrabaserade Foundry-resursidentiteten från App Service-autentiseringen när du tar bort eller ersätter Foundry-resursen.
• Ta bort App Service-autentiseringsapplikationen i Microsoft Entra när du permanent tar bort App Service-appen. Detta steg förhindrar också risken för en föräldralös Application ID URI, som beskrevs tidigare.
• Om du använder en användartilldelad identitet och federerad identitetslegitimation för hemlig autentisering av App Service, radera den identiteten och den federerade inloggningsinformationen med appen.

Relaterat innehåll

• Konfigurera din App Service- eller Azure Functions-app så att den använder Microsoft Entra-inloggning
• Integrera AI i dina Azure App Service-program
• Vad är Foundry Agent Service?