Bezpieczne wywołania narzędzi OpenAPI z usługi agenta Foundry

Foundry Agent Service może wywołać punkt końcowy App Service OpenAPI anonimowo lub za pomocą tożsamości zarządzanej. Używaj zarządzanej tożsamości, gdy uwierzytelnianie App Service chroni punkt końcowy.

Ten scenariusz zawiera dwa niezależne kierunki zarządzanej tożsamości:

• Gdy usługa App Service wywołuje Foundry, obiektem wywołującym jest tożsamość zarządzana przypisana przez system dla usługi App Service. Kontrola dostępu oparta na rolach (RBAC) Azure na zasobach lub projekcie Foundry autoryzuje połączenie.
• Gdy Foundry wywołuje punkt końcowy OpenAPI usługi App Service, podmiotem wywołującym jest tożsamość zarządzana przypisana przez system dla nadrzędnego zasobu Foundry. Uwierzytelnianie usługi App Service, walidacja tokenów oraz listy dozwolonych elementów autoryzują wywołanie.

Aplikacja Microsoft Entra do uwierzytelniania App Service jest chronionym zasobem API. Nie zastępuje ani jednej z tych wywołań zarządzanej tożsamości.

Poniższa tabela podsumowuje tożsamości i aplikacje w tym scenariuszu.

Wymagania wstępne

• Aplikacja App Service z punktami końcowymi interfejsu OpenAPI. Jeśli musisz dodać funkcje interfejsu OpenAPI do aplikacji, zobacz jeden z następujących samouczków:

  • Dodaj aplikację App Service jako narzędzie w Agencie Foundry (.NET)
  • Dodaj aplikację App Service jako narzędzie w Agencie Usługi Foundry (Java)
  • Dodaj aplikację App Service jako narzędzie w Foundry Agent Service (Python)
  • Dodaj aplikację App Service jako narzędzie w usłudze agenta Foundry (Node.js)

• Projekt Microsoft Foundry, w którym dodajesz swoją aplikację jako narzędzie OpenAPI.

Znajdź zarządzane identyfikatory tożsamości nadrzędnego zasobu Foundry

Foundry Agent Service wykorzystuje systemowo przypisaną zarządzaną tożsamość nadrzędnego zasobu Foundry podczas wywoływania narzędzia OpenAPI. Nie jest używana zarządzana tożsamość projektu Foundry na potrzeby tego żądania.

Potrzebujesz dwóch identyfikatorów na potrzeby tożsamości zasobu nadrzędnego:

• ID aplikacji (identyfikator klienta): Pojawia się w roszczeniu azp tokenu dostępu i jest używany do sprawdzania, czy aplikacja kliencka jest dozwolona na potrzeby uwierzytelniania usługi App Service.
• ID obiektu (głównego): Pojawia się w roszczeniu oid tokena i jest używana, gdy uwierzytelnianie App Service ogranicza dostęp do określonych tożsamości.

1. W portalu Foundry otwórz swój projekt, a następnie wybierz Zarządzaj w górnym menu.

2. Wybierz zasób nadrzędny w Szczegóły projektu, a następnie wybierz Otwórz w portalu Azure.

3. W menu po lewej stronie zasobu Foundry wybierz pozycję Zarządzanie zasobami>Tożsamość.

4. W obszarze Przypisany system skopiuj wartość identyfikatora obiektu (podmiotu zabezpieczeń) do późniejszego użycia.

5. W witrynie Azure Portal wyszukaj i wybierz pozycję Microsoft Entra ID.

6. W polu wyszukiwania wyszukaj skopiowany identyfikator obiektu i wybierz go w wynikach wyszukiwania.

7. Na stronie Przegląd skopiuj wartość identyfikatora aplikacji.

   Identyfikator obiektu jest taki sam jak ten wyświetlany dla systemowej tożsamości zarządzanej. Zapisz zarówno identyfikator aplikacji, jak i identyfikator obiektu do konfiguracji uwierzytelniania App Service.

Skonfiguruj uwierzytelnianie w usłudze Microsoft Entra dla swojej aplikacji

