Azure AI サービスに対する要求の認証

[アーティクル]
09/04/2024

Azure AI サービスに対する各要求には、認証ヘッダーが含まれている必要があります。このヘッダーを使用して、リソースキーまたは認証トークンを渡します。これは、サービスまたはサービスのグループについてお客様のサブスクリプションを検証するために使用されます。この記事では、要求を認証するための 3 つの方法と、そのそれぞれの要件について学習します。

単一サービスまたはマルチサービスのリソースキーで認証
トークンによる認証
Microsoft Entra ID を使用して認証する

前提条件

要求を行うには、Azure アカウントと Azure AI サービスサブスクリプションが必要になります。既にアカウントをお持ちの場合は、次のセクションまでスキップして進んでください。アカウントをお持ちでない場合は、数分で設定を行えるガイドである、Azure AI サービスのリソースの作成に関するページをご覧ください。

Azure portal でリソースに移動します。 [キーとエンドポイント] セクションは、[リソース管理] セクションにあります。エンドポイントとアクセスキーをコピーします。これらは、API 呼び出しを認証するために両方とも必要です。 KEY1 または KEY2 を使用できます。常に 2 つのキーを用意しておくと、サービスを中断させることなく、キーのローテーションと再生成を安全に行うことができます。

認証ヘッダー

Azure AI サービスで使用できる認証ヘッダーについて簡単に確認しましょう。

Header	説明
Ocp-Apim-Subscription-Key	特定のサービスのリソースキーまたはマルチサービスのリソースキーを使用して認証するには、このヘッダーを使用します。
Ocp-Apim-Subscription-Region	このヘッダーは、Azure AI 翻訳サービスと共にマルチサービスのリソースキーを使用する場合にのみ必要です。このヘッダーを使用して、リソースリージョンを指定します。
認可	アクセストークンを使用する場合、このヘッダーを使用します。トークンの交換を実行する手順については、以降のセクションで詳しく説明されています。値は `Bearer <TOKEN>` 形式で指定します。

単一サービスのリソースキーを使用した認証

1 つ目の方法では、Azure AI 翻訳などの特定のサービスに対してリソースキーを使用して要求を認証します。お客様が作成したそれぞれのリソースについて、Azure portal でキーを取得できます。 Azure portal でリソースに移動します。 [キーとエンドポイント] セクションは、[リソース管理] セクションにあります。エンドポイントとアクセスキーをコピーします。これらは、API 呼び出しを認証するために両方とも必要です。 KEY1 または KEY2 を使用できます。常に 2 つのキーを用意しておくと、サービスを中断させることなく、キーのローテーションと再生成を安全に行うことができます。

リソースキーを使用して要求を認証するには、それを Ocp-Apim-Subscription-Key ヘッダーとして渡す必要があります。これは、Azure AI 翻訳サービスの呼び出しの例です。

これは、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

マルチサービスリソースキーを使用した認証

マルチサービスリソースキーを使用して要求を認証できます。主な違いは、マルチサービスリソースキーが特定のサービスに関連付けられておらず、単一のキーを使用して複数の Azure AI サービスに対する要求を認証できることです。リージョン別の提供状況、サポートされている機能、および価格については、「Azure AI サービスの価格」を参照してください。

リソースキーは、各要求内で Ocp-Apim-Subscription-Key ヘッダーとして指定されます。

サポートされているリージョン

Azure AI サービスマルチサービスのリソースキーを使用して api.cognitive.microsoft.com に対する要求を行うときは、URL にリージョンを含める必要があります。 (例: westus.api.cognitive.microsoft.com)。

Azure AI 翻訳でマルチサービスリソースキーを使用するとき、Ocp-Apim-Subscription-Region ヘッダーでリソースリージョンを指定する必要があります。

マルチサービスリソース認証は、以下のリージョンでサポートされています。

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

サンプルの要求

これは、Azure AI 翻訳サービスの呼び出しの例です。

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

アクセストークンを使用して認証する

一部の Azure AI サービスはアクセストークンを受け入れ、また場合によってはアクセストークンは必須です。現在、以下のサービスでアクセストークンがサポートされています。

Text Translation API
音声サービス: Speech to text API
音声サービス: Text to speech API

警告

