Udostępnij przez

Uwierzytelnianie i autoryzacja w rozwiązaniu Microsoft Foundry

Uwierzytelnianie i autoryzacja w systemie Microsoft Foundry zarządza sposobem, w jaki podmioty potwierdzają tożsamość i uzyskują uprawnienia do wykonywania operacji. Funkcja Foundry dzieli operacje na płaszczyznę sterowania (zarządzanie zasobami) i płaszczyznę danych (użycie środowiska uruchomieniowego), z których każda ma własną powierzchnię uwierzytelniania i kontroli dostępu opartej na rolach (RBAC).

Narzędzie Foundry obsługuje dwie metody uwierzytelniania: Identyfikator Entra firmy Microsoft i klucze interfejsu API. Microsoft Entra ID umożliwia dostęp warunkowy, zarządzane tożsamości oraz szczegółową kontrolę dostępu opartą na rolach (RBAC). Klucze interfejsu API pozostają dostępne do szybkiego tworzenia prototypów, ale nie mają możliwości śledzenia poszczególnych użytkowników. W tym artykule porównuje te metody, odnosi tożsamości do ról i opisuje typowe scenariusze najmniejszych uprawnień.

Ważna

Użyj Microsoft Entra ID dla obciążeń produkcyjnych, aby włączyć dostęp warunkowy, tożsamości zarządzane oraz kontrolę dostępu opartą na rolach z jak najmniejszymi uprawnieniami. Klucze interfejsu API są wygodne do szybkiej oceny, ale zapewniają gruboziarnisty dostęp.

Wymagania wstępne

Płaszczyzna sterowania i płaszczyzna danych

Operacje platformy Azure dzielą się na dwie kategorie: płaszczyznę sterowania i płaszczyznę danych. Platforma Azure oddziela zarządzanie zasobami (płaszczyznę sterowania) od środowiska uruchomieniowego operacyjnego (płaszczyzny danych). W związku z tym płaszczyzna sterowania jest używana do zarządzania zasobami w ramach subskrypcji, a płaszczyzna danych służy do korzystania z możliwości udostępnianych przez uruchomioną instancję typu zasobu. Aby dowiedzieć się więcej na temat płaszczyzny sterowania i płaszczyzny danych, zobacz Płaszczyzna sterowania i płaszczyzna danych platformy Azure. W rozwiązaniu Foundry istnieje wyraźne rozróżnienie między operacjami płaszczyzny sterowania a operacjami płaszczyzny danych. W poniższej tabeli opisano różnicę między tymi dwoma, zakres w Foundry, typowe operacje użytkownika, przykładowe narzędzia i funkcje oraz obszar autoryzacji do użycia każdego.

Samolot Zakres w narzędziu Foundry Typowe operacje Przykładowe narzędzia Powierzchnia autoryzacji
Płaszczyzna sterowania Ustawianie i konfigurowanie zasobów, projektów, sieci, szyfrowania i połączeń Tworzenie lub usuwanie zasobów, przypisywanie ról, obracanie kluczy, konfigurowanie usługi Private Link Witryna Azure Portal, interfejs wiersza polecenia platformy Azure, szablony usługi ARM, Bicep, Terraform Akcje RBAC platformy Azure
Płaszczyzna danych Uruchamianie i używanie wnioskowania przy użyciu modelu, interakcji z agentem, zadań oceny i wywołań związanych z bezpieczeństwem treści Uzupełnianie czatów, generowanie osadzania, uruchamianie zadań dostrajania, wysyłanie komunikatów agenta, operacje analizatora i klasyfikatora Zestawy SDK, interfejsy API REST, plac zabaw portalu Foundry Azure RBAC dataActions

Wszystkie przykłady Bicep, Terraform i SDK można znaleźć w repozytorium foundry-samples w witrynie GitHub for Foundry.