1. W witrynie Azure Portal przejdź do aplikacji usługi App Service.

2. W menu po lewej stronie aplikacji wybierz pozycję Ustawienia>Uwierzytelnianie, a następnie wybierz pozycję Dodaj dostawcę tożsamości.

3. Na stronie Dodawanie dostawcy tożsamości wybierz pozycję Microsoft jako dostawca tożsamości , aby utworzyć nową rejestrację aplikacji.

4. W obszarze Ogranicz dostęp wybierz pozycję Wymagaj uwierzytelniania.

5. W obszarze Dodatkowe kontrole w obszarze Wymaganie aplikacji klienckiej wybierz pozycję Zezwalaj na żądania z określonych aplikacji klienckich.

6. Wybierz ikonę ołówka i skonfiguruj dozwolone aplikacje klienckie:

   • Dodaj identyfikator aplikacji , który skopiowałeś w sekcji Znajdź zarządzane identyfikatory zasobu Foundry nadrzędnego. Ten identyfikator pozwala na tokeny żądane przez nadrzędną tożsamość zasobu Foundry.
   • Jeśli aplikacja obsługuje interaktywne logowanie do przeglądarki, dodaj także własny identyfikator aplikacji (klienta) aplikacji Microsoft Entra w uwierzytelnianiu. Ten identyfikator umożliwia wydawanie tokenów aplikacji internetowej podczas logowania użytkownika. Jeśli tworzysz nową rejestrację aplikacji, dodaj ten identyfikator po utworzeniu dostawcy tożsamości.

7. Konfiguruj wymóg tożsamości:

   • Aby ustawić najbardziej restrykcyjne zasady dla punktu końcowego wywoływanego wyłącznie przez Foundry, wybierz Zezwalaj na żądania tylko od określonych tożsamości. Wybierz ikonę ołówka i dodaj identyfikator obiektu nadrzędnej tożsamości zasobów Foundry.
   • Jeśli aplikacja obsługuje także interaktywne logowanie do przeglądarki, wybierz Zezwalaj na żądania z dowolnej tożsamości , aby użytkownicy tenantów nie byli blokowani. To ustawienie nie pozwala na anonimowy dostęp. Żądania muszą nadal zawierać ważny token z dozwolonej aplikacji klienckiej oraz skonfigurowanego tenanta.

8. Aby uzyskać wymóg Najemcy, wybierz Zezwalaj na żądania tylko od najemcy emitenta. Nadrzędna tożsamość zasobu Foundry oraz wszyscy użytkownicy logujący się muszą znajdować w tym dzierżawie.

9. Konfiguruj nieuwierzytelnione żądania:

   • Jeśli aplikacja obsługuje wyłącznie klientów API, wybierz HTTP 401 Nieautoryzowane: zalecane dla API.
   • Jeśli aplikacja obsługuje interaktywne logowanie w przeglądarce, wybierz HTTP 302 Found redirect, a następnie wybierz Microsoft jako dostawcę przekierowań.

10. Wybierz Dodaj, aby utworzyć dostawcę tożsamości.

    Poniższa ilustracja przedstawia najbardziej ograniczoną konfigurację dostępną wyłącznie w wersji Foundry.

    

11. Jeśli aplikacja obsługuje interaktywne logowanie do przeglądarki, edytuj dostawcę i upewnij się, że sklep Token jest włączony. Jeśli utworzyłeś nową rejestrację aplikacji, dodaj jej identyfikator aplikacji do dozwolonych aplikacji klienckich.

Potrzebujesz obu identyfikatorów aplikacji, gdy aplikacja obsługuje interaktywne logowanie do przeglądarki. API dostępne wyłącznie w Foundry wymaga jedynie identyfikatora aplikacji nadrzędnej tożsamości zasobów Foundry.

Aktualizowanie URI identyfikatora aplikacji podczas rejestracji

URI ID aplikacji identyfikuje chronione API jako zasób OAuth. Aby uzyskać narzędzie OpenAPI do zarządzania tożsamością, odbiorca musi dokładnie odpowiadać identyfikatorowi aplikacji URI zarejestrowanemu w aplikacji Microsoft Entra do uwierzytelniania App Service. Foundry używa tej wartości jako parametru audience, gdy żąda tokenu dostępu przy użyciu tożsamości nadrzędnego zasobu Foundry.

