Partager via

Bibliothèque de client Azure Mixed Reality Authentication pour JavaScript - version 1.0.0-beta.1

  • Article

Mixed Reality services, tels qu’Azure Spatial Anchors, Azure Remote Rendering et d’autres, utilisent le service sts (Mixed Reality security token service) pour l’authentification. Ce package prend en charge l’échange des informations d’identification de compte Mixed Reality contre un jeton d’accès à partir de STS qui peut être utilisé pour accéder aux services Mixed Reality.

Liens clés :

diagramme d’authentification de service Mixed Reality

Prise en main

Environnements actuellement pris en charge

Prérequis

Installez le package @azure/mixed-reality-authentication

Installez la bibliothèque cliente Azure Mixed Reality Authentication pour JavaScript avec npm:

npm install @azure/mixed-reality-authentication

Créez et authentifiez unMixedRealityStsClient

Pour créer un objet client afin de demander un jeton d’accès pour un service Mixed Reality, vous aurez besoin de la account identifier ressource et account domain de votre Mixed Reality service et d’une credential.

Mixed Reality services prennent en charge différentes formes d’authentification :

  • Authentification par clé de compte
    • Les clés de compte vous permettent de commencer rapidement à utiliser Mixed Reality services. Mais avant de déployer votre application en production, nous vous recommandons de mettre à jour votre application pour utiliser l’authentification Azure AD.
  • Authentification par jeton Azure Active Directory (AD)
    • Si vous créez une application d’entreprise et que votre entreprise utilise Azure AD comme système d’identité, vous pouvez utiliser l’authentification Azure AD basée sur l’utilisateur dans votre application. Vous accordez ensuite l’accès à vos comptes Mixed Reality à l’aide de vos groupes de sécurité Azure AD existants. Vous pouvez également accorder l’accès directement aux utilisateurs de votre organisation.
    • Sinon, nous vous recommandons d’obtenir des jetons Azure AD à partir d’un service web prenant en charge votre application. Nous recommandons cette méthode pour les applications de production, car elle vous permet d’éviter d’incorporer les informations d’identification pour l’accès à un service Mixed Reality dans votre application cliente.

Consultez ici pour obtenir des instructions et des informations détaillées.

Utilisation de l’authentification par clé de compte

Utilisez le portail Azure pour accéder à votre ressource de service Mixed Reality et récupérer un account key.

Une fois que vous avez une clé de compte, vous pouvez utiliser la AzureKeyCredential classe pour authentifier le client comme suit :

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)
);

Remarque : l’authentification par clé de compte n’est pas recommandée pour les applications de production.

Utilisation d’informations d’identification Azure Active Directory

L’authentification par clé de compte est utilisée dans la plupart des exemples, mais vous pouvez également vous authentifier auprès d’Azure Active Directory à l’aide de la bibliothèque Azure Identity. Il s’agit de la méthode recommandée pour les applications de production. Pour utiliser le fournisseur DefaultAzureCredential indiqué ci-dessous ou d’autres fournisseurs d’informations d’identification fournis avec le Kit de développement logiciel (SDK) Azure, installez le @azure/identity package :

npm install @azure/identity

Vous devez également inscrire une nouvelle application AAD et accorder l’accès à votre ressource Mixed Reality en affectant le rôle approprié pour votre service Mixed Reality à votre principal de service.

Définissez les valeurs de l’ID client, de l’ID de locataire et de la clé secrète client de l’application AAD en tant que variables d’environnement : 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());

Concepts clés

MixedRealityStsClient

MixedRealityStsClient est la bibliothèque cliente utilisée pour accéder au Mixed Reality STS afin d’obtenir un jeton d’accès.

Les jetons obtenus à partir de l’Mixed Reality STS ont une durée de vie de 24 heures.

Valeur renvoyée

La valeur de retour pour un appel réussi à getToken est un GetTokenResponse, qui est un AccessToken à partir de @azure/core-http.

Exemples

Récupérer un jeton d’accès

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();

Consultez les exemples d’authentification ci-dessus ou Azure Identity pour des scénarios d’authentification plus complexes.

Utilisation du jeton d’accès dans une bibliothèque cliente Mixed Reality

Certaines bibliothèques clientes Mixed Reality peuvent accepter un jeton d’accès à la place d’informations d’identification. Par exemple :

// 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);

Remarque : L’utilisation SpatialAnchorsClient ci-dessus est hypothétique et peut ne pas refléter la bibliothèque réelle. Consultez la documentation de la bibliothèque cliente que vous utilisez pour déterminer si et comment cela peut être pris en charge.

Résolution des problèmes

Journalisation

L’activation de la journalisation peut vous aider à mieux comprendre les échecs. Pour avoir un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans @azure/logger :

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

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, consultez les documents relatifs au package @azure/logger.

Étapes suivantes

Consultez le répertoire d’exemples pour obtenir des exemples détaillés sur l’utilisation de cette bibliothèque.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

Impressions