アクセストークンをサポートするサービスは時間の経過と共に変わる可能性があります。この認証方法を使用する前に、サービスの API リファレンスを確認してください。

単一サービスのリソースキーとマルチサービスのリソースキーは、どちらも認証トークンと交換できます。認証トークンは 10 分間有効です。これらは JSON Web Token (JWT) 形式で格納され、JWT ライブラリを使用してプログラムで照会することができます。

アクセストークンは、Authorization ヘッダーとして要求に組み込まれます。指定されるトークンの値の前には Bearer が付いている必要があります (例: Bearer YOUR_AUTH_TOKEN)。

サンプルの要求

リソースキーをアクセストークンと交換するには、以下の URL を使用します: 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"

以下のマルチサービスのリージョンで、トークンの交換がサポートされています。

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

アクセストークンを取得したら、各要求内でそれを Authorization ヘッダーとして渡す必要があります。これは、Azure AI 翻訳サービスの呼び出しの例です。

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

Microsoft Entra ID を使用して認証する

重要

Microsoft Entra 認証は常に、Azure リソースのカスタムサブドメイン名と共に使用される必要があります。リージョンエンドポイントでは、Microsoft Entra 認証がサポートされていません。

前のセクションでは、Azure AI サービスに対して単一サービスまたはマルチサービスのサブスクリプションキーを使用して認証する方法を説明しました。これらのキーを使用すると、開発を迅速かつ簡単に開始できますが、Azure ロールベースのアクセス制御 (Azure RBAC) を必要とするより複雑なシナリオでは不十分です。 Microsoft Entra ID を使用して認証を行うために何が必要なのかを確認しましょう。

以降のセクションでは、Azure Cloud Shell 環境または Azure CLI を使用してサブドメインを作成し、ロールを割り当てて、Azure AI サービスを呼び出すベアラートークンを取得します。問題が発生した場合は、各セクションに、Azure Cloud Shell/Azure CLI の各コマンドで使用可能なすべてのオプションへのリンクが提供されています。

重要

組織で Microsoft Entra ID を介した認証を行っている場合は、組織内のユーザーが常に Microsoft Entra ID を使う必要があるように、ローカル認証 (キーによる認証) を無効にすることをお勧めします。

カスタムサブドメインを使用してリソースを作成する

最初の手順で、カスタムサブドメインを作成します。カスタムサブドメイン名のない既存の Azure AI サービスリソースを使用する場合は、「Azure AI サービスカスタムサブドメイン」の手順に従って、リソースのカスタムサブドメインを有効にします。

まず、Azure Cloud Shell を開きます。サブスクリプションを選択します。
```
Set-AzContext -SubscriptionName <SubscriptionName>
```
次に、カスタムサブドメインを使用して Azure AI サービスリソースを作成します。サブドメイン名は、グローバルに一意である必要があり、"."、"!"、"," などの特殊文字を含めることはできません。
```
$account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
```
成功すると、エンドポイントにリソースに固有のサブドメイン名が表示されます。

サービスプリンシパルにロールを割り当てる

これで、カスタムサブドメインがリソースに関連付けられたので、ロールをサービスプリンシパルに割り当てる必要があります。

注意

Azure ロールの割り当ての反映には最大で 5 分かかる場合があることに留意してください。

まず、Microsoft Entra アプリケーションを登録しましょう。

$SecureStringPassword = ConvertTo-SecureString -String <YOUR_PASSWORD> -AsPlainText -Force

$app = New-AzureADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -PasswordCredentials $SecureStringPassword

次の手順では、ApplicationId が必要になります。

次に、Microsoft Entra アプリケーションのサービスプリンシパルを作成する必要があります。
```
New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
```
Note

Azure portal でアプリケーションを登録したら、この手順は完了です。
最後の手順では、(リソースにスコープが設定された) サービスプリンシパルに "Cognitive Services ユーザー" ロールを割り当てます。ロールを割り当てて、このリソースにサービスプリンシパルアクセス権を付与します。同じサービスプリンシパルアクセスをサブスクリプション内の複数のリソースに対して許可できます。

注意

アプリケーションの ObjectId ではなく、サービスプリンシパルの ObjectId が使用されます。 ACCOUNT_ID は、作成した Azure AI サービスアカウントの Azure リソース ID になります。 Azure portal でリソースの "プロパティ" から Azure リソース ID を検索できます。
```
New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
```

