Autenticazione e autorizzazione per Ancoraggi nello spazio di AzureAuthentication and authorization to Azure Spatial Anchors

Questo articolo illustra i diversi modi in cui è possibile eseguire l'autenticazione a ancoraggi spaziali di Azure dall'app o dal servizio Web.In this article, you'll learn the various ways you can authenticate to Azure Spatial Anchors from your app or web service. Verranno inoltre fornite informazioni sui modi in cui è possibile utilizzare il controllo degli accessi in base al ruolo di Azure (RBAC di Azure) in Azure Active Directory (Azure AD) per controllare l'accesso agli account di ancoraggio spaziali.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.

PanoramicaOverview

Diagramma che mostra una panoramica dell'autenticazione per gli ancoraggi spaziali di Azure.

Per accedere a uno specifico account di Ancoraggi nello spazio di Azure, i client devono prima ottenere un token di accesso dal servizio token di sicurezza (STS) di Realtà mista di Azure.To access a given Azure Spatial Anchors account, clients need to first obtain an access token from Azure Mixed Reality Security Token Service (STS). I token ottenuti da STS hanno una durata di 24 ore.Tokens obtained from STS have a lifetime of 24 hours. Contengono informazioni che i servizi di ancoraggio spaziali utilizzano per prendere decisioni di autorizzazione per l'account e assicurarsi che solo le entità autorizzate possano accedere all'account.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.

È possibile ottenere i token di accesso in Exchange per i token o le chiavi dell'account rilasciati da Azure AD.Access tokens can be obtained in exchange for either account keys or tokens issued by Azure AD.

Le chiavi dell'account consentono di iniziare rapidamente a usare il servizio di ancoraggio spaziale di Azure.Account keys enable you to get started quickly with using the Azure Spatial Anchors service. Tuttavia, prima di distribuire l'applicazione in produzione, è consigliabile aggiornare l'app per usare l'autenticazione Azure AD.But before you deploy your application to production, we recommend that you update your app to use Azure AD authentication.

È possibile ottenere Azure AD token di autenticazione in due modi:You can obtain Azure AD authentication tokens in two ways:

  • Se si sta creando un'applicazione aziendale e l'azienda USA Azure AD come sistema di identità, è possibile usare l'autenticazione Azure AD basata sull'utente nell'app.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. Si concede quindi l'accesso agli account di ancoraggio spaziali usando i gruppi di sicurezza Azure AD esistenti.You then grant access to your Spatial Anchors accounts by using your existing Azure AD security groups. È anche possibile concedere l'accesso direttamente agli utenti dell'organizzazione.You can also grant access directly to users in your organization.
  • In caso contrario, è consigliabile ottenere Azure AD token da un servizio Web che supporta l'app.Otherwise, we recommend that you obtain Azure AD tokens from a web service that supports your app. Questo metodo è consigliato per le applicazioni di produzione perché consente di evitare di incorporare le credenziali per l'accesso agli ancoraggi spaziali di Azure nell'applicazione client.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.

Chiavi dell'accountAccount keys

Il modo più semplice per iniziare consiste nell'usare le chiavi dell'account per l'accesso all'account degli ancoraggi spaziali di Azure.The easiest way to get started is to use account keys for access to your Azure Spatial Anchors account. È possibile ottenere le chiavi dell'account nella portale di Azure.You can get your account keys on the Azure portal. Passare all'account e selezionare la scheda chiavi :Go to your account and select the Keys tab:

Screenshot che mostra la scheda chiavi con il pulsante copia per la chiave primaria evidenziata.

Sono disponibili due chiavi.Two keys are available. Entrambi sono contemporaneamente validi per l'accesso all'account di ancoraggi spaziali.Both are simultaneously valid for access to the Spatial Anchors account. Si consiglia di aggiornare regolarmente la chiave usata per accedere all'account.We recommend that you regularly update the key you use to access the account. La presenza di due chiavi valide separate Abilita questi aggiornamenti senza tempi di inattività.Having two separate valid keys enables these updates without downtime. È necessario solo aggiornare la chiave primaria e la chiave secondaria in alternativa.You only have to update the primary key and the secondary key alternatively.

