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

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

前提条件

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

アカウントの作成後に、Azure portal からリソース キーを取得できます。

認証ヘッダー

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

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

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

1 つ目の方法では、Translator などの特定のサービスに対してリソース キーを使用して要求を認証します。 お客様が作成したそれぞれのリソースについて、Azure portal でキーを取得できます。 リソース キーを使用して要求を認証するには、それを Ocp-Apim-Subscription-Key ヘッダーとして渡す必要があります。

以下のサンプル要求は、Ocp-Apim-Subscription-Key ヘッダーの使用方法を示しています。 このサンプルを使用する際は有効なリソース キーを含める必要があることに注意してください。

これは、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 サービスに対する要求を認証できることです。 リージョン別の提供状況、サポートされている機能、および価格については、「Azure AI サービスの価格」を参照してください。

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

Multi-service resource key demonstration for Azure AI services

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

マルチサービスのリソース キーを使用して 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

サンプルの要求

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

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

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

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

注意

QnA Maker でも Authorization ヘッダーが使用されますが、エンドポイント キーが必要です。 詳細については、QnA Maker でナレッジ ベースから回答を取得する方法に関するページを参照してください。

警告

アクセス トークンをサポートするサービスは時間の経過と共に変わる可能性があります。この認証方法を使用する前に、サービスの 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 ヘッダーとして渡す必要があります。 これは、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

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 サービス カスタム サブドメイン」の手順に従って、リソースのカスタム サブドメインを有効にします。

  1. まず、Azure Cloud Shell を開きます。 サブスクリプションを選択します。

    Set-AzContext -SubscriptionName <SubscriptionName>
    
  2. 次に、カスタム サブドメインを使用して Azure AI サービス リソースを作成します。 サブドメイン名は、グローバルに一意である必要があり、"."、"!"、"," などの特殊文字を含めることはできません。

    $account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
    
  3. 成功すると、エンドポイントにリソースに固有のサブドメイン名が表示されます。

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

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

注意

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

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

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

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

  2. 次に、Microsoft Entra アプリケーションのサービス プリンシパルを作成する必要があります。

    New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
    

    Note

    Azure portal でアプリケーションを登録したら、この手順は完了です。

  3. 最後の手順では、(リソースにスコープが設定された) サービス プリンシパルに "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 を呼び出します。

  1. TenantId を取得します。

    $context=Get-AzContext
    $context.Tenant.Id
    
  2. トークンを取得します。

    $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 などのソリューションと統合することです。

  3. 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 のアクセス ポリシーは、コンテナーに格納されているデータにアクセスしようとするときにのみ使用できます。

関連項目