OpenAPI-hulpprogramma-aanroepen vanuit Foundry Agent Service beveiligen

Foundry Agent Service kan een App Service OpenAPI-endpoint anoniem aanroepen of met beheerde identiteit. Gebruik beheerde identiteit wanneer App Service-authenticatie het endpoint beschermt.

Dit scenario bevat twee onafhankelijke managed identity-richtingen:

• Wanneer App Service Foundry aanroept, is de aanroeper de door het App Service systeem toegewezen beheerde identiteit. Azure op rollen gebaseerd toegangsbeheer (RBAC) voor de Foundry-resource of het project machtigt de aanroep.
• Wanneer Foundry het App Service OpenAPI-eindpunt aanroept, is de aanroepende entiteit de door het systeem toegewezen beheerde identiteit van de bovenliggende Foundry-resource. App Service authenticatietokenvalidatie en toelaatlijsten autoriseren de oproep.

De App Service-authenticatie Microsoft Entra-applicatie is de beschermde API-bron. Het vervangt geen van beide bij het aanroepen van managed identity.

De volgende tabel vat de identiteiten en toepassingen in dit scenario samen.

Vereiste voorwaarden

• Een App Service-app met OpenAPI-eindpunten. Als u OpenAPI-functionaliteit aan uw app wilt toevoegen, raadpleegt u een van de volgende zelfstudies:

  • Een App Service-app toevoegen als een hulpprogramma in Foundry Agent Service (.NET)
  • Een App Service-app toevoegen als een hulpprogramma in Foundry Agent Service (Java)
  • Een App Service-app toevoegen als een hulpprogramma in Foundry Agent Service (Python)
  • Een App Service-app toevoegen als een hulpprogramma in Foundry Agent Service (Node.js)

• Een Microsoft Foundry-project waarbij je je app toevoegt als een OpenAPI-tool.

Vind de beheerde identiteits-ID's van de hoofd-Foundry-bron

Foundry Agent Service gebruikt de systeem-toegewezen beheerde identiteit van de ouder Foundry-resource wanneer het een OpenAPI-tool aanroept. Voor dit verzoek wordt de beheerde identiteit van het Foundry-project niet gebruikt.

Je hebt twee identifiers nodig voor de ouder-resource-identiteit:

• Application ID (client ID): Verschijnt in de azp-claim van het toegangstoken en wordt gebruikt voor de controle van toegestane clienttoepassingen voor App Service-verificatie.
• Object (principal) ID: Verschijnt in de oid claim van de token en wordt gebruikt wanneer App Service-authenticatie de toegang beperkt tot specifieke identiteiten.

1. Open in het Foundry-portaal je project en selecteer vervolgens Beheren in het bovenste menu.

2. Selecteer de ouderresource in Project details en selecteer vervolgens Open in het Azure-portaal.

3. Selecteer Resource Management>Identity in het linkermenu van de Foundry-resource.

4. Kopieer onder Systeem toegewezen de waarde van object-id (principal) voor later gebruik.

5. Zoek en selecteer Microsoft Entra ID in Azure Portal.

6. Zoek in het zoekvak naar de object-id die u hebt gekopieerd en selecteer deze in de zoekresultaten.

7. Kopieer op de pagina Overzicht de waarde van de toepassings-id.

   De Object ID is hetzelfde als die weergegeven voor de systeem-toegewezen beheerde identiteit. Sla zowel de applicatie-ID als de object-ID op voor het configureren van App Service-authenticatie.

Microsoft Entra-verificatie configureren voor uw app

1. Navigeer in Azure Portal naar uw App Service-app.

2. Selecteer in het linkermenu van uw app Instellingen>Authenticatie, en selecteer vervolgens Identiteitsprovider toevoegen.

3. Selecteer Op de pagina Een id-provider toevoegenMicrosoft als id-provider om een nieuwe app-registratie te maken.

4. Voor Toegang beperken, selecteer Verificatie vereisen.

5. Selecteer onder Aanvullende controles voor clienttoepassingsvereisteaanvragen toestaan uit specifieke clienttoepassingen.

6. Selecteer het potloodpictogram en configureer de toegestane clientapplicaties:

   • Voeg de applicatie-ID toe die je hebt gekopieerd in De beheerde identiteits-ID's van de bovenliggende Foundry-resource zoeken. Deze ID maakt tokens mogelijk die worden aangevraagd door de ouder Foundry-resource-identiteit.
   • Als de app interactieve aanmelding via de browser ondersteunt, voeg dan ook de eigen toepassings-id (client-id) van de Microsoft Entra-toepassing voor App Service-verificatie toe. Deze ID maakt het mogelijk om tokens uit te geven aan de webapplicatie tijdens het aanmelden van de gebruiker. Als je een nieuwe app-registratie aanmaakt, voeg dan deze ID toe nadat je de identiteitsprovider hebt aangemaakt.

7. Identiteitsvereiste configureren:

   • Voor het meest beperkende beleid voor een eindpunt dat alleen door Foundry wordt aangeroepen, selecteer Aanvragen van specifieke identiteiten toestaan. Selecteer het potloodpictogram en voeg de object-ID van de ouder Foundry resource identity toe.
   • Als de app ook interactieve browser-aanmelding ondersteunt, selecteer dan Verzoeken toestaan van elke identiteit zodat tenantgebruikers niet worden geblokkeerd. Deze instelling staat geen anonieme toegang toe. Verzoeken moeten nog steeds een geldig token bevatten van een toegestane clientapplicatie en de geconfigureerde tenant.

8. Voor Tenantvereiste selecteer je Alleen aanvragen van de tenant van de uitgever toestaan. De bovenliggende Foundry-resource-identiteit en alle gebruikers die zich aanmelden, moeten zich in deze tenant bevinden.

9. Configureer niet-geauthenticeerde verzoeken:

   • Als de app alleen API-clients bedient, selecteer dan HTTP 401 Unauthorized: aanbevolen voor API's.
   • Als de app interactieve browser-aanmelding ondersteunt, selecteer dan HTTP 302 Found redirect en selecteer vervolgens Microsoft als redirectprovider.

10. Selecteer Toevoegen om de id-provider te maken.

    De volgende afbeelding toont de smalste configuratie die alleen voor Foundry bestaat.

    

11. Als de app interactieve browser-aanmelding ondersteunt, bewerk dan de provider en zorg dat de Token-opslag is ingeschakeld. Als je een nieuwe appregistratie hebt aangemaakt, voeg dan het applicatie-ID toe aan de toegestane clientapplicaties.

Je hebt beide applicatie-ID's nodig wanneer de app interactieve browser-aanmelding ondersteunt. Een Foundry-only API vereist alleen de applicatie-ID van de ouder Foundry-resource-identiteit.

De Application ID-URI voor de app-registratie bijwerken

Een Application ID URI identificeert de beschermde API als een OAuth-bron. Voor een beheerde identiteit OpenAPI-tool moet de doelgroep exact overeenkomen met een Application ID-URI die geregistreerd is op de App Service authenticatie Microsoft Entra-applicatie. Foundry gebruikt die waarde als doelgroep wanneer het met de identiteit van de bovenliggende Foundry-resource een toegangstoken aanvraagt.

De Application ID en Application ID URI zijn verschillende eigenschappen:

• De applicatie-ID, ook wel de client-ID genoemd, is een gegenereerde GUID.
• Een Application ID URI is een URI die een API of resource identificeert die eigendom is van de applicatie. Het hoeft niet per se de applicatieclient ID te bevatten.

Kies een stabiele Application ID-URI en behandel deze als onderdeel van het API-contract:

De URI moet geldig zijn, uniek voor de huurder en geaccepteerd worden door het Application ID URI-beleid van de huurder. Een gewone tekenreeks zoals 'some-random-string' is geen geldige Application ID URI.

Deze gids gebruikt de volledige HTTPS App Service URL:

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

1. Nadat de configuratie van de Microsoft-provider is voltooid, selecteert u deze in de kolom Id-provider om de pagina voor app-registratie te openen.

2. Selecteer een>API beheren in het linkermenu.

3. Selecteer Bewerken naast de URI van de toepassings-id.

4. Verander de waarde in de volledige HTTPS-URL van je App Service-app, zoals https://<app-name>.azurewebsites.net.

   U vindt de hostnaam van de app op de pagina Overzicht in het standaarddomein.

5. Voor een nieuwe app-registratie zorg ervoor dat de Access-tokenversie is ingesteld op 2.

6. Selecteer Opslaan.

Het wijzigen van de Application ID URI vereist later het bijwerken van het Foundry tool-publiek en alle andere clients die tokens voor de API aanvragen.

De bijbehorende authenticatieconfiguratie van het OpenAPI-instrument is:

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

Je hoeft de tool-doelgroep niet te vermelden onder Toegestane token-doelgroepen. App Service-authenticatie herkent resource-id's die je bij de Microsoft Entra-applicatie registreert. Omgekeerd registreert het toevoegen van een waarde alleen aan Toegestane token-audiences geen OAuth-resource en stelt Microsoft Entra niet in staat een token daarvoor uit te geven.

Gebruik niet het Foundry-projecteindpunt of de client-ID van App Service als doelgroep, tenzij je die exacte waarde ook configureert als de Application ID URI. Andere geldige Application ID URI-formaten, waaronder api:// URI's, werken wanneer de geregistreerde waarde en het publiek exact overeenkomen. Voor gerelateerde randgevallen, zie Veelgestelde vragen.

Configureer de beschermde API declaratief

Gebruik Bicep om de beschermde API en het App Service-authenticatiebeleid te configureren. Het volgende patroon gaat ervan uit:

• webApp is de App Service-bron.
• entraApp is een module die de Microsoft Entra-toepassing voor App Service-authenticatie aanmaakt.
• foundryAccountClientId is de applicatie-ID van de ouder Foundry-resource-identiteit.
• appServiceAuthCredentialSettingName is de naam van de app-instelling die het bestaande Client Secret van de App Service-authenticatie bevat.

In de Microsoft Graph Bicep applicatiemodule configureert u de App Service URL als de identifier-URI en vraagt u om toegangstokens van versie 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

Het volgende authsettingsV2 voorbeeld maakt zowel interactieve browser-aanmelding als Foundry OpenAPI-aanroepen mogelijk:

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

Laat de Foundry resource identity application ID doorgeven via Azure Developer CLI (AZD):

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

Configureer vervolgens de omgeving en herdeploy:

azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
azd provision

Het OpenAPI-hulpprogramma configureren in Microsoft Foundry

1. Selecteer uw agent in het Foundry portal.

2. Zoek het OpenAPI-hulpprogramma en selecteer ...>Bewerken.

3. Controleer of het OpenAPI 3.0+ schema-vakje het schema van je App Service-app bevat. Als dat niet zo is, plak dan je OpenAPI-schema erin. Zie OpenAPI gebruiken met Foundry Agent Service voor meer informatie.

4. Selecteer beheerde identiteit voor verificatiemethode.

5. Voor Audience voer je de Application ID URI in die je eerder hebt geconfigureerd. Voor de configuratie in deze handleiding gebruik je de volledige HTTPS-URL van je App Service-app, zoals https://<app-name>.azurewebsites.net. De waarden moeten exact overeenkomen.

6. Selecteer Het hulpprogramma Bijwerken.

De agent testen

1. Selecteer uw agent in de Foundry-portal en selecteer Uitproberen in speeltuin.

2. Chat met de agent om uw OpenAPI-eindpunten te testen. Voorbeeld:

   • Toon alle taken.
   • Maak een taak met de naam Boodschappen kopen.
   • Werk die taak bij naar "Boodschappen kopen en eten koken."

Als je authenticatie correct configureert, roept de agent de API's van je app aan via de OpenAPI-tool.

Veelgestelde vragen

Waarom kan ik de OpenAPI-tool opslaan voordat ik App Service-autorisatie configureer?

Wanneer je een OpenAPI-tool opslaat, valideert Foundry het schema, het audienceformaat en de definitie. Het roept het App Service-eindpunt niet aan. Je kunt de tool dus opslaan voordat je de ouder Foundry-resourceidentiteit toevoegt aan de App Service-toestemmingslijst.

Configureer de toestaanslijst voordat je de tool aanroept in de playground of tijdens runtime. Tot die tijd weigert App Service tool-aanroepen.

Waarom faalt het standaardpubliek api://<client-id> soms?

Het App Service-portaal maakt vaak een Microsoft Entra-applicatie aan met api://<application-client-id> als applicatie-ID URI. In dat geval kan Foundry dezelfde waarde gebruiken als zijn publiek.

Aangepaste of declaratieve inrichting kan de identifierUris-verzameling van de Microsoft Entra-toepassing leeg laten, zelfs wanneer App Service-verificatie api://<client-id> weergeeft onder Toegestane tokendoelgroepen. In die toestand kan Foundry geen managed identity token voor de waarde verkrijgen omdat het geen geregistreerde resource identifier is.

