Azure Spatial Anchors 的驗證和授權

在本文中，您將瞭解從應用程式或 Web 服務向 Azure Spatial Anchors 進行驗證的各種方式。 您也將瞭解在 Microsoft Entra ID 中使用 Azure 角色型存取控制 （Azure RBAC） 來控制空間錨點帳戶存取的方式。

警告

建議您使用帳戶金鑰快速上線，但只能在開發/原型設計期間使用。 我們不建議您將應用程式寄送至生產環境，其中包含內嵌帳戶金鑰。 請改用使用者型或服務型 Microsoft Entra 驗證方法，如下所述。

概觀

若要存取指定的 Azure Spatial Anchors 帳戶，用戶端必須先從 Azure Mixed Reality Security Token Service （STS） 取得存取權杖。 從 STS 取得的權杖存留期為 24 小時。 它們包含 Spatial Anchors 服務用來對帳戶進行授權決策的資訊，並確保只有授權的主體可以存取帳戶。

您可以取得存取權杖，以換取 Microsoft Entra ID 所簽發的帳戶金鑰或權杖。

帳戶金鑰可讓您快速開始使用 Azure Spatial Anchors 服務。 但在您將應用程式部署至生產環境之前，建議您先更新應用程式以使用 Microsoft Entra 驗證。

您可以透過兩種方式取得 Microsoft Entra 驗證權杖：

• 如果您要建置企業應用程式，且您的公司使用 Microsoft Entra ID 作為其身分識別系統，您可以在應用程式中使用使用者型 Microsoft Entra 驗證。 接著，您可以使用現有的 Microsoft Entra 安全性群組來授與 Spatial Anchors 帳戶的存取權。 您也可以直接將存取權授與組織中的使用者。
• 否則，建議您從支援您應用程式的 Web 服務取得 Microsoft Entra 權杖。 建議您針對生產應用程式使用此方法，因為它可讓您避免將認證內嵌至用戶端應用程式中的 Azure Spatial Anchors 存取權。

帳戶金鑰

開始使用最簡單的方式是使用帳戶金鑰來存取您的 Azure Spatial Anchors 帳戶。 您可以在Azure 入口網站上取得帳戶金鑰。 移至您的帳戶，然後選取 [ 金鑰] 索引卷 標：

有兩個金鑰可供使用。 兩者同時有效，可存取 Spatial Anchors 帳戶。 建議您定期更新用來存取帳戶的金鑰。 有兩個不同的有效金鑰可讓這些更新不停機。 您只需要更新主鍵和次要金鑰。

SDK 內建支援透過帳戶金鑰進行驗證。 您只需要在 物件上 cloudSession 設定 AccountKey 屬性：

C#

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

Objective-C

_cloudSession.configuration.accountKey = @"MyAccountKey";

迅速

_cloudSession!.configuration.accountKey = "MyAccountKey"

Java

mCloudSession.getConfiguration().setAccountKey("MyAccountKey");

C++ NDK

auto configuration = cloudSession_->Configuration();
configuration->AccountKey(R"(MyAccountKey)");

C++/WinRT

auto configuration = m_cloudSession.Configuration();
configuration.AccountKey(LR"(MyAccountKey)");

設定該屬性之後，SDK 會處理存取權杖的帳戶金鑰交換，以及應用程式權杖的必要快取。

Microsoft Entra 使用者驗證

針對以 Microsoft Entra 使用者為目標的應用程式，建議您為使用者使用 Microsoft Entra 權杖。 您可以使用 MSAL 來取得此權杖 。 請遵循註冊應用程式 快速入門中的 步驟，包括：

在Azure 入口網站

1. 在 Microsoft Entra ID 中將您的應用程式註冊為原生應用程式。 在註冊時，您必須判斷應用程式是否應該是多租使用者。 您也必須提供應用程式允許的重新導向 URL。

2. 移至 [ API 許可權] 索引 標籤。

3. 選取新增權限。

   1. 在 [我的組織使用的 API] 索引標籤上 ，選取 [混合實境資源提供者 ]。
   2. 選取委派的權限。
   3. 在 [混合實境 ] 底下 選取 [mixedreality.signin ]。
   4. 選取新增權限。

4. 選取授與管理員同意。

5. 將 ASA RBAC 角色 指派給您想要授與資源存取權的應用程式或使用者。 如果您想要讓應用程式的使用者對 ASA 帳戶有不同的角色，請在 Microsoft Entra ID 中註冊多個應用程式，並將個別角色指派給每個應用程式。 然後實作您的授權邏輯，為您的使用者使用正確的角色。 如需詳細的角色指派步驟，請參閱 使用Azure 入口網站 指派 Azure 角色。

在您的程式碼中

1. 請務必針對 MSAL 中的用戶端識別碼和 RedirectUri 參數，使用您自己的 Microsoft Entra 應用程式的應用程式 識別碼 和 重新導向 URI。
2. 設定租使用者資訊：
   1. 如果您的應用程式僅支援 我的組織，請將此值取代為您的 租使用者識別碼 或 租使用者名稱 。 例如，contoso.microsoft.com。
   2. 如果您的應用程式支援 任何組織目錄中 的帳戶，請將此值取代為 組織 。
   3. 如果您的應用程式支援 所有 Microsoft 帳戶使用者 ，請將此值取代為 Common 。
3. 在您的權杖要求上，將 範圍 設定為 https://sts.mixedreality.azure.com//.default 。 此範圍會向 Microsoft Entra 識別碼指出您的應用程式要求混合實境安全性權杖服務 （STS） 的權杖。