Na poniższych listach i diagramie przedstawiono szczegółowe rozdzielenie między płaszczyzną sterowania a akcjami płaszczyzny danych. Akcje płaszczyzny sterowania w programie Foundry obejmują:

  • Tworzenie zasobu usługi Foundry
  • Tworzenie projektu odlewni
  • Tworzenie hosta możliwości konta
  • Tworzenie hosta kompetencji projektu
  • Wdrożenie modelu
  • Tworzenie połączenia konta i projektu

Akcje płaszczyzny danych w narzędziu Foundry obejmują:

  • Tworzenie agentów
  • Uruchamianie oceny
  • Śledzenie i monitorowanie
  • Precyzyjne dostosowanie

Na poniższym diagramie przedstawiono widok separacji płaszczyzny sterowania od płaszczyzny danych w systemie Foundry wraz z przypisaniami kontroli dostępu opartej na rolach (RBAC) oraz rodzajami dostępu, jakie użytkownik może mieć: do płaszczyzny sterowania, płaszczyzny danych lub obu jednocześnie. Jak pokazano na diagramie, RBAC "actions" są skojarzone z płaszczyzną sterowania, podczas gdy RBAC "dataActions" są skojarzone z płaszczyzną danych.

Diagram ilustrujący separację operacji płaszczyzny sterowania i płaszczyzny danych ze skojarzonymi powierzchniami RBAC.

Metody uwierzytelniania

Narzędzie Foundry obsługuje Microsoft Entra ID (oparte na tokenach, bezkluczowe) i klucze API.

Microsoft Entra ID

Microsoft Entra ID używa tokenów typu bearer OAuth 2.0 o zakresie do https://cognitiveservices.azure.com/.default.

Użyj identyfikatora Entra firmy Microsoft dla:

  • Obciążenia produkcyjne.
  • Dostęp warunkowy, uwierzytelnianie wieloskładnikowe (MFA) i dostęp just in time.
  • Kontrola dostępu oparta na rolach zgodnie z zasadą najmniejszych uprawnień oraz integracja z zarządzaną tożsamością.

Zalety: szczegółowe przypisania ról, audytowanie poszczególnych podmiotów, kontrolowane okresy istnienia tokenu, automatyczna higiena tajemnic i zarządzane tożsamości usług.

Ograniczenia: wyższa złożoność konfiguracji początkowej. Wymaga zrozumienia kontroli dostępu opartej na rolach (RBAC). Aby uzyskać więcej informacji na temat kontroli dostępu opartej na rolach w rozwiązaniu Foundry, zobacz Kontrola dostępu oparta na rolach dla rozwiązania Microsoft Foundry.

Klucze interfejsu API

Klucze interfejsu API to statyczne tajemnice powiązane z zasobem Foundry.

Użyj kluczy interfejsu API dla:

  • Szybkie tworzenie prototypów.
  • Izolowane środowiska testowe, w których dopuszczalna jest rotacja pojedynczego sekretu.

Zalety: proste, niezależne od języka i nie wymagają pozyskiwania tokenów.

Ograniczenia: Nie można wyrazić tożsamości użytkownika, trudno jest dokładnie określić zakres i jest trudniejsze do audytu. Ogólnie nie są akceptowane przez obciążenia produkcyjne przedsiębiorstwa i nie są zalecane przez firmę Microsoft.

Aby uzyskać więcej informacji na temat włączania uwierzytelniania bez klucza, zobacz Konfigurowanie uwierzytelniania bez klucza przy użyciu identyfikatora Entra firmy Microsoft.

Uwierzytelnianie przy użyciu identyfikatora Entra firmy Microsoft (Python)

W poniższym przykładzie pokazano, jak uwierzytelnić się za pomocą Microsoft Entra ID, używając biblioteki azure-identity i wysłać żądanie do punktu końcowego Foundry:

from azure.identity import DefaultAzureCredential
import requests

# Create a credential object using DefaultAzureCredential
# This automatically uses environment variables, managed identity, or Azure CLI credentials
credential = DefaultAzureCredential()

