Azure Spatial Anchors に対する認証と承認Authentication and authorization to Azure Spatial Anchors

この記事では、アプリまたは Web サービスから Azure Spatial Anchors に対する認証を実行できるさまざまな方法について説明します。In this article, you'll learn the various ways you can authenticate to Azure Spatial Anchors from your app or web service. Azure Active Directory (Azure AD) で Azure ロールベースのアクセス制御 (Azure RBAC) を使用して、Spatial Anchors アカウントへのアクセスを制御する方法についても説明します。You'll also learn about the ways you can use Azure role-based access control (Azure RBAC) in Azure Active Directory (Azure AD) to control access to your Spatial Anchors accounts.

概要Overview

Azure Spatial Anchors に対する認証の概要を示す図。

特定の Azure Spatial Anchors アカウントにアクセスするには、まずクライアントで Azure Mixed Reality セキュリティ トークン サービス (STS) からアクセス トークンを取得する必要があります。To access a given Azure Spatial Anchors account, clients need to first obtain an access token from Azure Mixed Reality Security Token Service (STS). STS から取得したトークンは、24 時間有効です。Tokens obtained from STS have a lifetime of 24 hours. それには Spatial Anchors サービスでアカウントの承認決定を行うために使用する情報が含まれており、承認されたプリンシパルのみがアカウントにアクセスできるようにします。They contain information that Spatial Anchors services use to make authorization decisions on the account and ensure that only authorized principals can access the account.

アクセス トークンは、アカウント キーまたは Azure AD によって発行されたトークンのいずれかと引き換えに取得できます。Access tokens can be obtained in exchange for either account keys or tokens issued by Azure AD.

アカウント キーを使用すると、Azure Spatial Anchors サービスの使用をすぐに開始できます。Account keys enable you to get started quickly with using the Azure Spatial Anchors service. ただし、アプリケーションを運用環境にデプロイする前に、Azure AD 認証を使用するようにアプリを更新することをお勧めします。But before you deploy your application to production, we recommend that you update your app to use Azure AD authentication.

Azure AD 認証トークンは、2 つの方法で取得できます。You can obtain Azure AD authentication tokens in two ways:

  • エンタープライズ アプリケーションをビルドしていて、会社の ID システムとして Azure AD を使用している場合は、アプリ内でユーザーベースの Azure AD 認証を使用できます。If you're building an enterprise application and your company is using Azure AD as its identity system, you can use user-based Azure AD authentication in your app. その後、既存の Azure AD セキュリティ グループを使用して、Spatial Anchors アカウントにアクセス権を付与します。You then grant access to your Spatial Anchors accounts by using your existing Azure AD security groups. 組織内のユーザーに直接アクセス権を付与することもできます。You can also grant access directly to users in your organization.
  • それ以外の場合は、アプリをサポートしている Web サービスから Azure AD トークンを取得することをお勧めします。Otherwise, we recommend that you obtain Azure AD tokens from a web service that supports your app. Azure Spatial Anchors にアクセスするための資格情報をクライアント アプリケーションに埋め込むことを回避できるため、運用アプリケーションではこの方法をお勧めします。We recommend this method for production applications because it allows you to avoid embedding the credentials for access to Azure Spatial Anchors in your client application.

アカウント キーAccount keys

最も簡単に始める方法は、アカウント キーを使用して自分の Azure Spatial Anchors アカウントにアクセスすることです。The easiest way to get started is to use account keys for access to your Azure Spatial Anchors account. Azure portal で、自分のアカウント キーを取得できます。You can get your account keys on the Azure portal. 自分のアカウントに移動し、 [キー] タブを選択します。Go to your account and select the Keys tab:

[プライマリ キー] の [コピー] ボタンが強調表示されている [キー] タブを示すスクリーンショット。

2 つのキーを利用できます。Two keys are available. どちらも Spatial Anchors アカウントにアクセスするために同時に有効になっています。Both are simultaneously valid for access to the Spatial Anchors account. アカウントへのアクセスに使用するキーを定期的に更新することをお勧めします。We recommend that you regularly update the key you use to access the account. 2 つの独立した有効なキーを用意することで、ダウンタイムなしで更新を行うことができます。Having two separate valid keys enables these updates without downtime. 必要なのは、プライマリ キーとセカンダリ キーを交互に更新することだけです。You only have to update the primary key and the secondary key alternatively.

