Fournisseurs de la Boîte à outils Microsoft Graph

Article
10/18/2023

Les fournisseurs de la Boîte à outils Microsoft Graph activent votre application pour authentifier avec l’identité Microsoft et l’accès à Microsoft Graph en quelques lignes de code seulement. Chaque fournisseur traite l’authentification utilisateur et l’acquisition de jetons d’accès pour appeler les API Microsoft Graph, de sorte que vous n’avez pas à écrire ce code vous-même.

Vous pouvez utiliser les fournisseurs en tant que tels, sans composants, pour implémenter rapidement l’authentification pour votre application et effectuer des appels vers Microsoft Graph via le Kit de développement logiciel (SDK) client de JavaScript.

Les fournisseurs ont l’obligation, lors de l’utilisation des composants de la Boîte à outils Microsoft Graph en tant que composants, de les utiliser pour accéder à Microsoft Graph. Si vous disposez déjà de votre propre authentification et que vous voulez utiliser les composants, vous pouvez utiliser un fournisseur personnalisé à la place.

Le Kit de ressources Microsoft Graph inclut les fournisseurs suivants.

Fournisseurs	Description
Personnalisé	Crée un fournisseur personnalisé pour activer l’authentification et l’accès à Microsoft Graph à l’aide du code d’authentification existant de votre application.
Électron	Authentifie et fournit à Microsoft Graph l’accès aux composants à l’intérieur des applications Electron.
MSAL2	Utilise MSAL-browser pour connecter des utilisateurs et acquérir des jetons à utiliser avec Microsoft Graph.
Proxy	Permet l’utilisation de l’authentification principale en effectuant le routage de tous les appels vers Microsoft Graph au moyen de votre serveur principal.
SharePoint	Authentifie et fournit l’accès à Microsoft Graph aux composants présents dans les composants WebPart SharePoint.
TeamsFx	Utilisez le fournisseur TeamsFx dans vos applications Microsoft Teams pour fournir aux composants du Kit de ressources Microsoft Graph l’accès à Microsoft Graph.

Initialisation d’un fournisseur

Pour utiliser un fournisseur dans votre application, vous devez initialiser un nouveau fournisseur, puis le définir en tant que fournisseur global dans l’espace de noms Fournisseurs. Nous vous recommandons d’effectuer cette opération avant de commencer à utiliser l’un des composants. Vous pouvez procéder de deux manières :

Option 1 : utiliser le composant fournisseur

Vous pouvez directement utiliser la version de composant du fournisseur dans votre HTML. Dans les coulisses, un nouveau fournisseur est initialisé et défini en tant que fournisseur global. L’exemple suivant montre comment utiliser le fournisseur MSAL2.

<script type="module">
  import { registerMgtComponents, registerMgtMsal2Provider } from "https://unpkg.com/@microsoft/mgt@4";
  registerMgtMsal2Provider();
  registerMgtComponents();
</script>
<mgt-msal2-provider client-id="YOUR_CLIENT_ID"></mgt-msal2-provider>

Option 2 : initialiser le code

L’initialisation de votre fournisseur dans votre code JavaScript vous permet de fournir davantage d’options. Pour ce faire, créez une nouvelle instance de fournisseur, puis définissez la valeur de la propriété Providers.globalProvider au fournisseur que vous voulez utiliser. L’exemple suivant montre comment utiliser le fournisseur MSAL2.

import { Providers } from "@microsoft/mgt-element";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
Providers.globalProvider = new Msal2Provider({
  clientId: "YOUR_CLIENT_ID",
});

Note: Pour plus d’informations sur l’inscription de votre application et l’obtention d’un ID client, consultez Créer une application Microsoft Entra.

Étendues d’autorisation

Nous vous recommandons l’ajout de toutes les étendues d’autorisation dont votre application a besoin à la propriété ou à l’attribut scopes lors de l’initialisation de votre fournisseur (ne s’applique pas au fournisseur SharePoint). Cette action est facultative, mais elle améliorera votre expérience utilisation en affichant à l’utilisateur un seul écran de consentement avec une liste agrégée des autorisations demandées par tous les composants dans votre application, au lieu d’afficher des écrans distincts pour chaque composant. Les exemples suivants montrent comment procéder avec le fournisseur MSAL2.

