Autenticação e autorização para Âncoras Espaciais do Azure

  • Artigo

Neste artigo, você aprenderá as várias maneiras de se autenticar nas Âncoras Espaciais do Azure em seu aplicativo ou serviço Web. Você também aprenderá sobre as maneiras de usar o controle de acesso baseado em função do Azure (RBAC do Azure) na ID do Microsoft Entra para controlar o acesso às suas contas de Âncoras Espaciais.

Aviso

Recomendamos que você use chaves de conta para integração rápida, mas somente durante o desenvolvimento/a prototipagem. Não recomendamos que você envie seu aplicativo para produção com uma chave de conta inserida nele. Em vez disso, use as abordagens de autenticação do Microsoft Entra baseadas em usuário ou serviço descritas a seguir.

Visão geral

Diagram that shows an overview of authentication to Azure Spatial Anchors.

Para acessar uma determinada conta de Âncoras Espaciais do Azure, os clientes precisam primeiro obter um token de acesso do STS (serviço de token de segurança) da Realidade Misturada do Azure. Os tokens obtidos do STS têm um tempo de vida de 24 horas. Eles contêm informações que os serviços de Âncoras Espaciais usam para tomar decisões de autorização na conta e garantir que apenas entidades de segurança autorizadas possam acessar essa conta.

Os tokens de acesso podem ser obtidos em troca de chaves de conta ou tokens emitidos pelo Microsoft Entra ID.

As chaves de conta permitem que você comece rapidamente com o uso do serviço de Âncoras Espaciais do Azure. Mas antes de implantar seu aplicativo em produção, recomendamos que você atualize seu aplicativo para usar a autenticação do Microsoft Entra.

Você pode obter tokens de autenticação do Microsoft Entra de duas maneiras:

  • Se você estiver criando um aplicativo corporativo e sua empresa estiver usando o Microsoft Entra ID como seu sistema de identidade, poderá usar a autenticação do Microsoft Entra baseada em usuário em seu aplicativo. Em seguida, você concede acesso às suas contas de Âncoras Espaciais usando os grupos de segurança existentes do Microsoft Entra. Você também pode permitir acesso diretamente aos usuários em sua organização.
  • Caso contrário, recomendamos que você obtenha tokens do Microsoft Entra de um serviço Web que ofereça suporte ao seu aplicativo. Recomendamos esse método para aplicativos de produção porque ele permite evitar a inserção das credenciais para acesso às Âncoras Espaciais do Azure em seu aplicativo cliente.

Chaves de conta

A maneira mais fácil de começar é usar chaves de conta para acesso à sua conta das Âncoras Espaciais do Azure. Você obtém as chaves de conta no portal do Azure. Acesse sua conta e selecione a guia Chaves:

Screenshot that shows the Keys tab with the Copy button for the Primary key highlighted.

Duas chaves estão disponíveis. Elas são simultaneamente válidas para acesso à conta de Âncoras Espaciais. Recomendamos que você atualize regularmente a chave usada para acessar a conta. Ter duas chaves válidas separadas permite realizar essas atualizações sem tempo de inatividade. Você só precisa atualizar a chave primária e a chave secundária como alternativa.

O SDK tem suporte integrado para autenticação por meio de chaves de conta. Você só precisa definir a propriedade AccountKey no objeto cloudSession:

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

Após definir essa propriedade, o SDK vai lidar com a troca da chave de conta para um token de acesso e o cache de tokens necessário para seu aplicativo.

Autenticação de usuário do Microsoft Entra

Para aplicativos destinados a usuários do Microsoft Entra, recomendamos que você use um token do Microsoft Entra para o usuário. Obtenha esse token usando a MSAL. Siga as etapas no guia de início rápido para registrar um aplicativo, que inclui:

No portal do Azure

  1. Registre seu aplicativo no Microsoft Entra ID como um aplicativo nativo. Como parte do registro, você precisará determinar se o aplicativo deve ser multilocatário. Você também precisará fornecer as URLs de redirecionamento permitidas para seu aplicativo.

  2. Acesse a guia permissões de API.

  3. Selecione Adicionar uma permissão.

    1. Selecione Provedor de Recursos de Realidade Misturada na guia APIs que minha organização usa.
    2. Selecione Permissões delegadas.
    3. Selecione mixedreality.signin em mixedreality.
    4. Selecione Adicionar Permissões.

  4. Selecione Conceder consentimento do administrador.

  5. Atribua uma função RBAC do ASA ao aplicativo ou aos usuários que você deseja conceder acesso ao recurso. Se você quiser que os usuários do aplicativo tenham funções diferentes em relação à conta ASA, registre vários aplicativos na ID do Microsoft Entra e atribua uma função separada a cada um. Em seguida, implemente sua lógica de autorização para usar a função certa para seus usuários. Para ver as etapas detalhadas de atribuição de função, confira Atribuir funções do Azure usando o portal do Azure.

No seu código

  1. Certifique-se de usar a ID do aplicativo e redirecionar o URI do seu próprio aplicativo Microsoft Entra para a ID do cliente e os parâmetros RedirectUri no MSAL.
  2. Defina as informações do locatário:
    1. Se o seu aplicativo der suporte a Somente minha organização, substitua esse valor pela ID do locatário ou pelo Nome do locatário. Por exemplo, contoso.microsoft.com.
    2. Se o aplicativo der suporte a Contas em qualquer diretório organizacional, substitua esse valor por Organizações.
    3. Se o aplicativo der suporte a Todos os usuários de contas Microsoft, substitua esse valor por Comum.
  3. Em sua solicitação de token, defina o escopo como https://sts.mixedreality.azure.com//.default. Esse escopo indicará ao Microsoft Entra ID que seu aplicativo está solicitando um token para o STS (Serviço de Token de Segurança) de Realidade Mista.

Depois de concluir essas etapas, seu aplicativo deve ser capaz de obter do MSAL um token do Microsoft Entra. Você pode definir esse token do Microsoft Entra como o objeto de configuração da authenticationToken sessão na nuvem:

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

Autenticação do serviço Microsoft Entra

Para implantar aplicativos que usam Âncoras Espaciais do Azure em produção, recomendamos que você use um serviço de back-end que atenderá às solicitações de autenticação do agente. Veja a seguir uma visão geral do processo:

Diagram that provides an overview of authentication to Azure Spatial Anchors.

Aqui, supõe-se que seu aplicativo use o próprio mecanismo para autenticar no serviço de back-end. (Por exemplo, uma conta da Microsoft, PlayFab, Facebook, um ID do Google ou um nome de usuário e senha personalizados.) Depois que os usuários forem autenticados em seu serviço de back-end, esse serviço poderá recuperar um token do Microsoft Entra, trocá-lo por um token de acesso para Âncoras Espaciais do Azure e devolvê-lo ao seu aplicativo cliente.

O token de acesso do Microsoft Entra é recuperado por meio do MSAL. Siga as etapas no Início rápido para registrar um aplicativo, que incluem:

No portal do Azure

  1. Registre seu aplicativo no Microsoft Entra ID:
    1. No portal do Azure, selecione Microsoft Entra ID e, em seguida, selecione Registros de aplicativo.
    2. Selecione Novo registro.
    3. Insira o nome do seu aplicativo, selecione aplicativo Web/API como o tipo de aplicativo e insira a URL de autenticação para seu serviço. Selecione Criar.
  2. No aplicativo, selecione Configurações e, em seguida, selecione a guia Certificados e segredos. Crie um segredo do cliente, selecione uma duração e, em seguida, selecione Adicionar. Não se esqueça de salvar o valor do segredo. Você precisará incluí-lo no código do serviço Web.
  3. Atribua uma função RBAC do ASA ao aplicativo ou aos usuários que você deseja conceder acesso ao recurso. Se você quiser que os usuários do aplicativo tenham funções diferentes em relação à conta ASA, registre vários aplicativos na ID do Microsoft Entra e atribua uma função separada a cada um. Em seguida, implemente sua lógica de autorização para usar a função certa para seus usuários. Para ver as etapas detalhadas de atribuição de função, confira Atribuir funções do Azure usando o portal do Azure.

No seu código

Observação

Você pode usar o exemplo de serviço que está disponível como parte dos aplicativos de exemplo de Âncoras Espaciais.

  1. Certifique-se de usar a ID do aplicativo, o segredo do aplicativo e o URI de redirecionamento do seu próprio aplicativo Microsoft Entra como a ID do cliente, o segredo e os parâmetros RedirectUri no MSAL.
  2. Defina a ID do locatário como sua própria ID de locatário do Microsoft Entra no parâmetro authority no MSAL.
  3. Em sua solicitação de token, defina o escopo como https://sts.mixedreality.azure.com//.default.

Depois de concluir essas etapas, seu serviço de back-end pode recuperar um token do Microsoft Entra. Em seguida, ele pode alterá-lo para um token MR que ele retornará ao cliente. O uso de um token Microsoft Entra para recuperar um token MR é feito por meio de uma chamada REST. Aqui está uma chamada de exemplo:

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

O Cabeçalho de autorização é formatado da seguinte maneira: Bearer <Azure_AD_token>

A resposta contém o token MR em texto sem formatação.

Esse token MR é retornado para o cliente. Seu aplicativo cliente pode defini-lo como token de acesso na configuração da sessão de nuvem:

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

Controle de acesso baseado em função do Azure

Para ajudá-lo a controlar o nível de acesso concedido a aplicativos, serviços ou usuários do Microsoft Entra do seu serviço, você pode atribuir essas funções pré-existentes, conforme necessário, em suas contas do Azure Spatial Anchors:

  • Proprietário da Conta de Âncoras Espaciais. Os aplicativos ou usuários que têm essa função podem criar âncoras espaciais, consultá-las e excluí-las. Quando você se autentica em sua conta usando chaves de conta, a função Proprietário da Conta de Âncoras Espaciais é atribuída à entidade de segurança autenticada.
  • Colaborador da Conta de Âncoras Espaciais. Os aplicativos ou usuários que têm essa função podem criar âncoras espaciais e consultá-las, mas não podem excluí-las.
  • Leitor da Conta de Âncoras Espaciais. Aplicativos ou usuários que têm essa função só podem consultar âncoras espaciais. Eles não podem criar, não podem excluir as existentes nem atualizar metadados nelas. Normalmente, essa função é usada para aplicativos em que alguns usuários coletam o ambiente, mas outros só podem recuperar âncoras previamente colocadas nesse ambiente.

Próximas etapas

Criar seu primeiro aplicativo com Âncoras Espaciais do Azure:

Unity (HoloLens)

Unity (iOS)

Unity (Android)

iOS

Android

HoloLens

Xamarin (Android)

Xamarin (iOS)