# Get an access token for the Cognitive Services scope
token = credential.get_token("https://cognitiveservices.azure.com/.default")

# Use the token in your API request
headers = {
    "Authorization": f"Bearer {token.token}",
    "Content-Type": "application/json"
}

# Replace with your Foundry endpoint
endpoint = "https://<your-resource-name>.cognitiveservices.azure.com"

# Example: List deployments (adjust the path for your specific API)
response = requests.get(f"{endpoint}/openai/deployments?api-version=2024-10-21", headers=headers)
print(response.json())

Oczekiwane dane wyjściowe: odpowiedź JSON z listą wdrożeń modelu lub błąd uwierzytelniania, jeśli brakuje poświadczeń lub przypisanie roli nie jest skonfigurowane.

Dokumentacja: DefaultAzureCredential | azure-identity library

Uwierzytelnianie przy użyciu klucza interfejsu API (Python)

W poniższym przykładzie pokazano, jak uwierzytelniać się przy użyciu klucza interfejsu API. Użyj tego podejścia tylko do szybkiego tworzenia prototypów; Identyfikator Entra firmy Microsoft jest zalecany w środowisku produkcyjnym.

import requests

# Replace with your actual API key and endpoint
api_key = "<your-api-key>"
endpoint = "https://<your-resource-name>.cognitiveservices.azure.com"

headers = {
    "api-key": api_key,
    "Content-Type": "application/json"
}

# Example: List deployments
response = requests.get(f"{endpoint}/openai/deployments?api-version=2024-10-21", headers=headers)
print(response.json())

Ostrzeżenie

Klucze interfejsu API zapewniają pełny dostęp do zasobu i nie mogą być ograniczone do określonych użytkowników ani akcji. Regularnie wykonuj rotację kluczy i unikaj umieszczania ich w systemie kontroli wersji.

Oczekiwane dane wyjściowe: odpowiedź JSON z listą wdrożeń modelu lub błąd 401, jeśli klucz interfejsu API jest nieprawidłowy.

Dokumentacja: Zmiana kluczy dostępu interfejsu API

Macierz obsługi funkcji

Zapoznaj się z poniższą macierzą, aby zrozumieć, jakie możliwości w Foundry są obsługiwane przez klucz API w porównaniu z identyfikatorem Microsoft Entra.

Możliwość lub funkcja klucz interfejsu API Microsoft Entra ID Notatki
Podstawowe wnioskowanie modelu (czat, osadzanie) Tak Tak W pełni obsługiwane.
Operacje dostrajania Tak Tak Entra ID dodaje audyt dla każdego podmiotu.
Usługa agentów Nie. Tak Użyj identyfikatora Entra na potrzeby dostępu do narzędzia tożsamości zarządzanej.
Evaluations Nie. Tak Użyj identyfikatora Entra.
Analiza wywołań dotyczących bezpieczeństwa treści Tak Tak Aby ograniczyć operacje wysokiego ryzyka, użyj RBAC (kontroli dostępu opartej na rolach).
Zadania analizy wsadowej (Rozumienie Treści) Tak Tak Identyfikator entra zalecany do skalowania.
Użycie placu zabaw w portalu Tak Tak Plac zabaw korzysta z trybu połączenia z projektem.
Izolacja sieci za pomocą usługi Private Link Tak Tak Identyfikator entra dodaje dostęp warunkowy.
Zasada najmniejszych uprawnień dzięki wbudowanym i niestandardowym rolom Nie. Tak Klucze dla każdego zasobu działają na zasadzie wszystko albo nic.
Tożsamość zarządzana (system lub przypisana przez użytkownika) Nie. Tak Umożliwia uwierzytelnianie bez sekretów.
Przypisanie użytkownika na żądanie Nie. Tak Token zawiera identyfikatory dzierżawcy i obiektów.
Odwołanie (natychmiastowe) Obracanie klucza Usuwanie roli lub dezaktywacja głównego podmiotu Stosuje się krótki okres istnienia tokenu.
Obsługa potoków automatyzacji Tak (wpis tajny) Tak (główny użytkownik usługi lub tożsamość zarządzana) Entra ID zmniejsza obrót sekretów.
Interfejs API asystentów Tak Tak Zaleca się użycie Entra ID.
Wnioskowanie wsadowe Tak Tak