完成這些步驟之後，您的應用程式應該能夠從 MSAL 取得 Microsoft Entra 權杖。 您可以將 Microsoft Entra 權杖設定為 authenticationToken 雲端會話組態物件上的 ：

C#

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

Objective-C

_cloudSession.configuration.authenticationToken = @"MyAuthenticationToken";

迅速

_cloudSession!.configuration.authenticationToken = "MyAuthenticationToken"

Java

mCloudSession.getConfiguration().setAuthenticationToken("MyAuthenticationToken");

C++ NDK

auto configuration = cloudSession_->Configuration();
configuration->AuthenticationToken(R"(MyAuthenticationToken)");

C++/WinRT

auto configuration = m_cloudSession.Configuration();
configuration.AuthenticationToken(LR"(MyAuthenticationToken)");

Microsoft Entra 服務驗證

若要將使用 Azure Spatial Anchors 的應用程式部署到生產環境，建議您使用後端服務來代理驗證要求。 以下是程式的概觀：

在此，假設您的應用程式會使用自己的機制向後端服務進行驗證。 （例如，Microsoft 帳戶、PlayFab、Facebook、Google ID 或自訂使用者名稱和密碼。在使用者向後端服務進行驗證之後，該服務可以擷取 Microsoft Entra 權杖、將它交換為 Azure Spatial Anchors 的存取權杖，並將它傳回用戶端應用程式。

Microsoft Entra 存取權杖是透過 MSAL 擷取。 請遵循註冊應用程式快速入門 中的 步驟，包括：

在Azure 入口網站

1. 在 Microsoft Entra 識別碼中註冊您的應用程式：
   1. 在Azure 入口網站中，選取 [Microsoft Entra ID ]，然後選取 [應用程式註冊 ]。
   2. 選取新增註冊。
   3. 輸入應用程式的名稱、選取 [Web 應用程式/ API ] 作為應用程式類型，然後輸入服務的驗證 URL。 選取建立。
2. 在應用程式上，選取 [設定 ]，然後選取 [憑證和秘密] 索引 標籤。建立新的用戶端密碼，選取持續時間，然後選取 [ 新增 ]。 請務必儲存秘密值。 您必須將它包含在 Web 服務的程式碼中。
3. 將 ASA RBAC 角色 指派給您想要授與資源存取權的應用程式或使用者。 如果您想要讓應用程式的使用者對 ASA 帳戶有不同的角色，請在 Microsoft Entra ID 中註冊多個應用程式，並將個別角色指派給每個應用程式。 然後實作您的授權邏輯，為您的使用者使用正確的角色。 如需詳細的角色指派步驟，請參閱 使用Azure 入口網站 指派 Azure 角色。

在您的程式碼中

注意

您可以使用 作為 Spatial Anchors 範例應用程式 一部分 的服務範例 。

1. 請務必使用您自己 Microsoft Entra 應用程式的應用程式識別碼、應用程式秘密和重新導向 URI 作為 MSAL 中的用戶端識別碼 、 秘密 和 RedirectUri 參數。
2. 將租使用者識別碼設定為 MSAL 中授權單位 參數中 您自己的 Microsoft Entra 租使用者識別碼。
3. 在您的權杖要求上，將 範圍 設定為 https://sts.mixedreality.azure.com//.default 。

完成這些步驟之後，後端服務可以擷取 Microsoft Entra 權杖。 然後，它可以將它交換回用戶端的 MR 權杖。 透過 REST 呼叫完成使用 Microsoft Entra 權杖來擷取 MR 權杖。 以下是範例呼叫：

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"}

授權標頭的格式如下： Bearer <Azure_AD_token>

回應包含純文字的 MR 權杖。

該 MR 權杖接著會傳回給用戶端。 然後，用戶端應用程式可以在雲端會話組態中將其設定為其存取權杖：

C#

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

Objective-C

_cloudSession.configuration.accessToken = @"MyAccessToken";

迅速

_cloudSession!.configuration.accessToken = "MyAccessToken"

Java

mCloudSession.getConfiguration().setAccessToken("MyAccessToken");

C++ NDK

auto configuration = cloudSession_->Configuration();
configuration->AccessToken(R"(MyAccessToken)");

C++/WinRT

auto configuration = m_cloudSession.Configuration();
configuration.AccessToken(LR"(MyAccessToken)");

Azure 角色型存取控制

為了協助您控制授與服務應用程式、服務或 Microsoft Entra 使用者的存取層級，您可以視需要指派這些預先存在的角色給 Azure Spatial Anchors 帳戶：

• Spatial Anchors 帳戶擁有者 。 具有此角色的應用程式或使用者可以建立空間錨點、查詢和刪除它們。 當您使用帳戶金鑰向您的帳戶進行驗證時，空間錨點帳戶擁有者角色會指派給已驗證的主體。
• 空間錨點帳戶參與者 。 具有此角色的應用程式或使用者可以建立空間錨點並查詢它們，但無法刪除它們。
• 空間錨點帳戶讀取器 。 具有此角色的應用程式或使用者只能查詢空間錨點。 它們無法建立新專案、刪除現有的專案，或更新其上的中繼資料。 此角色通常用於某些使用者策劃環境的應用程式，但其他角色只能重新叫用先前放置於環境中的錨點。

下一步

使用 Azure Spatial Anchors 建立您的第一個應用程式：

Unity （HoloLens）

Unity （iOS）

Unity （Android）

iOS

Android

HoloLens

Xamarin （Android）

Xamarin （iOS）