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

Artigo
10/18/2023

Neste artigo, você aprenderá as várias maneiras de autenticar as Âncoras Espaciais do Azure a partir do 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 (Azure RBAC) 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 apenas durante o desenvolvimento/prototipagem. Não recomendamos que você envie seu aplicativo para produção com uma chave de conta incorporada. Em vez disso, use as abordagens de autenticação do Microsoft Entra baseadas no usuário ou no serviço descritas a seguir.

Descrição geral

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

Para acessar uma determinada conta do Azure Spatial Anchors, os clientes precisam primeiro obter um token de acesso do Serviço de Token de Segurança (STS) do Azure Mixed Reality. Os tokens obtidos do STS têm uma vida útil de 24 horas. Eles contêm informações que os serviços da Spatial Anchors usam para tomar decisões de autorização na conta e garantir que apenas entidades autorizadas possam acessar a 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 a usar o serviço Âncoras Espaciais do Azure. Mas antes de implantar seu aplicativo na 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, você poderá usar a autenticação do Microsoft Entra baseada no usuário em seu aplicativo. Em seguida, você concede acesso às suas contas do Spatial Anchors usando seus grupos de segurança existentes do Microsoft Entra. Você também pode conceder 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 que você evite incorporar as credenciais de 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 acessar sua conta do Azure Spatial Anchors. Você pode obter suas chaves de conta no portal do Azure. Aceda à sua conta e selecione o separador Chaves :

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

Duas chaves estão disponíveis. Ambos são simultaneamente válidos para acesso à conta Spatial Anchors. Recomendamos que atualize regularmente a chave que utiliza para aceder à conta. Ter duas chaves válidas separadas permite essas atualizações sem tempo de inatividade. Você só precisa atualizar a chave primária e a chave secundária alternativamente.

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

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

_cloudSession.configuration.accountKey = @"MyAccountKey";

_cloudSession!.configuration.accountKey = "MyAccountKey"

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

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

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

Depois de definir essa propriedade, o SDK manipulará a troca da chave da conta por um token de acesso e o cache necessário de tokens 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. Você pode obter esse token usando o MSAL. Siga as etapas no início rápido para registrar um aplicativo, que incluem:

No portal do Azure

Registe a sua aplicação no Microsoft Entra ID como uma aplicação nativa. Como parte do registro, você precisará determinar se seu aplicativo deve ser multilocatário. Você também precisará fornecer as URLs de redirecionamento permitidas para seu aplicativo.
Vá para a guia Permissões da API.
Selecione Adicionar uma permissão.
1. Selecione Provedor de Recursos de Realidade Mista na guia APIs que minha organização usa .
2. Selecione Permissões delegadas.
3. Selecione mixedreality.signin em mixedreality.
4. Selecione Adicionar permissões.
Selecione Conceder consentimento do administrador.
Atribua uma função RBAC ASA ao aplicativo ou usuários aos quais você deseja dar acesso ao seu recurso. Se você quiser que os usuários do seu aplicativo tenham funções diferentes em relação à conta ASA, registre vários aplicativos no Microsoft Entra ID 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 obter etapas detalhadas de atribuição de função, consulte Atribuir funções do Azure usando o portal do Azure.

No seu código

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.
Defina as informações do locatário:
1. Se a sua aplicação suportar apenas A Minha organização, substitua este valor pelo seu ID de Inquilino ou Nome do Inquilino. Por exemplo, contoso.microsoft.com.
2. Se seu aplicativo oferecer suporte a Contas em qualquer diretório organizacional, substitua esse valor por Organizações.
3. Se a sua aplicação suportar Todos os utilizadores da conta Microsoft, substitua este valor por Comum.
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 da MSAL um token Microsoft Entra. Você pode definir esse token do Microsoft Entra como o authenticationToken objeto de configuração da sessão na nuvem:

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

_cloudSession.configuration.authenticationToken = @"MyAuthenticationToken";

_cloudSession!.configuration.authenticationToken = "MyAuthenticationToken"

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

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

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

Autenticação do serviço Microsoft Entra

Para implantar aplicativos que usam as Âncoras Espaciais do Azure na produção, recomendamos que você use um serviço back-end que agenciará solicitações de autenticação. Aqui está uma visão geral do processo:

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

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

O token de acesso do Microsoft Entra é recuperado através do MSAL. Siga as etapas no início rápido de registrar um aplicativo, que incluem:

No portal do Azure

Registe a sua candidatura no Microsoft Entra ID:
1. No portal do Azure, selecione Microsoft Entra ID e, em seguida, selecione Registos de aplicações.
2. Selecione Novo registo.
3. Digite o nome do seu aplicativo, selecione Web app / API como o tipo de aplicativo e insira a URL de autenticação para o seu serviço. Selecione Criar.
No aplicativo, selecione Configurações e, em seguida, selecione a guia Certificados e segredos. Crie um novo segredo de cliente, selecione uma duração e, em seguida, selecione Adicionar. Certifique-se de salvar o valor secreto. Você precisará incluí-lo no código do seu serviço Web.
Atribua uma função RBAC ASA ao aplicativo ou usuários aos quais você deseja dar acesso ao seu recurso. Se você quiser que os usuários do seu aplicativo tenham funções diferentes em relação à conta ASA, registre vários aplicativos no Microsoft Entra ID 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 obter etapas detalhadas de atribuição de função, consulte Atribuir funções do Azure usando o portal do Azure.

No seu código

Nota

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

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.
Defina a ID do locatário como sua própria ID de locatário do Microsoft Entra no parâmetro de autoridade no MSAL.
Em sua solicitação de token, defina o escopo como https://sts.mixedreality.azure.com//.default.

Depois de concluir essas etapas, seu serviço back-end pode recuperar um token do Microsoft Entra. Ele pode então trocá-lo por 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á um exemplo de chamada:

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 Autorização é formatado da seguinte forma: Bearer <Azure_AD_token>

A resposta contém o token MR em texto simples.

Esse token MR é então devolvido ao cliente. Seu aplicativo cliente pode defini-lo como seu token de acesso na configuração de sessão na nuvem:

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

_cloudSession.configuration.accessToken = @"MyAccessToken";

_cloudSession!.configuration.accessToken = "MyAccessToken"

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

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

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

Controlo de acesso baseado em funções 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 Spatial Anchors. 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 Âncoras Espaciais. Aplicativos ou usuários que têm essa função podem criar âncoras espaciais e consultá-las, mas não podem excluí-las.
Leitor de Conta de Âncoras Espaciais. Aplicativos ou usuários que têm essa função só podem consultar âncoras espaciais. Eles não podem criar novos, excluir os existentes ou atualizar metadados neles. Essa função é normalmente usada para aplicativos em que alguns usuários fazem a curadoria do ambiente, mas outros só podem se lembrar de âncoras colocadas anteriormente no ambiente.