要求のサンプル

このサンプルでは、サービスプリンシパルの認証にパスワードが使用されています。次に、指定されたトークンを使用して Computer Vision API を呼び出します。

TenantId を取得します。

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

トークンを取得します。

$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

Note

スクリプトでパスワードを使う場合、最も安全なオプションは、PowerShell のシークレット管理モジュールを使い、Azure Key Vault などのソリューションと統合することです。

Computer Vision API を呼び出します。

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

または、証明書を使用してサービスプリンシパルを認証することもできます。サービスプリンシパルの他に、別の Microsoft Entra アプリケーションから委任されたアクセス許可を持つことで、ユーザープリンシパルもサポートされます。この場合、パスワードまたは証明書の代わりに、ユーザーはトークンを取得するときに 2 要素認証が求められます。

マネージド ID へのアクセスを認証する

Azure AI サービスでは、Azure リソースのマネージド ID を使用した Microsoft Entra 認証がサポートされています。 Azure リソースのマネージド ID では、Azure 仮想マシン (VM)、関数アプリ、仮想マシンスケールセットなどのサービスで実行されているアプリケーションから Azure AI サービスリソースへのアクセスを、Microsoft Entra 資格情報を使用して承認することができます。 Azure リソースのマネージド ID と Microsoft Entra 認証を併用すると、クラウドで実行されるアプリケーションに資格情報を保存することを避けることができます。

VM 上のマネージド ID を有効にする

Azure リソースのマネージド ID を使用して、ご利用の VM から Azure AI サービスリソースへのアクセスを承認するには、VM 上で Azure リソースのマネージド ID を有効にする必要があります。 Azure リソースのマネージド ID を有効にする方法については、次を参照してください。

マネージド ID の詳細については、Azure リソースのマネージド ID に関するページを参照してください。

Azure Key Vault を使用して資格情報に安全にアクセスする

Azure Key Vault を使用して、Azure AI サービスアプリケーションを安全に開発できます。 Key Vault を使用すると、認証資格情報をクラウドに格納でき、アプリケーションにセキュリティ情報を格納しないため、シークレットが誤って漏洩する可能性が低くなります。

認証は Microsoft Entra ID によって行われます。認可は、Azure ロールベースのアクセス制御 (Azure RBAC) または Key Vault のアクセスポリシーを使用して行うことができます。 Azure RBAC は、コンテナーの管理と、コンテナーに格納されているデータへのアクセスの両方に使用できます。一方、Key Vault のアクセスポリシーは、コンテナーに格納されているデータにアクセスしようとするときにのみ使用できます。

次の方法で共有

Azure AI サービスに対する要求の認証

前提条件

認証ヘッダー

単一サービスのリソースキーを使用した認証

マルチサービスリソースキーを使用した認証

サポートされているリージョン

サンプルの要求

アクセストークンを使用して認証する

サンプルの要求

Microsoft Entra ID を使用して認証する

カスタムサブドメインを使用してリソースを作成する

サービスプリンシパルにロールを割り当てる

要求のサンプル

マネージド ID へのアクセスを認証する

VM 上のマネージド ID を有効にする

Azure Key Vault を使用して資格情報に安全にアクセスする

関連項目

フィードバック

その他のリソース

次の方法で共有

Azure AI サービスに対する要求の認証

前提条件

認証ヘッダー

単一サービスのリソース キーを使用した認証

マルチサービス リソース キーを使用した認証

サポートされているリージョン

サンプルの要求

アクセス トークンを使用して認証する

サンプルの要求

Microsoft Entra ID を使用して認証する

カスタム サブドメインを使用してリソースを作成する

サービス プリンシパルにロールを割り当てる

要求のサンプル

マネージド ID へのアクセスを認証する

VM 上のマネージド ID を有効にする

Azure Key Vault を使用して資格情報に安全にアクセスする

関連項目

フィードバック

その他のリソース

単一サービスのリソースキーを使用した認証

マルチサービスリソースキーを使用した認証

アクセストークンを使用して認証する

カスタムサブドメインを使用してリソースを作成する

サービスプリンシパルにロールを割り当てる