Uwierzytelnianie żądań do narzędzi Foundry

Każde żądanie narzędzi Foundry Tools musi zawierać nagłówek uwierzytelniania. Ten nagłówek przechodzi wzdłuż klucza zasobu lub tokenu uwierzytelniania, który służy do weryfikowania subskrypcji dla usługi lub grupy usług. W tym artykule poznasz trzy sposoby uwierzytelniania żądania i wymagania dotyczące każdego z nich.

• Uwierzytelnij się za pomocą klucza zasobu dla pojedynczej usługi lub wielousługowego Foundry.
• Uwierzytelnianie przy użyciu tokenu.
• Uwierzytelnianie przy użyciu identyfikatora Entra firmy Microsoft.

Wymagania wstępne

Przed wykonaniem żądania potrzebna jest subskrypcja platformy Azure i zasób usługi Foundry. Jeśli potrzebujesz zasobu usługi Foundry, zapoznaj się z przewodnikiem tworzenia zasobu usługi Foundry .

Nagłówki uwierzytelniania

Szybko przejrzyjmy nagłówki uwierzytelniania dostępne dla narzędzi Foundry.

Uwierzytelnianie przy użyciu klucza zasobu pojedynczej usługi

Pierwszą opcją jest uwierzytelnienie żądania przy użyciu klucza zasobu dla określonej usługi, takiej jak Azure Translator. Klucze są dostępne w witrynie Azure Portal dla każdego utworzonego zasobu. Przejdź do zasobu w witrynie Azure Portal. Sekcję Klucze i punkt końcowy można znaleźć w sekcji Zarządzanie zasobami. Skopiuj punkt końcowy i klucz dostępu, ponieważ będzie potrzebny zarówno do uwierzytelniania wywołań interfejsu API. Możesz użyć wartości KEY1 lub KEY2. Zawsze posiadanie dwóch kluczy umożliwia bezpieczne obracanie i ponowne generowanie kluczy bez powodowania zakłóceń usługi.

Aby użyć klucza zasobu do uwierzytelniania żądania, należy przekazać go wraz z nagłówkiem Ocp-Apim-Subscription-Key . Jest to przykładowe wywołanie usługi Azure Translator:

Jest to przykładowe wywołanie usługi Translator:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Uwierzytelnij się za pomocą klucza zasobu Foundry

Możesz użyć klucza zasobu Foundry do uwierzytelniania żądań dla wielu narzędzi Foundry. Poświadczenia uwierzytelniania nie są powiązane z określoną usługą. Zobacz Cennik narzędzi Foundry, aby uzyskać informacje o dostępności regionalnej, obsługiwanych funkcjach i cenach.

Klucz zasobu jest udostępniany w każdym żądaniu Ocp-Apim-Subscription-Key jako nagłówek.

Obsługiwane regiony

W przypadku używania klucza zasobu Foundry do wysyłania żądania do api.cognitive.microsoft.com, należy uwzględnić region w adresie URL. Na przykład: westus.api.cognitive.microsoft.com.

W przypadku korzystania z klucza zasobu Foundry za pomocą usługi Azure Translator należy określić region zasobu za pomocą nagłówka Ocp-Apim-Subscription-Region.

Uwierzytelnianie zasobów usługi Foundry jest obsługiwane w następujących regionach:

• australiaeast
• brazilsouth
• canadacentral
• centralindia
• eastasia
• eastus
• japaneast
• northeurope
• southcentralus
• southeastasia
• uksouth
• westcentralus
• westeurope
• westus
• westus2
• francecentral
• koreacentral
• northcentralus
• southafricanorth
• uaenorth
• switzerlandnorth

Przykładowe żądania

Jest to przykładowe wywołanie usługi Azure Translator:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Ocp-Apim-Subscription-Region: YOUR_SUBSCRIPTION_REGION' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Uwierzytelnianie przy użyciu tokenu dostępu

Niektóre narzędzia Foundry akceptują, a w niektórych przypadkach wymagają tokenu dostępu. Obecnie te usługi obsługują tokeny dostępu:

• interfejs API tłumaczenia tekstu
• Mowa: interfejs API zamiany mowy na tekst
• Mowa: interfejs API przekształcania tekstu na mowę

Klucze zasobów usług Foundry i AI można wymieniać na potrzeby tokenów uwierzytelniania. Tokeny uwierzytelniania są ważne przez 10 minut. Są one przechowywane w formacie JSON Web Token (JWT) i mogą być odpytywane programowo przy użyciu bibliotek JWT.