L'SDK include il supporto predefinito per l'autenticazione tramite chiavi dell'account.The SDK has built-in support for authentication via account keys. È sufficiente impostare la AccountKey proprietà sull' cloudSession oggetto:You just need to set the AccountKey property on your cloudSession object:

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

Dopo aver impostato questa proprietà, l'SDK gestirà lo scambio della chiave dell'account per un token di accesso e la memorizzazione nella cache necessaria per i token per l'app.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.

Avviso

Si consiglia di usare le chiavi dell'account per il caricamento rapido, ma solo durante lo sviluppo e la creazione di prototipi.We recommend that you use account keys for quick onboarding, but only during development/prototyping. Non è consigliabile distribuire l'applicazione in produzione con una chiave di account incorporata.We don't recommend that you ship your application to production with an embedded account key in it. Usare invece gli approcci di autenticazione Azure AD basati sull'utente o sui servizi descritti di seguito.Instead, use the user-based or service-based Azure AD authentication approaches described next.

Autenticazione utente di Azure ADAzure AD user authentication

Per le applicazioni destinate Azure Active Directory utenti, si consiglia di usare un token Azure AD per l'utente.For applications that target Azure Active Directory users, we recommend that you use an Azure AD token for the user. È possibile ottenere questo token usando MSAL.You can obtain this token by using the MSAL. Seguire i passaggi nella Guida introduttiva sulla registrazione di un'app, che include:Follow the steps in the quickstart on registering an app, which include:

Nel portale di AzureIn the Azure portal

  1. Registrare l'applicazione in Azure AD come applicazione nativa.Register your application in Azure AD as a native application. Nell'ambito della registrazione, è necessario determinare se l'applicazione deve essere multi-tenant.As part of registering, you'll need to determine whether your application should be multitenant. Sarà inoltre necessario specificare gli URL di reindirizzamento consentiti per l'applicazione.You'll also need to provide the redirect URLs allowed for your application.

  2. Passare alla scheda autorizzazioni API .Go to the API permissions tab.

  3. Selezionare Aggiungi un'autorizzazione.Select Add a permission.

    1. Selezionare provider di risorse realtà mista nelle API utilizzate dall'organizzazione .Select Mixed Reality Resource Provider on the APIs my organization uses tab.
    2. Selezionare Autorizzazioni delegate.Select Delegated permissions.
    3. Selezionare mixedreality. SignIn in mixedreality.Select mixedreality.signin under mixedreality.
    4. Selezionare Aggiungi autorizzazioni.Select Add permissions.
  4. Selezionare concedi il consenso dell'amministratore.Select Grant admin consent.

  5. Concedere all'applicazione o agli utenti l'accesso alla risorsa:Grant your application or users access to your resource:

    1. Passare alla risorsa ancoraggi spaziali nella portale di Azure.Go to your Spatial Anchors resource in the Azure portal.
    2. Passare alla scheda controllo di accesso (IAM) .Go to the Access control (IAM) tab.
    3. Selezionare Aggiungi un'assegnazione di ruolo.Select Add role assignment.
    4. Selezionare un ruolo.Select a role.
    5. Nella casella Seleziona immettere i nomi degli utenti, i gruppi e/o le applicazioni a cui si desidera assegnare l'accesso.In the Select box, enter the names of the users, groups, and/or applications to which you want to assign access.
    6. Selezionare Salva.Select Save.

Nel codiceIn your code

  1. Assicurarsi di usare l'ID applicazione e l'URI di reindirizzamento dell'applicazione Azure AD per i parametri ID client e RedirectUri in MSAL.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. Impostare le informazioni relative al tenant:Set the tenant information:
    1. Se l'applicazione supporta solo l'organizzazione, sostituire questo valore con l' ID tenant o il nome del tenant.If your application supports My organization only, replace this value with your Tenant ID or Tenant name. Ad esempio, contoso.microsoft.com.For example, contoso.microsoft.com.
    2. Se l'applicazione supporta gli account in qualsiasi directory organizzativa, sostituire questo valore con le organizzazioni.If your application supports Accounts in any organizational directory, replace this value with Organizations.
    3. Se l'applicazione supporta tutti gli utenti account Microsoft, sostituire questo valore con comune.If your application supports All Microsoft account users, replace this value with Common.
  3. Nella richiesta di token impostare l' ambito su " https://sts.<account-domain>//.default ", dove <account-domain> viene sostituito con il dominio dell'account per l'account degli ancoraggi spaziali di Azure.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. Un ambito di esempio per un account di ancoraggio spaziale di Azure nel dominio dell'account Stati Uniti orientali 2 è " 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". Questo ambito indicherà ad Azure AD che l'applicazione richiede un token per il servizio token di sicurezza (STS) di Realtà mista.This scope will indicate to Azure AD that your application is requesting a token for the Mixed Reality Security Token Service (STS).