Identyfikator aplikacji i URI identyfikatora aplikacji to różne właściwości:

• Identyfikator aplikacji, zwany także identyfikatorem klienta, jest wygenerowanym identyfikatorem GUID.
• URI ID aplikacji to URI identyfikujące API lub zasób należący do aplikacji. Nie musi zawierać identyfikatora klienta aplikacji.

Wybierz stabilny identyfikator ID aplikacji (URI) i traktuj go jako część kontraktu API:

Identyfikator URI musi być prawidłowy, unikalny w obrębie dzierżawy i zgodny z zasadami identyfikatora URI aplikacji obowiązującymi w tej dzierżawie. Zwykły ciąg znaków, taki jak some-random-string, nie jest prawidłowym URI identyfikatora aplikacji.

Ten przewodnik wykorzystuje pełny adres URL HTTPS App Service:

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

1. Po zakończeniu konfiguracji dostawcy firmy Microsoft wybierz ją w kolumnie Dostawca tożsamości , aby otworzyć stronę rejestracji aplikacji.

2. W menu po lewej stronie wybierz pozycję Zarządzaj>uwidaczniaj interfejs API.

3. Obok URI identyfikatora aplikacji wybierz pozycję Edytuj.

4. Zmień wartość na pełny adres URL HTTPS aplikacji App Service, na przykład .https://<app-name>.azurewebsites.net

   Nazwę hosta aplikacji można znaleźć na stronie Przegląd w domenie domyślnej.

5. Przy rejestracji nowej aplikacji upewnij się, że wersja tokena Access jest ustawiona na 2.

6. Wybierz Zapisz.

Zmiana ID ID aplikacji wymaga późniejszej aktualizacji grupy odbiorców narzędzi Foundry oraz każdego innego klienta, który prosi o tokeny dla API.

Odpowiednia konfiguracja uwierzytelniania narzędzi OpenAPI to:

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

Nie musisz wpisywać odbiorców narzędzi w kategorii Dozwolone grupy tokenów. Uwierzytelnianie App Service rozpoznaje identyfikatory zasobów, które rejestrujesz w aplikacji Microsoft Entra. Z kolei dodanie wartości tylko do Dozwoleni odbiorcy tokenów nie rejestruje zasobu OAuth ani nie umożliwia platformie Microsoft Entra wydania tokena dla tego zasobu.

Nie używaj punktu końcowego projektu Foundry ani identyfikatora klienta usługi App Service jako wartości audience, chyba że skonfigurujesz tę dokładną wartość również jako URI identyfikatora aplikacji. Inne prawidłowe formaty identyfikatora URI aplikacji, w tym identyfikatory URI api://, działają, gdy zarejestrowana wartość i odbiorca są dokładnie zgodne. Informacje o powiązanych przypadkach brzegowych znajdziesz w sekcji Najczęściej zadawane pytania.

Konfiguruj chronione API deklaratywnie

Użyj Bicep do skonfigurowania chronionego API oraz polityki uwierzytelniania App Service. Następujący wzorzec zakłada:

• webApp jest zasobem usługi App Service.
• entraApp to moduł, który tworzy aplikację Microsoft Entra na potrzeby uwierzytelniania usługi App Service.
• foundryAccountClientId to identyfikator aplikacji nadrzędnej tożsamości zasobów Foundry.
• appServiceAuthCredentialSettingName to nazwa ustawienia aplikacji, które zawiera istniejący sekret klienta uwierzytelniania App Service.

W module aplikacji Microsoft Graph Bicep konfiguruj adres URL App Service jako identyfikator URI i zażądaj tokenów dostępu wersji 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

Poniższy authsettingsV2 przykład pozwala zarówno na interaktywne logowanie do przeglądarki, jak i wywołania Foundry OpenAPI:

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

Przekaż identyfikator aplikacji tożsamości zasobu Foundry za pośrednictwem interfejsu wiersza polecenia Azure Developer CLI (AZD):

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