Tokeny dostępu są dołączane do żądania jako nagłówka Authorization . Podana wartość tokenu musi być poprzedzona wartością Bearer, na przykład : Bearer YOUR_AUTH_TOKEN.

Przykładowe żądania

Użyj tego adresu URL, aby wymienić klucz zasobu dla tokenu dostępu: https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken.

curl -v -X POST \
"https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Content-length: 0" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

Te regiony obsługują wymianę tokenów dla zasobów usługi Foundry:

• australiaeast
• brazilsouth
• canadacentral
• centralindia
• eastasia
• eastus
• japaneast
• northeurope
• southcentralus
• southeastasia
• uksouth
• westcentralus
• westeurope
• westus
• westus2

Po otrzymaniu tokenu dostępu należy przekazać je w każdym żądaniu Authorization jako nagłówek. Jest to przykładowe wywołanie usługi Azure Translator:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Uwierzytelnianie przy użyciu usługi Microsoft Entra ID

W poprzednich sekcjach pokazaliśmy, jak uwierzytelniać się przy użyciu kluczy interfejsu API. Chociaż te klucze zapewniają szybką i łatwą ścieżkę do rozpoczęcia programowania, brakuje ich w scenariuszach wymagających kontroli dostępu opartej na rolach (RBAC) platformy Azure. Przyjrzyjmy się temu, co jest wymagane do bezpieczniejszego uwierzytelniania przy użyciu identyfikatora Entra firmy Microsoft.

W poniższych sekcjach użyjesz środowiska usługi Azure Cloud Shell lub interfejsu wiersza polecenia platformy Azure, aby utworzyć poddomenę, przypisać role i uzyskać token elementu nośnego w celu wywołania narzędzi Foundry Tools. Jeśli utkniesz, linki są udostępniane w każdej sekcji z wszystkimi dostępnymi opcjami dla każdego polecenia w usłudze Azure Cloud Shell/interfejsie wiersza polecenia platformy Azure.

Tworzenie zasobu z niestandardową poddomeną

Pierwszym krokiem jest utworzenie niestandardowej poddomeny. Jeśli chcesz użyć istniejącego zasobu Foundry, który nie ma własnej nazwy poddomeny, postępuj zgodnie z instrukcjami w dziale Niestandardowe poddomeny narzędzi Foundry, aby włączyć własną poddomenę dla swojego zasobu.

1. Zacznij od otwarcia usługi Azure Cloud Shell. Następnie wybierz subskrypcję:

   Set-AzContext -SubscriptionName <SubscriptionName>
   

2. Następnie utwórz zasób Foundry z niestandardową poddomeną. Nazwa poddomeny musi być globalnie unikatowa i nie może zawierać znaków specjalnych, takich jak: ".", "!", ",".

   $account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
   

3. W przypadku powodzenia punkt końcowy powinien wyświetlić nazwę poddomeny unikatową dla zasobu.

Przypisywanie roli do jednostki usługi

Teraz, po utworzeniu niestandardowej poddomeny skojarzonej z zasobem, musisz przypisać rolę do jednostki usługi.

1. Najpierw zarejestrujmy aplikację Firmy Microsoft Entra.

   $SecureStringPassword = ConvertTo-SecureString -String <YOUR_PASSWORD> -AsPlainText -Force
   
   $app = New-AzureADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -PasswordCredentials $SecureStringPassword
   

   W następnym kroku będziesz potrzebować identyfikatora ApplicationId .

2. Następnie należy utworzyć jednostkę usługi dla aplikacji Microsoft Entra.

   New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
   

   Uwaga

   Jeśli zarejestrujesz aplikację w witrynie Azure Portal, ten krok zostanie ukończony.

3. Ostatnim krokiem jest przypisanie roli "Użytkownik usług Cognitive Services" do jednostki usługi (w zakresie do zasobu). Przypisując rolę, udzielasz jednostce usługi dostępu do tego zasobu. Możesz udzielić tej samej jednostki usługi dostępu do wielu zasobów w ramach subskrypcji.

   Uwaga

   Identyfikator ObjectId jednostki usługi jest używany, a nie identyfikator ObjectId dla aplikacji. ACCOUNT_ID będzie identyfikatorem zasobu Azure dla zasobu Foundry, który utworzyłeś. Identyfikator zasobu platformy Azure można znaleźć w sekcji "properties" zasobu w witrynie Azure Portal.

   New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
   

Przykładowe żądanie

W tym przykładzie hasło jest używane do uwierzytelniania jednostki usługi. Podany token jest następnie używany do wywoływania interfejsu API usługi Azure Vision.