Typy tożsamości

Zasoby i aplikacje platformy Azure są uwierzytelniane przy użyciu różnych typów tożsamości, z których każda jest przeznaczona dla określonych scenariuszy. Podmioty użytkowników reprezentują użytkowników ludzkich, podmioty usługowe reprezentują aplikacje lub zautomatyzowane procesy, a tożsamości zarządzane zapewniają bezpieczny sposób na dostęp do innych usług przez zasoby Azure bez konieczności zarządzania poświadczeniami. Zrozumienie tych różnic pomaga wybrać odpowiednią tożsamość na potrzeby logowania interakcyjnego, komunikacji między aplikacjami lub automatyzacji obciążeń.

Platforma Azure obsługuje następujące typy tożsamości.

Typ tożsamości Opis
Podmiot główny użytkownika Indywidualny użytkownik w identyfikatorze Entra firmy Microsoft
Jednostka usługi (rejestracja aplikacji) Tożsamość aplikacji korzystająca z klucza tajnego klienta lub certyfikatu
Tożsamość zarządzana (przypisana przez system) Tożsamość powiązana z zasobami platformy Azure jest automatycznie zarządzana przez platformę.
Tożsamość zarządzana (przypisana przez użytkownika) Niezależna tożsamość połączona z wieloma zasobami.

Omówienie ról wbudowanych

W narzędziu Foundry użyj wbudowanych ról, aby oddzielić dozwolone akcje dla użytkownika. Większość przedsiębiorstw chce rozdzielić płaszczyzny sterowania i danych dla swoich wbudowanych ról. Inni oczekują, że połączona rola płaszczyzny danych i płaszczyzny sterowania minimalizuje wymaganą liczbę przypisań ról. W poniższej tabeli wymieniono scenariusze i odpowiednie wbudowane role usługi Foundry, które najlepiej pasują do każdego scenariusza.

Scenariusz Typowe role wbudowane Notatki
Kompilowanie agentów przy użyciu wstępnie wdrożonych modeli Użytkownik sztucznej inteligencji platformy Azure Tylko użycie płaszczyzny danych; brak zapisów zarządzania.
Zarządzanie wdrożeniami lub dostosowywanie modeli Menedżer projektów sztucznej inteligencji platformy Azure Obejmuje tworzenie oraz aktualizację procesu wdrażania modelu.
Obracanie kluczy lub zarządzanie zasobem Właściciel konta usługi Azure AI Wysokie uprawnienia; rozważ niestandardową rolę, aby zapewnić najmniejsze możliwe uprawnienia.
Zarządzanie zasobami, zarządzanie wdrożeniami, tworzenie agentów Właściciel sztucznej inteligencji platformy Azure Wysoce uprzywilejowana rola samoobsługowa dla użytkowników, którzy potrzebują dostępu zarówno płaszczyzny sterowania, jak i płaszczyzny danych. Połącz z czytnikiem usługi Azure Monitor, jeśli jest to wymagane.
Możliwość obserwowania, śledzenie, monitorowanie Użytkownik Azure AI (minimum) Dodaj czytnik usługi Azure Monitor w usłudze Application Insights.

Aby zrozumieć podział wbudowanych ról i akcji płaszczyzny sterowania i płaszczyzny danych, zapoznaj się z poniższym diagramem.

Diagram mapujący wbudowane role do akcji płaszczyzny sterowania i akcji płaszczyzny danych w narzędziu Foundry.

Wskazówka

Utwórz rolę niestandardową, jeśli wbudowana rola przyznaje nadmiarowe uprawnienia dla twojego przypadku użycia.