Następnie skonfiguruj środowisko i wdroż ponownie:

azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
azd provision

Konfigurowanie narzędzia OpenAPI w rozwiązaniu Microsoft Foundry

1. Po powrocie do portalu Foundry wybierz agenta.

2. Znajdź narzędzie OpenAPI i wybierz pozycję ...>Edytuj.

3. Sprawdź, czy pole schematu OpenAPI 3.0+ zawiera schemat z Twojej aplikacji App Service. Jeśli nie, wklej schemat OpenAPI. Aby uzyskać więcej informacji, zobacz How to use OpenAPI with Foundry Agent Service (Jak używać interfejsu OpenAPI z usługą agenta rozwiązania Foundry).

4. W polu Metoda uwierzytelniania wybierz pozycję Tożsamość zarządzana.

5. W polu Odbiorcy wprowadź URI identyfikatora aplikacji, które skonfigurowano wcześniej. Do konfiguracji opisanej w tym przewodniku użyj pełnego adresu URL HTTPS dla swojej aplikacji App Service, na przykład .https://<app-name>.azurewebsites.net Wartości muszą się dokładnie pokrywać.

6. Wybierz pozycję Aktualizuj narzędzie.

Przetestuj agenta

1. W portalu Foundry wybierz agenta i wybierz pozycję Wypróbuj na placu zabaw.

2. Porozmawiaj z agentem, aby przetestować punkty końcowe interfejsu OpenAPI. Przykład:

   • Pokaż mi wszystkie zadania.
   • Utwórz zadanie o nazwie "Kup artykuły spożywcze".
   • Zaktualizuj to zadanie, aby "Kupować artykuły spożywcze i gotować kolację".

Jeśli poprawnie skonfigurujesz uwierzytelnianie, agent wywołuje API Twojej aplikacji za pomocą narzędzia OpenAPI.

Często zadawane pytania

Dlaczego mogę zapisać narzędzie OpenAPI przed skonfigurowaniem autoryzacji App Service?

Gdy zapisujesz narzędzie OpenAPI, Foundry weryfikuje jego schemat, format odbiorców i definicję. Nie wywołuje endpointu App Service. Możesz więc zapisać narzędzie przed dodaniem tożsamości zasobu nadrzędnego Foundry do listy dozwolonych w App Service.

Skonfiguruj listę dozwolonych elementów przed wywołaniem narzędzia w środowisku testowym lub w czasie wykonywania. Do tego czasu App Service odrzuca wywołania narzędzi.

Dlaczego domyślna api://<client-id> publiczność czasem zawodzi?

Portal usługi App Service często tworzy aplikację Microsoft Entra z identyfikatorem URI aplikacji api://<application-client-id>. W takim przypadku Foundry może użyć tej samej wartości co jego odbiorcy.

Niestandardowe lub deklaratywne udostępnianie może pozostawić kolekcję identifierUris aplikacji Microsoft Entra pustą, nawet gdy uwierzytelnianie App Service wyświetla api://<client-id> się w grupie Dozwolone grupy odbiorców tokenów. W tym stanie Foundry nie może uzyskać zarządzanego tokena tożsamości dla tej wartości, ponieważ nie jest to zarejestrowany identyfikator zasobu.

Aby rozwiązać problem, użyj jednej z tych opcji:

• Zarejestruj api://<client-id> jako identyfikator URI aplikacji i użyj go jako odbiorcy dla Foundry.
• Zarejestruj adres URL HTTPS usługi App Service jako identyfikator URI aplikacji i użyj tego adresu URL jako odbiorcy dla usługi Foundry.

Nie naprawiaj rozbieżności, dodając dowolne ciągi do allowedAudiences.

Czy uwierzytelnianie usługi App Service może działać bez identyfikatora URI aplikacji?

Interaktywne logowanie do przeglądarki może działać bez URI ID aplikacji, ponieważ przepływ przeglądarki wykorzystuje token ID jako identyfikator klienta aplikacji webowej.