1. Pobierz identyfikator dzierżawy:

   $context=Get-AzContext
   $context.Tenant.Id
   

2. Uzyskiwanie tokenu:

   $tenantId = $context.Tenant.Id
   $clientId = $app.ApplicationId
   $clientSecret = "<YOUR_PASSWORD>"
   $resourceUrl = "https://cognitiveservices.azure.com/"
   
   $tokenEndpoint = "https://login.microsoftonline.com/$tenantId/oauth2/token"
   $body = @{
       grant_type    = "client_credentials"
       client_id     = $clientId
       client_secret = $clientSecret
       resource      = $resourceUrl
   }
   
   $responseToken = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $body
   $accessToken = $responseToken.access_token
   

   Uwaga

   Za każdym razem, gdy używasz haseł w skrypcie, najbezpieczniejszą opcją jest użycie modułu Zarządzania wpisami tajnymi programu PowerShell i integracja z rozwiązaniem, takim jak usługa Azure Key Vault.

3. Wywołaj interfejs API usługi Azure Vision:

   $url = $account.Endpoint+"vision/v1.0/models"
   $result = Invoke-RestMethod -Uri $url  -Method Get -Headers @{"Authorization"="Bearer $accessToken"} -Verbose
   $result | ConvertTo-Json
   

Alternatywnie jednostkę usługi można uwierzytelnić przy użyciu certyfikatu. Oprócz jednostki usługi jednostka użytkownika jest również obsługiwana przez delegowanie uprawnień za pośrednictwem innej aplikacji Firmy Microsoft Entra. W takim przypadku zamiast haseł lub certyfikatów użytkownicy będą monitowani o uwierzytelnianie dwuskładnikowe podczas uzyskiwania tokenu.

Autoryzowanie dostępu do tożsamości zarządzanych

Narzędzia Foundry obsługują uwierzytelnianie firmy Microsoft Entra przy użyciu tożsamości zarządzanych dla zasobów platformy Azure. Tożsamości zarządzane dla zasobów platformy Azure mogą autoryzować dostęp do zasobów Foundry, korzystając z poświadczeń Microsoft Entra używanych przez aplikacje działające na maszynach wirtualnych Azure, aplikacjach funkcji, zestawach skalowania maszyn wirtualnych oraz innych usługach. Korzystając z tożsamości zarządzanych dla zasobów platformy Azure wraz z uwierzytelnianiem firmy Microsoft Entra, można uniknąć przechowywania poświadczeń z aplikacjami uruchomionymi w chmurze.

Włączanie tożsamości zarządzanych na maszynie wirtualnej

Aby można było użyć tożsamości zarządzanych dla zasobów platformy Azure w celu autoryzowania dostępu do zasobów usługi Foundry z maszyny wirtualnej, należy włączyć tożsamości zarządzane dla zasobów platformy Azure na maszynie wirtualnej. Aby dowiedzieć się, jak włączyć tożsamości zarządzane dla zasobów platformy Azure, zobacz:

• Azure Portal
• Azure PowerShell
• Interfejs wiersza polecenia platformy Azure
• Szablon usługi Azure Resource Manager
• Biblioteki klienta usługi Azure Resource Manager

Aby uzyskać więcej informacji na temat tożsamości zarządzanych, zobacz Tożsamości zarządzane dla zasobów platformy Azure.

Bezpieczne uzyskiwanie dostępu do poświadczeń przy użyciu usługi Azure Key Vault

Za pomocą usługi Azure Key Vault można bezpiecznie opracowywać aplikacje firmy Microsoft Foundry. Usługa Key Vault umożliwia przechowywanie poświadczeń uwierzytelniania w chmurze i zmniejsza prawdopodobieństwo przypadkowego wycieku wpisów tajnych, ponieważ nie będziesz przechowywać informacji zabezpieczających w aplikacji.

Uwierzytelnianie odbywa się za pośrednictwem identyfikatora Entra firmy Microsoft. Autoryzacja może odbywać się za pomocą kontroli dostępu opartej na rolach (RBAC) platformy Azure lub zasad dostępu usługi Key Vault. Kontrola dostępu oparta na rolach platformy Azure może służyć zarówno do zarządzania magazynami, jak i uzyskiwania dostępu do danych przechowywanych w magazynie, podczas gdy zasady dostępu do magazynu kluczy mogą być używane tylko podczas próby uzyskania dostępu do danych przechowywanych w magazynie.

Powiązana zawartość

• Co to są narzędzia odlewnicze?
• Cennik narzędzi Foundry
• Niestandardowe poddomeny