<script type="module">
  import { registerMgtComponents, registerMgtMsal2Provider } from "https://unpkg.com/@microsoft/mgt@4";
  registerMgtMsal2Provider();
  registerMgtComponents();
</script>
<mgt-msal2-provider
  client-id="YOUR_CLIENT_ID"
  scopes="user.read,people.read"
></mgt-msal2-provider>

Si vous initialiser le fournisseur dans le code, fournissez les étendues d’autorisation dans un tableau dans la propriété scopes.

import { Providers } from "@microsoft/mgt-element";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
Providers.globalProvider = new Msal2Provider({
  clientId: 'YOUR_CLIENT_ID'
  scopes:['user.read','people.read']
});

Vous trouverez la liste des étendues d’autorisation exigée par chaque composant dans la section Autorisations Microsoft Graph de la page de documentation de chaque composant.

Hôtes personnalisés

Vous pouvez spécifier des hôtes personnalisés pour le client Microsoft Graph. Cela vous permet d’appeler des API non sécurisées par Microsoft Graph Microsoft Entra ID. Lorsque vous spécifiez des hôtes personnalisés, veillez à demander l’étendue du jeton d’accès.

<script type="module">
  import { registerMgtComponents, registerMgtMsal2Provider } from "https://unpkg.com/@microsoft/mgt@4";
  registerMgtMsal2Provider();
  registerMgtComponents();
</script>
<mgt-msal2-provider 
  client-id="YOUR_CLIENT_ID"
  custom-hosts="myapi.com,anotherapi.com"
></mgt-msal2-provider>

Si vous initialisez le fournisseur dans le code, fournissez les noms d’hôte dans un tableau dans la customHosts propriété .

import { Providers } from "@microsoft/mgt-element";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
Providers.globalProvider = new Msal2Provider({
  clientId: 'YOUR_CLIENT_ID',
  customHosts: ['myapi.com','anotherapi.com']
});

Remarque : il s’agit de noms d’hôtes, et non d’URI.

Pour appeler les API personnalisées, demandez cette étendue d’API.

<mgt-get resource="https://myapi.com/v1.0/api" scopes="api://CUSTOM_API_GUID/SCOPE">
  ...
</mgt-get>

Ou via Javascript/Typescript :

import { prepScopes } from "@microsoft/mgt-element";

graphClient
  .api("https://myapi.com/v1.0/api")
  .middlewareOptions(prepScopes("api://CUSTOM_API_GUID/SCOPE"))
  .get();
...

Statut du fournisseur

Le fournisseur effectue un suivi du statut d’authentification de l’utilisateur et le communique aux composants. Par exemple, lors de la connexion correcte d’un utilisateur, le ProviderState est mis à jour sur SignedIn, signalant aux composants qu’ils peuvent désormais effectuer des appels vers Microsoft Graph. L’énumération ProviderState définit trois statuts, tel qu’illustré.

export enum ProviderState {
  Loading,
  SignedOut,
  SignedIn,
}

Dans certains cas, vous voudrez afficher des fonctionnalités ou accomplir une action seulement après la connexion correcte de l’utilisateur. Vous pouvez accéder et vérifier le statut du fournisseur, tel qu’illustré dans l’exemple suivant.

import { Providers, ProviderState } from "@microsoft/mgt-element";

//assuming a provider has already been initialized

if (Providers.globalProvider.state === ProviderState.SignedIn) {
  //your code here
}

Vous pouvez également utiliser la méthode Providers.onProviderUpdated pour recevoir une notification quand le statut du fournisseur change.

import { Providers, ProviderState } from "@microsoft/mgt-element";

//assuming a provider has already been initialized

const providerStateChanged = () => {
  if (Providers.globalProvider.state === ProviderState.SignedIn) {
    // user is now signed in
  }
};

// register a callback for when the state changes
Providers.onProviderUpdated(providerStateChanged);

// remove callback if necessary
Providers.removeProviderUpdatedListener(providerStateChanged);

Obtention d’un jeton d’accès

Chaque fournisseur expose une fonction appelée getAccessToken qui peut récupérer le jeton d’accès actuel ou récupérer un nouveau jeton d’accès pour les étendues fournies. L’exemple suivant présente le moyen pour obtenir un nouveau jeton d’accès avec l’étendue d’autorisation User.Read.

import { Providers, ProviderState } from "@microsoft/mgt-element";

//assuming a provider has already been initialized

if (Providers.globalProvider.state === ProviderState.SignedIn) {
  const token = await Providers.globalProvider.getAccessToken({
    scopes: ["User.Read"],
  });
}

Passer vos propres appels vers Microsoft Graph

L’ensemble des composants peuvent accéder à Microsoft Graph sans aucune personnalisation obligatoire à condition que vous initialisiez un fournisseur (comme décrit dans les sections précédentes). Si vous voulez passer vos propres appels vers Microsoft Graph, vous pouvez le faire en obtenant une référence auprès du même Kit de développement logiciel (SDK) que celui utilisé par les composants. D’abord, obtenez une référence auprès de IProvider global, puis utilisez l’objet graph tel qu’illustré :

import { Providers } from "@microsoft/mgt-element";

let provider = Providers.globalProvider;
if (provider) {
  let graphClient = provider.graph.client;
  let userDetails = await graphClient.api("me").get();
}

Vous devrez dans certains cas passer par des autorisations supplémentaires en fonction de l’API que vous appelez. L’exemple suivant montre comment procéder.

import { prepScopes } from "@microsoft/mgt-element";

graphClient
  .api("me")
  .middlewareOptions(prepScopes("user.read", "calendar.read"))
  .get();

Utilisation de plusieurs fournisseurs

Dans certains cas, votre application s’exécutera dans différents environnement et exigera un fournisseur différent pour chacun d’entre eux. Par exemple, l’application peut s’exécuter en tant qu’application web et onglet Microsoft Teams, ce qui signifie que vous devrez peut-être utiliser à la fois le fournisseur MSAL2 et le fournisseur MSAL2 Teams. Dans ce cas, tous les composants du fournisseur ont l’attribut depends-on pour créer une chaîne de secours, tel qu’illustré dans l’exemple suivant.

<mgt-teams-msal2-provider
  client-id="[CLIENT-ID]"
  auth-popup-url="auth.html"
></mgt-teams-msal2-provider>

<mgt-msal2-provider
  client-id="[CLIENT-ID]"
  depends-on="mgt-teams-provider"
></mgt-msal2-provider>

Dans ce scénario, le fournisseur MSAL2 n’est utilisé que si votre application s’exécute en tant qu’application web et si le fournisseur MSAL2 Teams n’est pas disponible dans l’environnement actuel.

Pour accomplir la même opération dans le code, vous pouvez utiliser la propriété isAvailable sur le fournisseur, tel qu’illustré.

if (TeamsProvider.isAvailable) {
  Providers.globalProvider = new TeamsProvider(teamsConfig);
} else {
  Providers.globalProvider = new Msal2Provider(msalConfig);
}

Connexion et déconnexion de l’utilisateur

Lorsque les fournisseurs appropriés sont initialisés pour votre application, vous pouvez ajouter le composant Connexiondu Kit de ressources pour facilement et rapidement implémenter la connexion et la déconnexion utilisateur. Le composant fonctionne avec le fournisseur pour traiter l’ensemble de la logique d’authentification et de la fonctionnalité de connexion/déconnexion. L’exemple suivant utilise le fournisseur MSAL2 et le composant Login.

<script type="module">
  import { registerMgtComponents, registerMgtMsal2Provider } from "https://unpkg.com/@microsoft/mgt@4";
  registerMgtMsal2Provider();
  registerMgtComponents();
</script>
<mgt-msal2-provider client-id="YOUR_CLIENT_ID"></mgt-msal2-provider>
<mgt-login></mgt-login>

Dans les scénarios dans lesquels vous souhaitez implémenter ceci vous-même au lieu d’utiliser le composant Connexion du Kit de ressources, vous pouvez l’effectuer en utilisant les méthodes login et logout du fournisseur.

Implémentation de votre fournisseur

Dans les cas où vous voulez ajouter les composants du Kit de ressources à une application ayant un code d’authentification préexistant, vous pouvez créer un fournisseur personnalisé qui s’intègre au mécanisme d’authentification au lieu d’utiliser nos fournisseurs prédéfinis. Le Kit de ressources fournit deux méthodes pour créer de nouveaux fournisseurs :

Créer un SimpleProvider qui renvoie un jeton d’accès à partir de votre code d’authentification en passant dans une fonction.
Développer la classe abstraite IProvider.

Pour en savoir plus sur chacune d’entre elles, voir les fournisseurs personnalisés.