SDK には、アカウント キーを使用した認証のサポートが組み込まれています。The SDK has built-in support for authentication via account keys. 必要なのは、cloudSession オブジェクトに AccountKey プロパティを設定することだけです。You just need to set the AccountKey property on your cloudSession object:

this.cloudSession.Configuration.AccountKey = @"MyAccountKey";

そのプロパティを設定すると、SDK によって、アクセス トークンのためのアカウント キーの交換とアプリで必要なトークンのキャッシュが処理されるようになります。After you set that property, the SDK will handle the exchange of the account key for an access token and the necessary caching of tokens for your app.

警告

クイック オンボードではアカウント キーを使用することをお勧めしますが、これは開発/プロトタイプ作成中のみ行うことをお勧めします。We recommend that you use account keys for quick onboarding, but only during development/prototyping. アカウント キーが組み込まれたアプリケーションを運用環境で使用することはお勧めしません。We don't recommend that you ship your application to production with an embedded account key in it. 代わりに、次に説明するユーザーベースまたはサービスベースの Azure AD 認証方法を使用してください。Instead, use the user-based or service-based Azure AD authentication approaches described next.

Azure AD ユーザー認証Azure AD user authentication

Azure Active Directory ユーザーを対象とするアプリケーションでは、ユーザー用の Azure AD トークンを使用することをお勧めします。For applications that target Azure Active Directory users, we recommend that you use an Azure AD token for the user. このトークンは、MSAL を使用することで取得できます。You can obtain this token by using the MSAL. アプリの登録に関するクイックスタートの手順に従います。以下の手順が含まれます。Follow the steps in the quickstart on registering an app, which include:

Azure portal でIn the Azure portal

  1. アプリケーションをネイティブ アプリケーションとして Azure AD に登録します。Register your application in Azure AD as a native application. 登録の一環として、アプリケーションをマルチテナントにする必要があるかどうかを決める必要があります。As part of registering, you'll need to determine whether your application should be multitenant. アプリケーションで許可されるリダイレクト URL も指定する必要があります。You'll also need to provide the redirect URLs allowed for your application.

  2. [API のアクセス許可] タブに移動します。Go to the API permissions tab.

  3. [アクセス許可の追加] を選択します。Select Add a permission.

    1. [所属する組織で使用している API] タブの [Mixed Reality Resource Provider](Mixed Reality リソース プロバイダー) を選択します。Select Mixed Reality Resource Provider on the APIs my organization uses tab.
    2. [委任されたアクセス許可] を選択します。Select Delegated permissions.
    3. [mixedreality] の下にある [mixedreality.signin] を選択します。Select mixedreality.signin under mixedreality.
    4. [アクセス許可の追加] を選択します.Select Add permissions.
  4. [管理者の同意の付与] を選択します。Select Grant admin consent.

  5. アプリケーションまたはユーザーにご使用のリソースへのアクセス権を付与します。Grant your application or users access to your resource:

    1. Azure portal で、ご使用の Spatial Anchors リソースに移動します。Go to your Spatial Anchors resource in the Azure portal.
    2. [アクセス制御 (IAM)] タブに移動します。Go to the Access control (IAM) tab.
    3. [ロールの割り当ての追加] を選択します。Select Add role assignment.
    4. ロールを選択しますSelect a role.
    5. [選択] ボックスに、アクセス権を割り当てるユーザー、グループ、またはアプリケーションの名前を入力します。In the Select box, enter the names of the users, groups, and/or applications to which you want to assign access.
    6. [保存] を選択します。Select Save.

コードでIn your code

  1. MSAL の client IDRedirectUri パラメーターに自分の Azure AD アプリケーションのアプリケーション ID とリダイレクト URI を使用することを確認します。Be sure to use the application ID and redirect URI of your own Azure AD application for the client ID and RedirectUri parameters in MSAL.
  2. テナント情報を設定します。Set the tenant information:
    1. 自分のアプリケーションで [所属する組織のみ] がサポートされる場合は、この値を自分の テナント ID または テナント名 に置き換えます。If your application supports My organization only, replace this value with your Tenant ID or Tenant name. 例: contoso.microsoft.com。For example, contoso.microsoft.com.
    2. 自分のアプリケーションで [任意の組織のディレクトリ内のアカウント] がサポートされる場合は、この値を organizations に置き換えます。If your application supports Accounts in any organizational directory, replace this value with Organizations.
    3. 自分のアプリケーションで [すべての Microsoft アカウント ユーザー] がサポートされる場合は、この値を Common に置き換えます。If your application supports All Microsoft account users, replace this value with Common.
  3. トークン要求で [スコープ]"https://sts.<account-domain>//.default" に設定します。<account-domain> は Azure Spatial Anchors アカウントの アカウント ドメイン に置換されます。On your token request, set the scope to "https://sts.<account-domain>//.default", where <account-domain> is replaced with the Account Domain for your Azure Spatial Anchors account. 米国東部 2 アカウント ドメインの Azure Spatial Anchors アカウントのスコープ例は "https://sts.mixedreality.azure.com//.default" です。An example scope for an Azure Spatial Anchors account in the East US 2 account domain is "https://sts.mixedreality.azure.com//.default". このスコープでは、アプリケーション上で Mixed Reality セキュリティ トークン サービス (STS) に対してトークンを要求していることを Azure AD に示します。This scope will indicate to Azure AD that your application is requesting a token for the Mixed Reality Security Token Service (STS).

これらの手順を完了すると、アプリケーションで MSAL から Azure AD トークンを取得できるようになります。After you complete these steps, your application should be able to obtain from MSAL an Azure AD token. その Azure AD トークンを、authenticationToken としてクラウド セッション構成オブジェクトに設定できます。You can set that Azure AD token as the authenticationToken on your cloud session configuration object:

this.cloudSession.Configuration.AuthenticationToken = @"MyAuthenticationToken";

Azure AD サービス認証Azure AD service authentication

Azure Spatial Anchors を使用するアプリを運用環境にデプロイするには、認証要求を仲介するバックエンド サービスを使用することをお勧めします。To deploy apps that use Azure Spatial Anchors to production, we recommend that you use a back-end service that will broker authentication requests. プロセスの概要を以下に示します。Here's an overview of the process:

Azure Spatial Anchors に対する認証の概要を示す図。

ここでは、自分のアプリで独自のメカニズムを使用して、バックエンド サービスに対する認証を行うことを前提としていますHere, it's assumed that your app uses its own mechanism to authenticate to its back-end service. (たとえば、Microsoft アカウント、PlayFab、Facebook、Google ID、カスタム ユーザー名とパスワードなど)。ユーザーがバックエンド サービスに対して認証された後、そのサービスで Azure AD トークンを取得し、それを Azure Spatial Anchors 用のアクセス トークンと交換してクライアント アプリケーションに返すことができます。(For example, a Microsoft account, PlayFab, Facebook, a Google ID, or a custom user name and password.) After your users are authenticated to your back-end service, that service can retrieve an Azure AD token, exchange it for an access token for Azure Spatial Anchors, and return it back to your client application.

Azure AD アクセス トークンは、MSAL を介して取得されます。The Azure AD access token is retrieved via the MSAL. アプリの登録のクイックスタートに関するページの手順に従います。以下の手順が含まれます。Follow the steps in the register an app quickstart, which include:

Azure portal でIn the Azure portal

  1. Azure AD でアプリケーションを登録します。Register your application in Azure AD:
    1. Azure portal で、 [Azure Active Directory] を選択し、 [アプリの登録] を選択します。In the Azure portal, select Azure Active Directory, and then select App registrations.
    2. [新規登録] を選択します。Select New registration.
    3. アプリケーションの名前を入力し、アプリケーションの種類として [Web アプリ/API] を選択し、サービスの認証 URL を入力します。Enter the name of your application, select Web app / API as the application type, and enter the auth URL for your service. [作成] を選択しますSelect Create.
  2. アプリケーションで、 [設定] を選択し、 [証明書とシークレット] タブを選択します。新しいクライアント シークレットを作成し、期間を選択し、 [追加] を選択します。On the application, select Settings, and then select the Certificates and secrets tab. Create a new client secret, select a duration, and then select Add. シークレット値を必ず保存してください。Be sure to save the secret value. それを Web サービスのコードに含める必要があります。You'll need to include it in your web service's code.
  3. アプリケーションまたはユーザー (および両方) にリソースへのアクセス権を付与します。Grant your application and/or users access to your resource:
    1. Azure portal で、ご使用の Spatial Anchors リソースに移動します。Go to your Spatial Anchors resource in the Azure portal.

    2. [アクセス制御 (IAM)] タブに移動します。Go to the Access control (IAM) tab.

    3. [ロールの割り当ての追加] を選択します。Select Add role assignment.

    4. ロールを選択しますSelect a role.

    5. [選択] ボックスに、アクセス権を割り当てるアプリケーションの名前を入力します (1 つまたは複数)。In the Select box, enter the name or names of the applications to which you want to assign access. アプリのユーザーに Spatial Anchors アカウントとは異なるロールを割り当てる場合は、複数のアプリケーションを Azure AD に登録し、それぞれに別のロールを割り当てます。If you want your app's users to have different roles against the Spatial Anchors account, register multiple applications in Azure AD and assign a separate role to each one. 次に、ユーザーに適切なロールを使用するために承認ロジックを実装します。Then implement your authorization logic to use the right role for your users.

      注意

      [ロールの割り当ての追加] ペインで、 [アクセスの割り当て先] から [Azure AD のユーザー、グループ、サービス プリンシパル] を選択します。In the Add role assignment pane, in Assign access to, select Azure AD user, group, or service principal.

    6. [保存] を選択します。Select Save.

コードでIn your code

注意

Spatial Anchors のサンプル アプリの一部として利用可能なサービス サンプルを使用できます。You can use the service sample that is available as a part of the Spatial Anchors sample apps.

  1. 自分の Azure AD アプリケーションのアプリケーション ID、アプリケーション シークレット、およびリダイレクト URI を、MSAL の client IDsecret、および RedirectUri の各パラメーターとして使用することを確認します。Be sure to use the application ID, application secret, and redirect URI of your own Azure AD application as the client ID, secret, and RedirectUri parameters in MSAL.
  2. 自分の Azure AD テナント ID に対する tenant ID を、MSAL の authority パラメーターに設定します。Set the tenant ID to your own Azure AD tenant ID in the authority parameter in MSAL.
  3. トークン要求で [スコープ]"https://sts.<account-domain>//.default" に設定します。<account-domain> は Azure Spatial Anchors アカウントの アカウント ドメイン に置換されます。On your token request, set the scope to "https://sts.<account-domain>//.default", where <account-domain> is replaced with the Account Domain for your Azure Spatial Anchors account. 米国東部 2 アカウント ドメインの Azure Spatial Anchors アカウントのスコープ例は "https://sts.mixedreality.azure.com//.default" です。An example scope for an Azure Spatial Anchors account in the East US 2 account domain is "https://sts.mixedreality.azure.com//.default".

これらの手順を完了すると、バックエンド サービスによって Azure AD トークンを取得できます。After you complete these steps, your back-end service can retrieve an Azure AD token. その後、クライアントに返される MR トークンに交換できます。It can then exchange it for an MR token that it will return back to the client. Azure AD トークンを使用した MR トークンの取得は、REST 呼び出しで行われます。Using an Azure AD token to retrieve an MR token is done via a REST call. 呼び出しの例を次に示します。Here's a sample call:

GET https://sts.mixedreality.azure.com/Accounts/35d830cb-f062-4062-9792-d6316039df56/token HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni<truncated>FL8Hq5aaOqZQnJr1koaQ
Host: sts.mixedreality.azure.com
Connection: Keep-Alive

HTTP/1.1 200 OK
Date: Sun, 24 Feb 2019 08:00:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1153
Accept: application/json
MS-CV: 05JLqWeKFkWpbdY944yl7A.0
{"AccessToken":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjI2MzYyMTk5ZTI2NjQxOGU4ZjE3MThlM2IyMThjZTIxIiwidHlwIjoiSldUIn0.eyJqdGkiOiJmMGFiNWIyMy0wMmUxLTQ1MTQtOWEzNC0xNzkzMTA1NTc4NzAiLCJjYWkiOiIzNWQ4MzBjYi1mMDYyLTQwNjItOTc5Mi1kNjMxNjAzOWRmNTYiLCJ0aWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJhaWQiOiIzNWQ4MzBjYi1mMDYyLTQwNjItOTc5Mi1kNjMxNjAzOWRmNTYiLCJhYW8iOi0xLCJhcHIiOiJlYXN0dXMyIiwicmlkIjoiL3N1YnNjcmlwdGlvbnMvNzIzOTdlN2EtNzA4NC00ODJhLTg3MzktNjM5Y2RmNTMxNTI0L3Jlc291cmNlR3JvdXBzL3NhbXBsZV9yZXNvdXJjZV9ncm91cC9wcm92aWRlcnMvTWljcm9zb2Z0Lk1peGVkUmVhbGl0eS9TcGF0aWFsQW5jaG9yc0FjY291bnRzL2RlbW9fYWNjb3VudCIsIm5iZiI6MTU0NDU0NzkwMywiZXhwIjoxNTQ0NjM0MzAzLCJpYXQiOjE1NDQ1NDc5MDMsImlzcyI6Imh0dHBzOi8vbXJjLWF1dGgtcHJvZC50cmFmZmljbWFuYWdlci5uZXQvIiwiYXVkIjoiaHR0cHM6Ly9tcmMtYW5jaG9yLXByb2QudHJhZmZpY21hbmFnZXIubmV0LyJ9.BFdyCX9UJj0i4W3OudmNUiuaGgVrlPasNM-5VqXdNAExD8acFJnHdvSf6uLiVvPiQwY1atYyPbOnLYhEbIcxNX-YAfZ-xyxCKYb3g_dbxU2w8nX3zDz_X3XqLL8Uha-rkapKbnNgxq4GjM-EBMCill2Svluf9crDmO-SmJbxqIaWzLmlUufQMWg_r8JG7RLseK6ntUDRyDgkF4ex515l2RWqQx7cw874raKgUO4qlx0cpBAB8cRtGHC-3fA7rZPM7UQQpm-BC3suXqRgROTzrKqfn_g-qTW4jAKBIXYG7iDefV2rGMRgem06YH_bDnpkgUa1UgJRRTckkBuLkO2FvA"}

Authorization ヘッダーは、次のように書式設定されます。Bearer <Azure_AD_token>The Authorization header is formatted as follows: Bearer <Azure_AD_token>

応答には、プレーン テキストの MR トークンが含まれます。The response contains the MR token in plain text.

その MR トークンは、その後、クライアントに返されます。That MR token is then returned to the client. クライアント アプリで、それをアクセス トークンとしてクラウド セッション構成に設定できます。Your client app can then set it as its access token in the cloud session configuration:

this.cloudSession.Configuration.AccessToken = @"MyAccessToken";

Azure ロールベースのアクセス制御Azure role-based access control

アプリケーション、サービス、またはサービスの Azure AD ユーザーに付与されるアクセスのレベルを制御するために、必要に応じて、ご使用の Azure Spatial Anchors アカウントに次の既存のロールを割り当てることができます。To help you control the level of access granted to applications, services, or Azure AD users of your service, you can assign these pre-existing roles as needed against your Azure Spatial Anchors accounts:

  • Spatial Anchors アカウント所有者Spatial Anchors Account Owner. このロールが割り当てられているアプリケーションまたはユーザーは、空間アンカーの作成、それらのクエリ、およびそれらの削除を実行できます。Applications or users that have this role can create spatial anchors, query for them, and delete them. アカウント キーを使用してアカウントを認証すると、認証されたプリンシパルに Spatial Anchors アカウント所有者ロールが割り当てられます。When you authenticate to your account by using account keys, the Spatial Anchors Account Owner role is assigned to the authenticated principal.
  • Spatial Anchors アカウント共同作成者Spatial Anchors Account Contributor. このロールが割り当てられているアプリケーションまたはユーザーは、空間アンカーの作成とそれらのクエリを実行できますが、それらを削除することはできません。Applications or users that have this role can create spatial anchors and query for them, but they can't delete them.
  • Spatial Anchors アカウント閲覧者Spatial Anchors Account Reader. このロールが割り当てられているアプリケーションまたはユーザーは、空間アンカーのクエリのみを実行できます。Applications or users that have this role can only query for spatial anchors. 新規作成、既存のものの削除、またはそれらのメタデータの更新を行うことはできません。They can't create new ones, delete existing ones, or update metadata on them. このロールは、通常は、一部のユーザーが環境をキュレートし、他のユーザーは環境に既に配置されているアンカーの呼び戻しのみを実行できる環境で使用されます。This role is typically used for applications where some users curate the environment but others can only recall anchors previously placed in the environment.

次の手順Next steps

Azure Spatial Anchors を使用する初めてのアプリを作成します。Create your first app with Azure Spatial Anchors: