Autenticación y autorización en Azure Spatial AnchorsAuthentication and authorization to Azure Spatial Anchors

En esta sección, trataremos las diversas maneras en las que puede autenticarse en Azure Spatial Anchors desde la aplicación o servicio web y las formas en que puede usar el Control de acceso basado en roles de Azure Directory (Azure AD) para controlar el acceso a las cuentas de Spatial Anchors.In this section, we will cover the various ways you can authenticate to Azure Spatial Anchors from your app or web service, and the ways in which you can use Role-Based Access Control in Azure Directory (Azure AD) to control access to your Spatial Anchors accounts.

Información generalOverview

Introducción a la autenticación y autorización en Azure Spatial Anchors

Para obtener acceso a una determinada cuenta de Azure Spatial Anchors, los clientes deben obtener primero un token de acceso del servicio de token de seguridad (STS) de Azure Mixed Reality.To access a given Azure Spatial Anchors account, clients need to first obtain an access token from Azure Mixed Reality Security Token Service (STS). Los tokens obtenidos de STS se publican durante 24 horas e incluyen información de los servicios de Spatial Anchors para tomar decisiones de autorización acerca de la cuenta y asegurarse de que solo entidades de seguridad autorizadas pueden tener acceso a esta.Tokens obtained from STS live for 24 hours, and contain information for the Spatial Anchors services to make authorization decisions on the account, and ensure that only authorized principals can access that account.

Los tokens de acceso pueden obtenerse a cambio de claves de cuenta o desde los tokens emitidos por Azure AD.Access tokens can be obtained in exchange from either account keys, or from Azure AD-issued tokens.

Las claves de cuenta le permiten comenzar rápidamente a usar el servicio de Azure Spatial Anchors; sin embargo, antes de implementar la aplicación en producción, se recomienda que la actualice para usar la autenticación basada en Azure AD.Account keys enable you to get quickly started on using the Azure Spatial Anchors service; however, before you deploy your application to production, it is advised that you update your app to use Azure AD-based authentication.

Los tokens de autenticación de Azure AD pueden obtenerse de dos maneras:Azure AD authentication tokens can be obtained two ways:

  • Si está creando una aplicación empresarial y la empresa usa Azure AD como sistema de identidad, puede usar la autenticación de Azure AD basada en el usuario en la aplicación y conceder acceso a las cuentas de Spatial Anchors mediante los grupos de seguridad existentes de Azure AD o directamente a los usuarios de la organización.If you are building an enterprise application, and your company is using Azure AD as its identity system, you may use user-based Azure AD authentication in your app, and grant access to your spatial anchors accounts using your existing Azure AD security groups, or directly to users in your organization.
  • En caso contrario, se recomienda que obtenga los tokens de Azure AD desde un servicio web compatible con la aplicación.Otherwise, it is recommended that you obtain Azure AD tokens from a web service supporting your app. El uso de un servicio web compatible es el método de autenticación recomendado para las aplicaciones de producción, ya que evita la incrustación de las credenciales para tener acceso a Azure Spatial Anchors en la aplicación cliente.Using a supporting web service is the recommended method of authentication for production applications, as it avoids embedding the credentials for accessing Azure Spatial Anchors in your client application.

Claves de cuentaAccount keys

El uso de claves de cuenta para tener acceso a la cuenta de Azure Spatial Anchors es la manera más sencilla de comenzar.Using account keys for access to your Azure Spatial Anchors account is the simplest way to get started. Encontrará las claves de cuenta en Azure Portal.You will find your account keys on the Azure portal. Vaya a la cuenta y seleccione la pestaña "Claves".Navigate to your account, and select the “Keys” tab.

Introducción a la autenticación y autorización en Azure Spatial Anchors

Se ponen a disposición dos claves, ambas válidas simultáneamente para tener acceso a la cuenta de Spatial Anchors.Two keys are made available, which are both simultaneously valid for access to the Spatial Anchors account. Se recomienda que actualice periódicamente la clave que usa para tener acceso a la cuenta, que tenga dos claves válidas independientes como actualizaciones sin tiempo de inactividad y que solo deba actualizar la clave principal y la clave secundaria de manera alternativa.It is recommended that you regularly update the key you use to access the account; having two separate valid keys enable such updates without downtime; you only have to update alternatively the primary key and the secondary key.

El SDK tiene compatibilidad integrada para la autenticación con claves de cuenta; basta con establecer la propiedad AccountKey en el objeto cloudSession.The SDK has built-in support for authenticating with account keys; you simply need to set the AccountKey property on your cloudSession object.

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

Una vez hecho esto, el SDK controlará el intercambio de la clave de cuenta para un token de acceso, así como el almacenamiento en caché necesaria de tokens para la aplicación.Once that is done, the SDK will handle the exchange of the account key for an access token, and the necessary caching of tokens for your app.

Advertencia

Se recomienda el uso de claves de cuenta para una incorporación rápida, pero solo durante el desarrollo y la creación de prototipos.Use of account keys is recommended for quick on-boarding, but during development/prototyping only. Se recomienda encarecidamente no enviar la aplicación a producción mediante una clave de cuenta incrustada en ella; en su lugar, use los enfoques de autenticación de Azure AD basada en el usuario o en el servicio que se incluyen a continuación.It is strongly recommended not to ship your application to production using an embedded account key in it, and to instead use the user-based or service-based Azure AD authentication approaches listed next.

Autenticación de usuario de Azure ADAzure AD user authentication

En el caso de las aplicaciones que tienen como destino a usuarios de Azure Active Directory, el enfoque recomendado consiste en usar un token de Azure AD para el usuario, que se puede obtener mediante la biblioteca de MSAL.For applications targeting Azure Active Directory users, the recommended approach is to use an Azure AD token for the user, which you can obtain using the MSAL library. Debe seguir los pasos que se indican en la guía de inicio rápido para registrar una aplicación, que incluyen:You should follow the steps listed the register an app quickstart, which include:

  1. Configuración en Azure PortalConfiguration in Azure portal
    1. Registre la aplicación en Azure AD como Aplicación nativa.Register your application in Azure AD as Native application. Como parte del registro, deberá determinar si la aplicación debe ser multiempresa, así como proporcionar las direcciones URL de redireccionamiento permitidas para la aplicación.As part of registering, you will need to determine whether your application should be multi-tenant or not, and provide the redirect URLs allowed for your application.
      1. Cambie a la pestaña Permisos de API.Switch to the API permissions tab
      2. Seleccione Agregar un permiso.Select Add a permission
        1. Seleccione Mixed Reality Resource Provider (Proveedor de recursos de realidad mixta) en la pestaña API usadas en mi organización.Select Mixed Reality Resource Provider under APIs my organization uses tab
        2. Seleccione Permisos delegados.Select Delegated permissions
        3. Active la casilla mixedreality.signin en mixedrealityCheck the box for mixedreality.signin under mixedreality
        4. Seleccione Agregar permisos.Select Add permissions
      3. Seleccione Conceder consentimiento de administrador.Select Grant admin consent
    2. Conceda acceso a la aplicación o a los usuarios para el recurso:Grant your application or users access to your resource:
      1. Vaya al recurso de Spatial Anchors en Azure Portal.Navigate to your Spatial Anchors resource in Azure portal
      2. Cambie a la pestaña Control de acceso (IAM) .Switch to the Access control (IAM) tab
      3. Presione Agregar asignación de roles.Hit Add role assignment
        1. Seleccionar un rol.Select a role
        2. En el campo Seleccionar, escriba el nombre de los usuarios, grupos o aplicaciones a los que quiere asignar acceso.In the Select field, enter the name of the user(s), group(s), and/or application(s) to which you want to assign access.
        3. Presione Guardar.Hit Save.
  2. En el código:In your code:
    1. Asegúrese de usar el Id. de aplicación y el URI de redirección de la propia aplicación de Azure AD como parámetros de Id. de cliente y RedirectUri de ADAL.Make sure to use the application ID and redirect Uri of your own Azure AD application as the client ID and RedirectUri parameters in ADAL
    2. Establezca la información del inquilino:Set the tenant information:
      1. Si la aplicación admite Solo mi organización, reemplace este valor por el identificador de inquilino o el nombre de inquilino (por ejemplo, contoso.microsoft.com).If your application supports My organization only, replace this value with your Tenant ID or Tenant name (for example, contoso.microsoft.com)
      2. Si la aplicación admite Cuentas en cualquier directorio organizativo, reemplace este valor por Organizaciones.If your application supports Accounts in any organizational directory, replace this value with Organizations
      3. Si la aplicación admite Todos los usuarios de cuentas Microsoft, reemplace este valor porComún.If your application supports All Microsoft account users, replace this value with Common
    3. En la solicitud de token, establezca el recurso en "https://sts.mixedreality.azure.com".On your token request, set the resource to "https://sts.mixedreality.azure.com". Este "recurso" indicará a Azure AD que la aplicación solicita un token para el servicio de Azure Spatial Anchors.This "resource" will indicate to Azure AD that your application is requesting a token for the Azure Spatial Anchors service.

De este modo, la aplicación podrá obtener de MSAL un token de Azure AD; dicho token de Azure AD se puede establecer como authenticationToken en el objeto de configuración de la sesión en la nube.With that, your application should be able to obtain from MSAL an Azure AD token; you can set that Azure AD token as the authenticationToken on your cloud session config object.

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

Autenticación de servicio de Azure ADAzure AD service authentication

La opción recomendada para implementar aplicaciones mediante el aprovechamiento de Azure Spatial Anchors en producción consiste en aprovechar un servicio back-end que gestione las solicitudes de autenticación.The recommended option to deploy apps leveraging Azure Spatial Anchors to production is to leverage a backend service that will broker authentication requests. El esquema general debe ser como se describe en este diagrama:The general scheme should be as described in this diagram:

Introducción a la autenticación y autorización en Azure Spatial Anchors

En este caso, se supone que la aplicación usa su propio mecanismo (por ejemplo: cuenta de Microsoft, PlayFab, Facebook, Id. de Google, nombre de usuario/contraseña personalizado, etc.) para autenticarse en su servicio back-end.Here, it is assumed that your app uses its own mechanism (for example: Microsoft account, PlayFab, Facebook, Google ID, custom username/password, etc.) to authenticate to its backend service. Una vez que los usuarios se autentican en el servicio back-end, dicho servicio puede recuperare un token de Azure AD, cambiarlo por un token de acceso para Azure Spatial Anchors y devolverlo a la aplicación cliente.Once your users are authenticated to your backend 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.

El token de acceso de Azure AD se recupera mediante la biblioteca de MSAL.The Azure AD access token is retrieved using the MSAL library. Debe seguir los pasos que se indican en la guía de inicio rápido para registrar una aplicación, que incluyen:You should follow the steps listed the register an app quickstart, which include:

  1. Configuración en Azure Portal:Configuration in Azure portal:
    1. Registre la aplicación en Azure AD:Register your application in Azure AD:
      1. En Azure Portal, vaya a Azure Active Directory y seleccione Registros de aplicaciones.In Azure portal, navigate to Azure Active Directory, and select app registrations
      2. Seleccione Nuevo registro de aplicaciones.Select new application registration
      3. Escriba el nombre de la aplicación, seleccione Aplicación web o API como tipo de aplicación y escriba la dirección URL de autenticación para el servicio.Enter the name of your application, select Web app / API as the application type, and enter the auth URL for your service. A continuación, presione Crear.Then hit Create.
      4. En esa aplicación, presione Configuración y, a continuación, seleccione la pestaña Claves. Escriba el nombre de la clave, seleccione una duración y presione Guardar.On that application, hit Settings, then select the Keys tab. Enter the name of your key, select a duration, and hit Save. Asegúrese de guardar el valor de clave que se muestra en ese momento, ya que lo necesitará para incluirlo en el código del servicio web.Make sure to save the key value that is displayed at that time, as you will need to include it in your web service’s code.
    2. Conceda acceso a la aplicación o a los usuarios para el recurso:Grant your application and/or users access to your resource:
      1. Vaya al recurso de Spatial Anchors en Azure Portal.Navigate to your Spatial Anchors resource in Azure portal
      2. Cambie a la pestaña Control de acceso (IAM) .Switch to the Access control (IAM) tab
      3. Presione Agregar asignación de roles.Hit Add role assignment
      4. Seleccionar un rol.Select a role
      5. En el campo Seleccionar, escriba el nombre de las aplicaciones que ha creado y a las que quiere asignar acceso.In the select field, enter the name of the application(s) you created and to which you want to assign access. Si quiere que los usuarios de la aplicación tengan distintos roles en la cuenta de Spatial Anchors, debe registrar varias aplicaciones en Azure AD y asignar a cada una un rol independiente.If you want your app’s users to have different roles against the Spatial Anchors account, you should register multiple applications in Azure AD, and assign to each a separate role. A continuación, implemente la lógica de autorización para usar el rol correcto para los usuarios.Then implement your authorization logic to use the right role for your users.
    3. Presione Guardar.Hit Save.
  2. En el código (nota: puede usar el servicio de ejemplo incluido en GitHub):In your code (note: you can use the service sample included on GitHub):
    1. Asegúrese de usar el Id. de aplicación, el secreto de aplicación y el URI de redirección de la propia aplicación de Azure AD como parámetros de Id. de cliente, secreto y RedirectUri de ADAL.Make 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 ADAL
    2. Establezca el id. de inquilino en su propio id. de inquilino de Azure AD en el parámetro de autoridad de ADAL.Set the tenant ID to your own AAAzure ADD tenant ID in the authority parameter in ADAL
    3. En la solicitud de token, establezca el recurso en "https://sts.mixedreality.azure.com".On your token request, set the resource to "https://sts.mixedreality.azure.com"

Con esto, el servicio back-end puede recuperar un token de Azure AD.With that, your backend service can retrieve an Azure AD token. A continuación, puede cambiarlo por un token de MR que va a devolver al cliente.It can then exchange it for an MR token that it will return back to the client. El uso de un token de Azure AD para recuperar un token de MR se realiza a través de una llamada de REST.Using an Azure AD token to retrieve an MR token is done via a REST call. A continuación, se muestra una llamada de ejemplo:Here is a sample call:

GET https://mrc-auth-prod.trafficmanager.net/Accounts/35d830cb-f062-4062-9792-d6316039df56/token HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni<truncated>FL8Hq5aaOqZQnJr1koaQ
Host: mrc-auth-prod.trafficmanager.net
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"}

El encabezado de autorización tiene el formato siguiente: Bearer <accoundId>:<accountKey>Where the Authorization header is formatted as follows: Bearer <accoundId>:<accountKey>

Y la respuesta contiene el token de MR en texto sin formato.And the response contains the MR token in plain text.

Ese token de MR se devuelve después al cliente.That MR token is then returned to the client. La aplicación cliente, a continuación, puede establecerlo como su token de acceso en la configuración de la sesión en la nube.Your client app can then set it as its access token in the cloud session config.

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

Control de acceso basado en rolRole-based access control

Para ayudar a controlar el nivel de acceso concedido a las aplicaciones, los servicios o los usuarios de Azure AD de su servicio, se crearon los siguientes roles de asignación según fue necesario en las cuentas de Azure Spatial Anchors:To help control the level of access granted to applications, services or Azure AD users of your service, the following roles have been created for you to assign as needed against your Azure Spatial Anchors accounts:

  • Propietario de cuenta de Spatial Anchors: las aplicaciones o los usuarios que tienen este rol pueden crear anclajes espaciales, realizar consultas y eliminarlos.Spatial Anchors Account Owner: applications or users that have this role are able to create spatial anchors, query for them, and delete them. Al autenticarse en la cuenta mediante claves de cuenta, el rol Propietario de cuenta de Spatial Anchors se asigna a la entidad de seguridad autenticada.When you authenticate to your account using account keys, the Spatial Anchors Account Owner role is assigned to the authenticated principal.
  • Colaborador de cuenta de Spatial Anchors: las aplicaciones o los usuarios que tienen este rol pueden crear anclajes espaciales y realizar consultas, pero no pueden eliminarlos.Spatial Anchors Account Contributor: applications or users that have this role are able to create spatial anchors, query for them, but cannot delete them.
  • Lector de cuenta de Spatial Anchors: las aplicaciones o los usuarios que tienen este rol solo pueden realizar consultas para los anclajes espaciales, pero no pueden crear otros nuevos, eliminar los existentes ni actualizar los metadatos de dichos anclajes espaciales.Spatial Anchors Account Reader: applications or users that have this role are only able to query for spatial anchors, but cannot create new ones, delete existing ones, or update metadata on spatial anchors. Esto se utiliza normalmente para las aplicaciones en las que algunos usuarios ajustan el entorno, mientras que otros solo pueden recuperar los anclajes colocados anteriormente en ese entorno.This is typically used for applications where some users curate the environment, while others can only recall anchors previously placed in that environment.

Pasos siguientesNext steps

Cree su primera aplicación con Azure Spatial Anchors.Create your first app with Azure Spatial Anchors.