Compartilhar via

Biblioteca de clientes da Autenticação Realidade Misturada do Azure para JavaScript – versão 1.0.0-beta.1

  • Artigo

Realidade Misturada serviços, como Âncoras Espaciais do Azure, Remote Rendering do Azure e outros, usam o STS (serviço de token de segurança) Realidade Misturada para autenticação. Esse pacote dá suporte à troca Realidade Misturada credenciais de conta para um token de acesso do STS que pode ser usado para acessar serviços Realidade Misturada.

Links principais:

diagrama de autenticação do serviço Realidade Misturada

Introdução

Ambientes com suporte no momento

Pré-requisitos

Instalar o pacote @azure/mixed-reality-authentication

Instale a biblioteca de clientes do Azure Realidade Misturada Authentication para JavaScript com npm:

npm install @azure/mixed-reality-authentication

Criar e autenticar um MixedRealityStsClient

Para criar um objeto cliente para solicitar um token de acesso para um serviço de Realidade Misturada, você precisará do account identifier e account domain do recurso de serviço do Realidade Misturada e de um credential.

Realidade Misturada serviços dão suporte a algumas formas diferentes de autenticação:

  • Autenticação de chave de conta
    • As chaves de conta permitem que você comece rapidamente a usar Realidade Misturada serviços. Mas antes de implantar seu aplicativo em produção, recomendamos que você atualize o aplicativo para usar a autenticação do Azure AD.
  • Autenticação de token do Azure Active Directory (AD)
    • Se você estiver criando um aplicativo empresarial e sua empresa estiver usando o Azure AD como sistema de identidade, você poderá usar a autenticação do Azure AD baseada no usuário em seu aplicativo. Em seguida, você concede acesso às suas contas Realidade Misturada usando seus grupos de segurança Azure AD existentes. Você também pode permitir acesso diretamente aos usuários em sua organização.
    • Caso contrário, é recomendável que você obtenha tokens do Azure AD em um serviço Web que dê suporte ao seu aplicativo. Recomendamos esse método para aplicativos de produção porque ele permite evitar a inserção das credenciais para acesso a um serviço de Realidade Misturada em seu aplicativo cliente.

Consulte aqui para obter instruções e informações detalhadas.

Usando a autenticação de chave de conta

Use o Portal do Azure para navegar até o recurso de serviço Realidade Misturada e recuperar um account key.

Depois de ter uma chave de conta, você pode usar a AzureKeyCredential classe para autenticar o cliente da seguinte maneira:

const { AzureKeyCredential } = require("@azure/core-auth");

const { MixedRealityStsClient } = require("@azure/mixed-reality-authentication");

const accountId = "<ACCOUNTD ID>";
const accountDomain = "<ACCOUNT_DOMAIN>";
const accountKey = "<ACCOUNT_KEY>";

const client = new MixedRealityStsClient(
  accountId,
  accountDomain,
  new AzureKeyCredential(accountKey)
);

Observação: a autenticação de chave de conta não é recomendada para aplicativos de produção.

Usando uma credencial do Azure Active Directory

A autenticação de chave de conta é usada na maioria dos exemplos, mas você também pode autenticar com o Azure Active Directory usando a biblioteca de Identidade do Azure. Esse é o método recomendado para aplicativos de produção. Para usar o provedor DefaultAzureCredential mostrado abaixo ou outros provedores de credenciais fornecidos com o SDK do Azure, instale o @azure/identity pacote:

npm install @azure/identity

Você também precisará registrar um novo aplicativo do AAD e conceder acesso ao recurso Realidade Misturada atribuindo a função apropriada para o serviço Realidade Misturada à entidade de serviço.

Defina os valores da ID do cliente, da ID do locatário e do segredo do cliente do aplicativo AAD como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

const { MixedRealityStsClient } = require("@azure/mixed-reality-authentication");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new MixedRealityStsClient(accountId, accountDomain, new DefaultAzureCredential());

Principais conceitos

MixedRealityStsClient

O MixedRealityStsClient é a biblioteca de clientes usada para acessar a Realidade Misturada STS para obter um token de acesso.

Os tokens obtidos da Realidade Misturada STS têm um tempo de vida de 24 horas.

Valor Retornado

O valor retornado para uma chamada bem-sucedida para getToken é um GetTokenResponse, que é um AccessToken de @azure/core-http.

Exemplos

Recuperar um token de acesso

const { AzureKeyCredential } = require("@azure/core-auth");

const { MixedRealityStsClient } = require("@azure/mixed-reality-authentication");

const accountId = "<ACCOUNTD ID>";
const accountDomain = "<ACCOUNT_DOMAIN>";
const accountKey = "<ACCOUNT_KEY>";

const client = new MixedRealityStsClient(
  accountId,
  accountDomain,
  new AzureKeyCredential(accountKey)
);

const token = await client.getToken();

Consulte os exemplos de autenticação acima ou Identidade do Azure para cenários de autenticação mais complexos.

Usando o token de acesso em uma biblioteca de clientes Realidade Misturada

Algumas bibliotecas de cliente Realidade Misturada podem aceitar um token de acesso no lugar de uma credencial. Por exemplo:

// GetMixedRealityAccessTokenFromWebService is a hypothetical method that retrieves
// a Mixed Reality access token from a web service. The web service would use the
// MixedRealityStsClient and credentials to obtain an access token to be returned
// to the client.
const accessToken = await GetMixedRealityAccessTokenFromWebService();

const account = new SpatialAnchorsAccount(accountId, accountDomain);
const client = new SpatialAnchorsClient(account, accessToken);

Observação: o SpatialAnchorsClient uso acima é hipotético e pode não refletir a biblioteca real. Consulte a documentação da biblioteca de clientes que você está usando para determinar se e como isso pode ter suporte.

Solução de problemas

Log

A habilitação do log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o log pode ser habilitado no runtime chamando setLogLevel em @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, veja os documentos do pacote @azure/logger.

Próximas etapas

Dê uma olhada no diretório de exemplos para obter exemplos detalhados sobre como usar essa biblioteca.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber como criar e testar o código.

Impressões