Konfigurowanie Microsoft Entra ID

Aby uzyskać ogólne wskazówki dotyczące konfigurowania uwierzytelniania entra ID w narzędziu Foundry, zobacz Konfigurowanie uwierzytelniania bez klucza.

  1. Upewnij się, że zasób rozwiązania Microsoft Foundry ma skonfigurowaną niestandardową poddomenę. Zobacz Niestandardowe poddomeny. Niestandardowa poddomena jest wymagana do uwierzytelniania opartego na tokenach.

  2. Przypisz wymaganą wbudowaną lub niestandardową rolę do każdego podmiotu. Aby przypisać role, musisz mieć rolę Właściciela lub Administratora dostępu użytkownika w zakresie docelowym. Typowe przypisania ról:

    • Użytkownik sztucznej inteligencji platformy Azure: dla deweloperów, którzy muszą kompilować i testować przy użyciu wstępnie wdrożonych modeli.
    • Menedżer projektu usługi Azure AI: w przypadku liderów zespołu, którzy muszą tworzyć projekty i zarządzać wdrożeniami.
    • Właściciel konta usługi Azure AI: dla administratorów, którzy potrzebują pełnego zarządzania zasobami i mogą warunkowo przypisać użytkownika usługi Azure AI na potrzeby dostępu do płaszczyzny danych.
    • Właściciel AI platformy Azure: dla użytkowników potrzebujących pełnego zarządzania zasobami i dostępem do płaszczyzny danych. Przykładowe polecenie CLI do przypisywania roli użytkownika usługi Azure AI:
    az role assignment create \
  --assignee <principal-id> \
  --role "Azure AI User" \
  --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource-name>

    Aby sprawdzić przypisanie roli, uruchom az role assignment list --assignee <principal-id> --scope <resource-scope> i potwierdź, że rola jest wyświetlana w wynikach.

  3. (Opcjonalnie) W przypadku jednostki usługi utwórz rejestrację aplikacji, dodaj klucz tajny klienta lub certyfikat i zanotuj identyfikator dzierżawy, identyfikator klienta i klucz tajny lub certyfikat.

  4. (Opcjonalnie) W przypadku tożsamości zarządzanej włącz tożsamość przypisaną przez system w usłudze wywołującej lub dołącz tożsamość przypisaną przez użytkownika, a następnie przypisz do niej rolę w zasobie Foundry.

  5. Usuń uwierzytelnianie oparte na kluczach po tym, jak wszyscy dzwoniący będą używać uwierzytelniania za pomocą tokena. Opcjonalnie wyłącz uwierzytelnianie lokalne w szablonach wdrażania.

Dokumentacja: Przypisywanie kontrolidostępu opartej na rolach | platformy Azuredla rozwiązania Foundry

Rozwiązywanie typowych błędów uwierzytelniania

Error Przyczyna Rezolucja
401 Brak autoryzacji Brak lub wygasły token; nieprawidłowy klucz interfejsu API Sprawdź, czy zakres pozyskiwania tokenu to https://cognitiveservices.azure.com/.default. Wygeneruj ponownie klucz interfejsu API, jeśli używasz uwierzytelniania opartego na kluczach.
403 Zabronione Brak przypisania roli RBAC Przypisz odpowiednią wbudowaną rolę (na przykład użytkownika sztucznej inteligencji platformy Azure) w zakresie zasobu lub projektu.
AADSTS700016 Nie można odnaleźć aplikacji w dzierżawie Sprawdź, czy rejestracja aplikacji istnieje u prawidłowego dzierżawcy, a identyfikator klienta jest poprawny.
Wymagana domena podrzędna niestandardowa Zasób używa regionalnego punktu końcowego zamiast niestandardowej poddomeny Skonfiguruj niestandardową poddomenę w zasobie Foundry. Uwierzytelnianie oparte na tokenach wymaga niestandardowej poddomeny.

Treści powiązane

  • Last updated on