Om het probleem op te lossen, gebruik je een van deze opties:

• Registreer api://<client-id> als de Application ID URI en gebruik deze als de Foundry-doelgroep.
• Registreer de App Service HTTPS-URL als de Application ID URI en gebruik deze URL als de Foundry audience.

Los de mismatch niet op door willekeurige strings toe te voegen aan allowedAudiences.

Kan App Service-authenticatie werken zonder een Application ID URI?

Interactieve browser-aanmelding kan werken zonder een Application ID-URI omdat de browserflow een ID-token gebruikt voor de client-ID van de webapplicatie.

De OpenAPI-flow van Foundry managed identity heeft een toegangstoken nodig voor een geregistreerde API-resource. Voor deze flow configureer je een Application ID URI en gebruik je dezelfde waarde als de tool audience.

Problemen met authenticatie en autorisatie oplossen

De OpenAPI-tool ontvangt HTTP 401

Een HTTP 401-antwoord betekent dat App Service-authenticatie het verzoek niet kon authenticeren. Waarschijnlijke oorzaken zijn onder andere:

• Je hebt beheerde identiteit niet geselecteerd voor de OpenAPI-tool.
• Het publiek komt niet precies overeen met de Microsoft Entra Application ID URI.
• De tokenuitgever of tenant komt niet overeen met App Service-authenticatie.
• Je hebt de applicatie-ID URI niet geconfigureerd in de Microsoft Entra-applicatie.

Controleer of het OpenAPI-publiek exact overeenkomt met een geregistreerde Application ID URI. Voor de configuratie in deze gids is de waarde de volledige App Service HTTPS URL.

De OpenAPI-tool ontvangt HTTP 403

Een HTTP 403-antwoord betekent dat de authenticatie is geslaagd, maar de autorisatiecontroles hebben de aanroeper afgewezen. Waarschijnlijke oorzaken zijn onder andere:

• Je hebt de identiteit van het Foundry-project toegevoegd aan de toelatingslijst in plaats van de identiteit van de bovenliggende Foundry-resource.
• Je voerde de object-ID in waarbij App Service-authenticatie een applicatie-ID vereist.
• Je hebt de parent resource application ID niet toegevoegd aan allowedApplications.
• Je hebt de parent resource object-ID niet toegevoegd aan de lijst met toegestane identiteit voor een Foundry-only configuratie.

Inspecteer de toegangstokenclaims:

• azp moet gelijk zijn aan de applicatie-ID van de ouder Foundry resource identity.
• oid moet gelijk zijn aan de object-ID van de ouder Foundry resource identity.

Browsergebruikers ontvangen HTTP 403 na het inloggen

Voor een app die interactieve browser-inloggegevens ondersteunt, controleer deze instellingen:

• De eigen client-ID van de webapp blijft in allowedApplications.
• De identiteitsvereiste maakt normale tenantgebruikers mogelijk.
• Niet-geauthenticeerde browserverzoeken gebruiken HTTP 302 in plaats van HTTP 401.

De tool werkt anoniem maar faalt nadat authenticatie is ingeschakeld

Werk de tool bij van Anoniem naar Beheerde identiteit, stel de doelgroep in op een geregistreerde Application ID URI en sta de ouder Foundry resource identiteit toe.

De hulpbronnen opschonen

Wanneer je resources uit dit scenario verwijdert of vervangt:

• Verwijder de ouder-Foundry-resourceidentiteit uit de App Service-authenticatie wanneer je de Foundry-resource verwijdert of vervangt.
• Verwijder de Microsoft Entra-applicatie voor App Service-authenticatie wanneer u de App Service-app permanent verwijdert. Deze stap voorkomt ook het eerder beschreven risico van de verweesde applicatie-ID URI.
• Als je een door de gebruiker toegewezen identiteit en een gefedereerde identiteitsgegevens gebruikt voor geheime App Service-authenticatie, verwijder dan die identiteit en die gefedereerde inloggegevens met de app.

Verwante inhoud

• Uw App Service- of Azure Functions-app configureren voor het gebruik van Microsoft Entra-aanmelding
• AI integreren in uw Azure App Service-toepassingen
• Wat is Foundry Agent Service?