Proveedores de Microsoft Graph Toolkit

Artigo
06/28/2023

Los proveedores de Microsoft Graph Toolkit 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, de modo que no tenga que escribir este código usted mismo.

Puede usar los proveedores por sí mismos, 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 cuando se usan los componentes del Kit de herramientas de Microsoft Graph, ya que los componentes los usan para acceder a Microsoft Graph. Si ya tiene su propia autenticación y quiere usar los componentes, puede usar un proveedor personalizado en su lugar.

El kit de herramientas incluye los siguientes proveedores.

Proveedores	Descripción
Personalizados	Crea un proveedor personalizado para habilitar la autenticación y el acceso a Microsoft Graph mediante el código de autenticación existente de la aplicación.
Electrón	Autentica y proporciona acceso de Microsoft Graph a los componentes dentro de las aplicaciones de Electron.
MSAL2	Usa MSAL-browser para iniciar sesión de usuarios y adquirir tokens para usarlos con Microsoft Graph.
Proxy	Permite el uso de la autenticación de back-end enrutando todas las llamadas a Microsoft Graph a través del back-end.
SharePoint	Autentica y proporciona acceso de Microsoft Graph a los componentes dentro de elementos web de SharePoint.
TeamsFx	Use el proveedor TeamsFx dentro de las aplicaciones de Microsoft Teams para proporcionar a los componentes del kit de herramientas de Microsoft Graph acceso a Microsoft Graph.

Inicialización de un proveedor

Para usar un proveedor en la aplicación, debe inicializar un nuevo proveedor y, a continuación, establecerlo como proveedor global en el espacio de nombres Providers. Se recomienda hacerlo 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 el CÓDIGO HTML. En segundo plano, se inicializa un nuevo proveedor y se establece como proveedor global. En el ejemplo siguiente se muestra cómo usar el proveedor 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>

Opción 2: Inicializar en el 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 } from "@microsoft/mgt-element";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
Providers.globalProvider = new Msal2Provider({
  clientId: "YOUR_CLIENT_ID",
});

Nota: Para obtener más información sobre cómo registrar la aplicación y obtener un identificador de cliente, consulte Creación de una aplicación Microsoft Entra.

Ámbitos de permisos

Se recomienda agregar todos los ámbitos de permisos que la aplicación necesita al atributo o la scopes propiedad al inicializar el proveedor (esto no se aplica al proveedor de SharePoint). Esto es opcional, pero mejorará la experiencia del usuario mediante la presentación de 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 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 va a inicializar el proveedor en el código, proporcione los ámbitos de permisos en una matriz de la scopes propiedad .

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']
});

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.

Hosts personalizados

Puede especificar hosts personalizados para el cliente de Microsoft Graph. Esto le permite llamar a API protegidas Microsoft Entra ID que no son de Microsoft Graph. Cuando especifique hosts personalizados, asegúrese de solicitar el ámbito del token de acceso.

<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 va a inicializar el proveedor en el código, proporcione los nombres de host en una matriz de la customHosts propiedad .

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']
});

Nota: Estos son nombres de host, no URI.

Para llamar a las API personalizadas, solicite ese ámbito de API.

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

O a través de Javascript/Typescript:

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

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

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 se actualiza a SignedIn, señalando 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 cierta funcionalidad o realizar una acción solo después de que un usuario haya iniciado sesión correctamente. Puede acceder al estado del proveedor y comprobarlo, como se muestra en el ejemplo siguiente.

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

//assuming a provider has already been initialized

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

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

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

Obtener un token de acceso

Cada proveedor expone una función llamada getAccessToken que 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 de User.Read permiso.

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"],
  });
}

Realizar sus propias llamadas a Microsoft Graph

Todos los componentes pueden acceder a Microsoft Graph sin necesidad de personalización, siempre y cuando 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-element";

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

Puede haber casos en los que necesite pasar permisos adicionales, en función de la API a la que llame. En el ejemplo siguiente, se muestra cómo hacerlo.

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

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

Uso de varios proveedores

En algunos escenarios, la aplicación se ejecutará en entornos diferentes y requerirá un proveedor diferente para cada uno. Por ejemplo, la aplicación podría ejecutarse como una aplicación web y una pestaña de Microsoft Teams, lo que significa que es posible que tenga que usar el proveedor MSAL2 y el proveedor MSAL2 de Teams. En 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 MSAL2 de Teams 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 o cierre de sesión del usuario

Cuando tenga los proveedores adecuados inicializados para la aplicación, puede agregar el componente Inicio de sesión del kit de herramientas para implementar fácilmente y rápidamente 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 y cierre de sesión. En el ejemplo siguiente se usa el proveedor MSAL2 y el componente Inicio de sesión.

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

En escenarios en los que quiera implementarlo usted mismo, en lugar de usar el componente Inicio de sesión del kit de herramientas, puede hacerlo mediante los login métodos y logout del proveedor.

Implementación de su propio proveedor

En escenarios en los que quiera agregar componentes del kit de herramientas a una aplicación con código de autenticación preexistente, 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 maneras de crear nuevos proveedores:

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

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

Compartir por