Przepływ zarządzanej tożsamości OpenAPI w Foundry wymaga tokena dostępu dla zarejestrowanego zasobu API. Dla tego przepływu konfiguruj ID aplikacji URI i używaj tej samej wartości co odbiorca narzędzi.

Rozwiązywanie problemów z uwierzytelnianiem i autoryzacją

Narzędzie OpenAPI otrzymuje HTTP 401

Odpowiedź HTTP 401 oznacza, że uwierzytelnianie App Service nie mogło uwierzytelnić żądania. Prawdopodobne przyczyny to:

• Nie wybrałeś zarządzanej tożsamości dla narzędzia OpenAPI.
• Wartość „aud” nie jest dokładnie zgodna z identyfikatorem URI aplikacji w Microsoft Entra.
• Emitent tokenów lub dzierżawca nie odpowiada uwierzytelnianiu App Service.
• Nie konfigurowałeś URI ID aplikacji w aplikacji Microsoft Entra.

Sprawdź, czy odbiorcy OpenAPI dokładnie odpowiadają zarejestrowanemu ID aplikacji URI. W konfiguracji opisanej w tym przewodniku wartość to pełny adres URL App Service HTTPS.

Narzędzie OpenAPI otrzymuje HTTP 403

Odpowiedź HTTP 403 oznacza, że uwierzytelnienie zakończyło się sukcesem, ale testy autoryzacji odrzuciły dzwoniącego. Prawdopodobne przyczyny to:

• Dodałeś tożsamość projektu Foundry do listy zezwoleń zamiast tożsamości zasobu nadrzędnego Foundry.
• Wprowadziłeś identyfikator obiektu, gdzie uwierzytelnianie App Service wymaga ID aplikacji.
• Nie dodałeś identyfikatora aplikacji nadrzędnego zasobu do allowedApplications.
• Nie dodałeś identyfikatora obiektu zasobu nadrzędnego do listy dozwolonych tożsamości w konfiguracji przeznaczonej wyłącznie dla Foundry.

Sprawdź roszczenia dotyczące tokenów dostępu:

• azp powinien być równy identyfikatorowi aplikacji nadrzędnej tożsamości zasobów Foundry.
• oid powinien być równy identyfikatorowi obiektu tożsamości zasobu nadrzędnego Foundry.

Użytkownicy przeglądarki otrzymują HTTP 403 po zalogowaniu

Aby uzyskać aplikację wspierającą interaktywne logowanie do przeglądarki, sprawdź następujące ustawienia:

• Własny identyfikator klienta aplikacji internetowej pozostaje w allowedApplications.
• Wymóg dotyczący tożsamości dopuszcza zwykłych użytkowników dzierżawy.
• Nieuwierzytelnione żądania przeglądarki używają kodu HTTP 302 zamiast kodu HTTP 401.

Narzędzie działa anonimowo, ale nie działa po włączeniu uwierzytelnienia

Zaktualizuj narzędzie z Anonimowy na Tożsamość zarządzana, ustaw wartość odbiorcy na zarejestrowany identyfikator URI aplikacji i zezwól na tożsamość nadrzędnego zasobu Foundry.

Uprzątnij zasoby

Kiedy usuwasz lub zastępujesz zasoby z tego scenariusza:

• Usuń nadrzędną tożsamość zasobu Foundry z uwierzytelniania w usłudze App Service po usunięciu lub zastąpieniu zasobu Foundry.
• Usuń aplikację Microsoft Entra używaną do uwierzytelniania w usłudze App Service, gdy trwale usuwasz aplikację App Service. Ten krok zapobiega również opisanemu wcześniej ryzyku osierocenia URI identyfikatora aplikacji.
• Jeśli używasz tożsamości przypisanej przez użytkownika oraz federowanego poświadczenia tożsamości do uwierzytelniania bez tajemnicy App Service, usuń tę tożsamość i federowane dane uwierzytelniające w aplikacji.

Treści powiązane

• Konfigurowanie aplikacji App Service lub Azure Functions do korzystania z logowania w usłudze Microsoft Entra
• Integrowanie sztucznej inteligencji z aplikacjami usługi Azure App Service
• Co to jest usługa agenta programu Foundry?