Compartilhar via

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

  • Artigo

Os serviços de Realidade Misturada, como o Azure Remote Rendering, usam o STS (Serviço de Token de Segurança de Realidade Misturada) para autenticação. Esse pacote dá suporte à troca de credenciais de conta de Realidade Misturada por um token de acesso do STS que pode ser usado para acessar serviços de Realidade Misturada.

Links de chave:

Introdução

Ambientes com suporte no momento

Pré-requisitos

  • Uma assinatura do Azure.
  • Você deve ter uma conta com um serviço Azure Mixed Reality:
    • de Renderização Remota do Azure
  • Familiaridade com os conceitos de autenticação e credencial da biblioteca de identidade do do Azure.

Instalar o pacote @azure/mixed-reality-authentication

Instale a biblioteca de clientes da Autenticação de Realidade Misturada do Azure 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 de Realidade Misturada e um credential.

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

  • Autenticação de chave de conta
    • As chaves de conta permitem que você comece a usar rapidamente os serviços de Realidade Misturada. Mas antes de implantar seu aplicativo em produção, recomendamos que você atualize seu 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 seu 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 de Realidade Misturada usando seus grupos de segurança existentes do Azure AD. Você também pode conceder acesso diretamente aos usuários em sua organização.
    • Caso contrário, recomendamos que você obtenha tokens do Azure AD de um serviço Web que dê suporte ao seu aplicativo. Recomendamos esse método para aplicativos de produção porque ele permite que você evite inserir as credenciais para acesso a um serviço de Realidade Misturada em seu aplicativo cliente.

Usando a autenticação de chave de conta

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

Depois de ter uma chave de conta, você poderá usar a classe AzureKeyCredential 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 pacote @azure/identity:

npm install @azure/identity

Você também precisará [registrar um novo aplicativo do AAD][register_aad_app] e conceder acesso ao recurso de Realidade Misturada atribuindo a função apropriada para seu serviço de 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 o STS de Realidade Misturada para obter um token de acesso.

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

Valor retornado

O valor retornado de 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 de Identidade do Azure para ver cenários de autenticação mais complexos.

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

Algumas bibliotecas de clientes de 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 uso de SpatialAnchorsClient 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.

Solucionando problemas

Log

Habilitar o registro em 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 registro em log pode ser habilitado em runtime chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, você pode examinar os documentos do pacote @azure/agente.

Próximas etapas

Examine os exemplos de diretório para obter exemplos detalhados sobre como usar essa biblioteca.

Contribuindo

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

Ao enviar uma solicitação de pull, um CLA-bot determinará automaticamente se você precisa fornecer um CLA e decorar a PR adequadamente (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 usando nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, consulte as perguntas frequentes sobre o Código de Conduta ou entre em contato com opencode@microsoft.com com perguntas ou comentários adicionais.

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

impressões