Dopo aver completato questi passaggi, l'applicazione deve essere in grado di ottenere da MSAL un token di Azure AD.After you complete these steps, your application should be able to obtain from MSAL an Azure AD token. È possibile impostare il token Azure AD come nell' authenticationToken oggetto di configurazione della sessione cloud:You can set that Azure AD token as the authenticationToken on your cloud session configuration object:

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

Autenticazione per il servizio Azure ADAzure AD service authentication

Per distribuire le app che usano gli ancoraggi spaziali di Azure nell'ambiente di produzione, è consigliabile usare un servizio back-end che effettuerà il broker delle richieste di autenticazione.To deploy apps that use Azure Spatial Anchors to production, we recommend that you use a back-end service that will broker authentication requests. Ecco una panoramica del processo:Here's an overview of the process:

Diagramma che fornisce una panoramica dell'autenticazione a ancoraggi spaziali di Azure.

In questo caso si presuppone che l'app usi un proprio meccanismo per l'autenticazione nel servizio back-end.Here, it's assumed that your app uses its own mechanism to authenticate to its back-end service. (Ad esempio, un account Microsoft, PlayFab, Facebook, un ID Google o un nome utente e una password personalizzati). Dopo l'autenticazione degli utenti nel servizio back-end, il servizio può recuperare un token di Azure AD, scambiarlo per un token di accesso per gli ancoraggi spaziali di Azure e restituirlo all'applicazione client.(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.

Il token di accesso Azure AD viene recuperato tramite MSAL.The Azure AD access token is retrieved via the MSAL. Seguire i passaggi nella Guida introduttiva per la registrazione di un'app, che include:Follow the steps in the register an app quickstart, which include:

Nel portale di AzureIn the Azure portal

  1. Registrare l'applicazione in Azure AD:Register your application in Azure AD:
    1. Nella portale di Azure selezionare Azure Active Directory, quindi selezionare registrazioni app.In the Azure portal, select Azure Active Directory, and then select App registrations.
    2. Selezionare Nuova registrazione.Select New registration.
    3. Immettere il nome dell'applicazione, impostare il tipo di applicazione su App Web/API e immettere l'URL di autenticazione per il servizio.Enter the name of your application, select Web app / API as the application type, and enter the auth URL for your service. Selezionare Crea.Select Create.
  2. Nell'applicazione selezionare Impostazioni, quindi selezionare la scheda certificati e segreti . Creare un nuovo segreto client, selezionare una durata, quindi selezionare Aggiungi.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. Assicurarsi di salvare il valore del segreto.Be sure to save the secret value. È necessario includerlo nel codice del servizio Web.You'll need to include it in your web service's code.
  3. Concedere all'applicazione e/o agli utenti l'accesso alla risorsa:Grant your application and/or users access to your resource:
    1. Passare alla risorsa ancoraggi spaziali nella portale di Azure.Go to your Spatial Anchors resource in the Azure portal.

    2. Passare alla scheda controllo di accesso (IAM) .Go to the Access control (IAM) tab.

    3. Selezionare Aggiungi un'assegnazione di ruolo.Select Add role assignment.

    4. Selezionare un ruolo.Select a role.

    5. Nella casella Seleziona immettere il nome o i nomi delle applicazioni a cui si desidera assegnare l'accesso.In the Select box, enter the name or names of the applications to which you want to assign access. Se si vuole che gli utenti dell'app abbiano ruoli diversi rispetto all'account degli ancoraggi spaziali, registrare più applicazioni nel Azure AD e assegnare un ruolo separato a ciascuna di esse.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. Quindi implementare la logica di autorizzazione in modo che venga usato il ruolo degli utenti corretto.Then implement your authorization logic to use the right role for your users.

      Nota

      Nel riquadro Aggiungi assegnazione ruolo , in assegna accesso a Selezionare Azure ad utente, gruppo o entità servizio.In the Add role assignment pane, in Assign access to, select Azure AD user, group, or service principal.

    6. Selezionare Salva.Select Save.

Nel codiceIn your code

Nota

È possibile usare l' esempio di servizio disponibile come parte delle app di esempio di ancoraggi spaziali.You can use the service sample that is available as a part of the Spatial Anchors sample apps.

  1. Assicurarsi di usare l'ID applicazione, il segreto applicazione e l'URI di reindirizzamento dell'applicazione Azure AD come i parametri ID client, segreto e RedirectUri in MSAL.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. Impostare l'ID tenant sul proprio Azure AD ID tenant nel parametro Authority in MSAL.Set the tenant ID to your own Azure AD tenant ID in the authority parameter in MSAL.
  3. Nella richiesta di token impostare l' ambito su " https://sts.<account-domain>//.default ", dove <account-domain> viene sostituito con il dominio dell'account per l'account degli ancoraggi spaziali di Azure.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. Un ambito di esempio per un account di ancoraggio spaziale di Azure nel dominio dell'account Stati Uniti orientali 2 è " 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".

Dopo aver completato questi passaggi, il servizio back-end può recuperare un token di Azure AD.After you complete these steps, your back-end service can retrieve an Azure AD token. Il token potrà quindi essere scambiato con un token MR che verrà restituito al client.It can then exchange it for an MR token that it will return back to the client. Il recupero di un token MR tramite un token di Azure AD viene eseguito tramite una chiamata REST.Using an Azure AD token to retrieve an MR token is done via a REST call. Ecco una chiamata di esempio: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"}

L'intestazione Authorization è formattata come indicato di seguito: Bearer <Azure_AD_token>The Authorization header is formatted as follows: Bearer <Azure_AD_token>

La risposta contiene il token MR in testo normale.The response contains the MR token in plain text.

Il token MR viene restituito al client.That MR token is then returned to the client. L'app client può quindi impostarla come token di accesso nella configurazione di sessione cloud:Your client app can then set it as its access token in the cloud session configuration:

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

Controllo degli accessi in base al ruolo di AzureAzure role-based access control

Per consentire di controllare il livello di accesso concesso a applicazioni, servizi o Azure AD utenti del servizio, è possibile assegnare questi ruoli preesistenti in base alle esigenze per gli account di ancoraggio spaziali di Azure: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:

  • Proprietario dell'account di ancoraggi spaziali.Spatial Anchors Account Owner. Le applicazioni o gli utenti che dispongono di questo ruolo possono creare ancoraggi spaziali, eseguire query per tali elementi ed eliminarli.Applications or users that have this role can create spatial anchors, query for them, and delete them. Quando si esegue l'autenticazione all'account usando le chiavi dell'account, il ruolo di proprietario dell'account di ancoraggi spaziali viene assegnato all'entità autenticata.When you authenticate to your account by using account keys, the Spatial Anchors Account Owner role is assigned to the authenticated principal.
  • Collaboratore account di ancoraggi spaziali.Spatial Anchors Account Contributor. Le applicazioni o gli utenti che dispongono di questo ruolo possono creare ancoraggi spaziali ed eseguire query su di essi, ma non possono eliminarli.Applications or users that have this role can create spatial anchors and query for them, but they can't delete them.
  • Lettore di account di ancoraggi spaziali.Spatial Anchors Account Reader. Le applicazioni o gli utenti con questo ruolo possono eseguire query solo per gli ancoraggi spaziali.Applications or users that have this role can only query for spatial anchors. Non possono crearne di nuovi, eliminare quelli esistenti o aggiornarne i metadati.They can't create new ones, delete existing ones, or update metadata on them. Questo ruolo viene in genere usato per le applicazioni in cui alcuni utenti curano l'ambiente, ma altri possono richiamare solo gli ancoraggi precedentemente posizionati nell'ambiente.This role is typically used for applications where some users curate the environment but others can only recall anchors previously placed in the environment.

Passaggi successiviNext steps

Creare la prima app con gli ancoraggi spaziali di Azure:Create your first app with Azure Spatial Anchors: