Proveedores Graph Toolkit Microsoft

Los proveedores de Graph Toolkit microsoft permiten que la aplicación se autentique con Microsoft Identity y acceda a Microsoft Graph en pocas líneas de código. Cada proveedor controla la autenticación de usuario y la adquisición de los tokens de acceso para llamar a las API de Microsoft Graph, para que no tenga que escribir este código usted mismo.

Puede usar los proveedores por su cuenta, sin componentes, para implementar rápidamente la autenticación de la aplicación y realizar llamadas a Microsoft Graph a través del SDK de cliente de JavaScript.

Los proveedores son necesarios al usar los componentes Graph Toolkit Microsoft, ya que los componentes los usan para tener acceso a Microsoft Graph. Si ya tiene su propia autenticación y desea usar los componentes, puede usar un proveedor personalizado en su lugar.

El Toolkit incluye los siguientes proveedores.

Proveedores Descripción
MSAL Usa msal.js para iniciar sesión en usuarios y adquirir tokens para usarlos con Microsoft Graph en una aplicación web.
MSAL2 Usa msal-browser para iniciar sesión en usuarios y adquirir tokens para usarlos con Microsoft Graph en una aplicación web.
Electron Autentica y proporciona a Microsoft Graph acceso a componentes dentro de aplicaciones de Electron.
SharePoint Autentica y proporciona a Microsoft Graph acceso a componentes dentro de SharePoint elementos web.
Teams Usa msal.js para iniciar sesión en usuarios y adquirir tokens en el cliente en Microsoft Teams pestañas.
Teams MSAL2 Usa msal-browser para iniciar sesión en usuarios y adquirir tokens en Microsoft Teams pestañas. Admite single Sign-On con back-end personalizado.
Proxy Permite el uso de la autenticación back-end enrutando todas las llamadas a Microsoft Graph a través del back-end.
Personalizados Cree un proveedor personalizado para habilitar la autenticación y el acceso a Microsoft Graph con el código de autenticación existente de la aplicación.

Inicializar un proveedor

Para usar un proveedor en la aplicación, debes inicializar un nuevo proveedor y, a continuación, establecerlo como el proveedor global en el espacio de nombres Proveedores. Se recomienda hacer esto antes de empezar a usar cualquiera de los componentes. Puede hacerlo de dos maneras:

Opción 1: Usar el componente de proveedor

Puede usar la versión del componente del proveedor directamente en su HTML. En segundo plano, se inicializa un nuevo proveedor y se establece como el proveedor global. En el ejemplo siguiente se muestra cómo usar el proveedor MSAL2.

<script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script>
<mgt-msal2-provider client-id="YOUR_CLIENT_ID"></mgt-msal2-provider>

Opción 2: Inicializar en código

Inicializar el proveedor en el código JavaScript le permite proporcionar más opciones. Para ello, cree una nueva instancia de proveedor y establezca el valor de la Providers.globalProvider propiedad en el proveedor que desea usar. En el ejemplo siguiente se muestra cómo usar el proveedor MSAL2.

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

Nota: Para obtener información detallada sobre cómo registrar la aplicación y obtener un identificador de cliente, consulta Crear una Azure Active Directory aplicación.

Ámbitos de permisos

Se recomienda agregar todos los ámbitos scopes de permisos que la aplicación necesita al atributo o propiedad al inicializar el proveedor (esto no se aplica al proveedor SharePoint usuario). Esto es opcional, pero mejorará la experiencia del usuario presentando una sola pantalla de consentimiento al usuario con una lista agregada de permisos solicitados por todos los componentes de la aplicación, en lugar de presentar pantallas independientes para cada componente. En los ejemplos siguientes se muestra cómo hacerlo con el proveedor MSAL2.

<script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script>
<mgt-msal2-provider client-id="YOUR_CLIENT_ID"
                   scopes="user.read,people.read"
                   ></mgt-msal2-provider>

Si va a inicializar el proveedor en código, proporcione los ámbitos de permisos en una matriz de la scopes propiedad.

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

Puede encontrar la lista de ámbitos de permisos requeridos por cada componente en la sección Permisos de microsoft Graph de la página de documentación de cada componente.

Estado del proveedor

El proveedor realiza un seguimiento del estado de autenticación del usuario y lo comunica a los componentes. Por ejemplo, cuando un usuario inicia sesión correctamente, ProviderState SignedInse actualiza a , indicando a los componentes que ahora pueden realizar llamadas a Microsoft Graph. La ProviderState enumeración define tres estados, como se muestra.

export enum ProviderState {
  Loading,
  SignedOut,
  SignedIn
}

En algunos escenarios, querrá mostrar determinadas funciones o realizar una acción solo después de que un usuario haya iniciado sesión correctamente. Puede obtener acceso y comprobar el estado del proveedor, como se muestra en el ejemplo siguiente.

import { Providers, ProviderState } from '@microsoft/mgt'

//assuming a provider has already been initialized

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

También puede usar el método para Providers.onProviderUpdated recibir una notificación siempre que cambie el estado del proveedor.

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

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

Obtener un token de acceso

Cada proveedor expone una función llamada que getAccessToken puede recuperar el token de acceso actual o recuperar un nuevo token de acceso para los ámbitos proporcionados. En el ejemplo siguiente se muestra cómo obtener un nuevo token de acceso con el ámbito User.Read de permisos.

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

//assuming a provider has already been initialized

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

Realizar sus propias llamadas a Microsoft Graph

Todos los componentes pueden tener acceso a Microsoft Graph sin ninguna personalización necesaria siempre que inicialice un proveedor (como se describe en las secciones anteriores). Si desea realizar sus propias llamadas a Microsoft Graph, puede hacerlo obteniendo una referencia al mismo SDK de Microsoft Graph que usan los componentes. En primer lugar, obtenga una referencia al global IProvider y, a continuación, use el graph objeto como se muestra:

import { Providers } from '@microsoft/mgt';

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

Puede haber casos en los que necesites pasar permisos adicionales, según la API a la que estés llamando. En el ejemplo siguiente, se muestra cómo hacerlo.

import { prepScopes } from '@microsoft/mgt';

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

Uso de varios proveedores

En algunos escenarios, la aplicación se ejecutará en diferentes entornos y requerirá un proveedor diferente para cada uno. Por ejemplo, la aplicación puede ejecutarse como una aplicación web y una pestaña Microsoft Teams, lo que significa que es posible que deba usar el proveedor MSAL2 y el proveedor Teams MSAL2. Para este escenario, todos los componentes del proveedor tienen el depends-on atributo para crear una cadena de reserva, como se muestra en el ejemplo siguiente.

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

En este escenario, el proveedor MSAL2 solo se usará si la aplicación se ejecuta como una aplicación web y el proveedor Teams MSAL2 no está disponible en el entorno actual.

Para lograr lo mismo en el código, puede usar la isAvailable propiedad en el proveedor, como se muestra.

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

Inicio de sesión/cierre de sesión del usuario

Cuando tenga los proveedores adecuados inicializados para la aplicación, puede agregar el componente de inicio de sesión de Toolkit para implementar de forma fácil y rápida el inicio de sesión y el cierre de sesión del usuario. El componente funciona con el proveedor para controlar toda la lógica de autenticación y la funcionalidad de inicio de sesión/cierre de sesión. En el ejemplo siguiente se usa el proveedor MSAL2 y el componente Login.

<script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script>
<mgt-msal2-provider client-id="YOUR_CLIENT_ID"></mgt-msal2-provider>
<mgt-login></mgt-login>

En los escenarios en los que quiera implementarlo usted mismo, en lugar de usar el componente login de Toolkit, login puede hacerlo con los métodos y logout del proveedor.

Implementar su propio proveedor

En escenarios en los que desea agregar componentes de Toolkit a una aplicación con código de autenticación preexistido, puede crear un proveedor personalizado que se conecte al mecanismo de autenticación, en lugar de usar nuestros proveedores predefinidos. El kit de herramientas proporciona dos formas de crear nuevos proveedores:

  • Cree un nuevo que SimpleProvider devuelva un token de acceso desde el código de autenticación pasando una función.
  • Extienda la IProvider clase abstracta.

Para obtener más información acerca de cada uno de ellos, vea proveedores personalizados.