Azure Cognitive Services に対する要求の認証

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

前提条件

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

アカウントの作成後に、Azure portal からサブスクリプション キーを取得できます。

認証ヘッダー

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

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

単一サービスのサブスクリプション キーによる認証

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

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

これは、Bing Web Search API 呼び出しのサンプルです。

curl -X GET 'https://api.cognitive.microsoft.com/bing/v7.0/search?q=Welsch%20Pembroke%20Corgis' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' | json_pp

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

次のビデオでは、Cognitive Services キーを使用するデモンストレーションを行っています。

マルチサービスのサブスクリプション キーによる認証

警告

現時点では、マルチサービス キーは QnA Maker、Immersive Reader、Personalizer、および Anomaly Detector をサポートしていません。

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

サブスクリプション キーは、各要求内で Ocp-Apim-Subscription-Key ヘッダーとして指定されます。

Cognitive Services のマルチサービスのサブスクリプション キーのデモ

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

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

Translator サービスと共にマルチサービスのサブスクリプション キーを使用する場合は、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

サンプルの要求

これは、Bing Web Search API 呼び出しのサンプルです。

curl -X GET 'https://YOUR-REGION.api.cognitive.microsoft.com/bing/v7.0/search?q=Welsch%20Pembroke%20Corgis' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' | json_pp

これは、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 Cognitive Services はアクセス トークンを受け入れ、また場合によってはアクセス トークンは必須です。 現在、以下のサービスでアクセス トークンがサポートされています。

  • Text Translation API
  • Speech Services: Speech-to-text API
  • Speech Services: Text-to-speech API

注意

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

警告

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

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

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

サンプルの要求

サブスクリプション キーをアクセス トークンと交換するには、https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken という URL を使用します。

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

Azure Active Directory で認証を行う

重要

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

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

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

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

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

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

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

    $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. まず、Azure AD アプリケーションを登録してみましょう。

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

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

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

    New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
    

    注意

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

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

    注意

    アプリケーションの ObjectId ではなく、サービス プリンシパルの ObjectId が使用されます。 ACCOUNT_ID は、作成した Cognitive Services アカウントの 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. トークンを取得します。

    注意

    Azure Cloud Shell を使用している場合、SecureClientSecret クラスは使用できません。

    $authContext = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext" -ArgumentList "https://login.windows.net/<TENANT_ID>"
    $secureSecretObject = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.SecureClientSecret" -ArgumentList $SecureStringPassword   
    $clientCredential = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.ClientCredential" -ArgumentList $app.ApplicationId, $secureSecretObject
    $token=$authContext.AcquireTokenAsync("https://cognitiveservices.azure.com/", $clientCredential).Result
    $token
    

  1. Computer Vision API を呼び出します。
    $url = $account.Endpoint+"vision/v1.0/models"
    $result = Invoke-RestMethod -Uri $url  -Method Get -Headers @{"Authorization"=$token.CreateAuthorizationHeader()} -Verbose
    $result | ConvertTo-Json
    

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

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

Cognitive Services では、Azure リソースのマネージド ID を使用した Azure Active Directory (Azure AD) 認証がサポートされています。 Azure リソースのマネージド ID では、Azure Virtual Machines (VMs)、Function Apps、Virtual Machine Scale Sets などのサービスで実行されているアプリケーションから Cognitive Services リソースへのアクセスを、Azure AD 資格情報を使用して承認することができます。 Azure リソースのマネージド ID を Azure AD 認証と一緒に使用することで、クラウドで動作するアプリケーションに資格情報を保存することを避けることができます。

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

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

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

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

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

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

関連項目