Proveedores de Microsoft Graph ToolkitMicrosoft Graph Toolkit providers

Los proveedores de Microsoft Graph Toolkit permiten que la aplicación se autentique con Microsoft Identity y acceda a Microsoft Graph en solo unas pocas líneas de código.The Microsoft Graph Toolkit providers enable your application to authenticate with Microsoft Identity and access Microsoft Graph in only few lines of code. 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.Each provider handles user authentication and acquiring the access tokens to call Microsoft Graph APIs, so that you don't have to write this code yourself.

Puedes 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.You can use the providers on their own, without components, to quickly implement authentication for your app and make calls to Microsoft Graph via the JavaScript client SDK.

Los proveedores son necesarios al usar los componentes de Microsoft Graph Toolkit, ya que los componentes los usan para tener acceso a Microsoft Graph.The providers are required when using the Microsoft Graph Toolkit components as the components use them to access Microsoft Graph. Si ya tiene su propia autenticación y desea usar los componentes, puede usar un proveedor personalizado en su lugar.If you already have your own authentication and want to use the components, you can use a custom provider instead.

El kit de herramientas incluye los siguientes proveedores.The Toolkit includes the following providers.

ProveedoresProviders DescripciónDescription
MsalMsal Usa MSAL.js para iniciar sesión en usuarios y adquirir tokens para usarlos con Microsoft Graph en una aplicación web.Uses MSAL.js to sign in users and acquire tokens to use with Microsoft Graph in a web application.
ElectronElectron Autentica y proporciona acceso de Microsoft Graph a componentes dentro de aplicaciones de Electron.Authenticates and provides Microsoft Graph access to components inside of Electron apps.
SharePointSharePoint Autentica y proporciona acceso de Microsoft Graph a componentes dentro de los elementos web de SharePoint.Authenticates and provides Microsoft Graph access to components inside of SharePoint web parts.
TeamsTeams Autentica y proporciona acceso de Microsoft Graph a componentes dentro de las pestañas de Microsoft Teams.Authenticates and provides Microsoft Graph access to components inside Microsoft Teams tabs.
ProxyProxy Permite el uso de la autenticación back-end enrutando todas las llamadas a Microsoft Graph a través del back-end.Allows the use of backend authentication by routing all calls to Microsoft Graph through your backend.
PersonalizadosCustom 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.Create a custom provider to enable authentication and access to Microsoft Graph with your application's existing authentication code.

Inicializar un proveedorInitializing a provider

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.To use a provider in your app, you need to initialize a new provider and then set it as the global provider in the Providers namespace. Se recomienda hacer esto antes de empezar a usar cualquiera de los componentes.We recommend doing this before you start using any of the components. Puede hacerlo de dos maneras:You can do this one of two ways:

Opción 1: Usar el componente de proveedorOption 1: Use the provider component

Puede usar la versión del componente del proveedor directamente en su HTML.You can use the component version of the provider directly in your HTML. En segundo plano, se inicializa un nuevo proveedor y se establece como el proveedor global.Behind the scenes, a new provider is initialized and set as the global provider. En el ejemplo siguiente se muestra cómo usar MsalProvider.The following example shows how to use the MsalProvider.

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

Opción 2: Inicializar en códigoOption 2: Initialize in code

Inicializar el proveedor en el código JavaScript le permite proporcionar más opciones.Initializing your provider in your JavaScript code enables you to provide more options. Para ello, cree una nueva instancia de proveedor y establezca el valor de la propiedad en el proveedor que Providers.globalProvider desea usar.To do this, create a new provider instance and set the value of the Providers.globalProvider property to the provider you'd like to use. En el ejemplo siguiente se muestra cómo usar MsalProvider.The following example shows how to use the MsalProvider.

import {Providers, MsalProvider } from "@microsoft/mgt";
Providers.globalProvider = new MsalProvider({
  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 Create an Azure Active Directory app.Note: For details about how to register your app and get a client ID, see Create an Azure Active Directory app.

Ámbitos de permisosPermission Scopes

Se recomienda agregar todos los ámbitos de permisos que la aplicación necesita al atributo o propiedad al inicializar el proveedor (esto no se aplica scopes al proveedor de SharePoint).We recommend adding all the permission scopes your application needs to the scopes attribute or property when initializing your provider (this does not apply to the SharePoint provider). 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.This is optional, but will improve your user experience by presenting a single consent screen to the user with an aggregated list of permissions requested by all components in your app, rather than presenting separate screens for each component. En los ejemplos siguientes se muestra cómo hacerlo con MsalProvider.The following examples show how to do this with the MsalProvider.

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

Si va a inicializar el proveedor en código, proporcione los ámbitos de permisos en una matriz de la scopes propiedad.If you're initializing the provider in code, provide the permission scopes in an array in the scopes property.

import {Providers, MsalProvider } from "@microsoft/mgt";
Providers.globalProvider = new MsalProvider({
  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.You can find the list of permission scopes required by each component in the Microsoft Graph permissions section of each component's documentation page.

Estado del proveedorProvider state

El proveedor realiza un seguimiento del estado de autenticación del usuario y lo comunica a los componentes.The provider keeps track of the user's authentication state and communicates it to the components. Por ejemplo, cuando un usuario inicia sesión correctamente, se actualiza a , indicando a los componentes que ahora pueden realizar llamadas ProviderState SignedIn a Microsoft Graph.For example, when a user successfully signs in, the ProviderState is updated to SignedIn, signaling to the components that they are now able to make calls to Microsoft Graph. La ProviderState enumeración define tres estados, como se muestra.The ProviderState enum defines three states, as shown.

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.In some scenarios, you will want to show certain functionality or perform an action only after a user has successfully signed in. Puede obtener acceso y comprobar el estado del proveedor, como se muestra en el ejemplo siguiente.You can access and check the provider state, as shown in the following example.

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 recibir una notificación siempre Providers.onProviderUpdated que cambie el estado del proveedor.You can also use the Providers.onProviderUpdated method to get notified whenever the state of the provider changes.

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 accesoGetting an access token

Cada proveedor expone una función llamada que puede recuperar el token de acceso actual o recuperar un nuevo token de acceso getAccessToken para los ámbitos proporcionados.Each provider exposes a function called getAccessToken that can retrieve the current access token or retrieve a new access token for the provided scopes. En el ejemplo siguiente se muestra cómo obtener un nuevo token de acceso con el User.Read ámbito de permisos.The following example shows how to get a new access token with the User.Read permission scope.

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

//assuming a provider has already been initialized

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

Realizar sus propias llamadas a Microsoft GraphMaking your own calls to Microsoft Graph

Todos los componentes pueden tener acceso a Microsoft Graph sin necesidad de personalización, siempre que inicialice un proveedor (como se describe en las secciones anteriores).All components can access Microsoft Graph without any customization required as long as you initialize a provider (as described in the previous sections). Si desea realizar sus propias llamadas a Microsoft Graph, puede hacerlo obteniendo una referencia al mismo SDK de Microsoft Graph que usan los componentes.If you want to make your own calls to Microsoft Graph, you can do so by getting a reference to the same Microsoft Graph SDK used by the components. En primer lugar, obtenga una referencia al global IProvider y, a continuación, use el graph objeto como se muestra:First, get a reference to the global IProvider and then use the graph object as shown:

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.There might be cases where you need to pass additional permissions, depending on the API you're calling. En el ejemplo siguiente, se muestra cómo hacerlo.The following example shows how to do this.

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

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

Uso de varios proveedoresUsing multiple providers

En algunos escenarios, la aplicación se ejecutará en diferentes entornos y requerirá un proveedor diferente para cada uno.In some scenarios, your application will run in different environments and require a different provider for each. Por ejemplo, la aplicación puede ejecutarse como una aplicación web y una pestaña de Microsoft Teams, lo que significa que es posible que deba usar MsalProvider y TeamsProvider.For example, the app might run as both a web application and a Microsoft Teams tab, which means you might need to use both the MsalProvider and the TeamsProvider. Para este escenario, todos los componentes del proveedor tienen el atributo para crear una cadena depends-on de reserva, como se muestra en el ejemplo siguiente.For this scenario, all provider components have the depends-on attribute to create a fallback chain, as shown in the following example.

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

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

En este escenario, MsalProvider solo se usará si la aplicación se ejecuta como una aplicación web y TeamsProvider no está disponible en el entorno actual.In this scenario, the MsalProvider will only be used if your app is running as a web application and the TeamsProvider is not available in the current environment.

Para lograr lo mismo en el código, puede usar la isAvailable propiedad en el proveedor, como se muestra.To accomplish the same in code, you can use the isAvailable property on the provider, as shown.

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

Inicio de sesión/cierre de sesión del usuarioUser Login/Logout

Cuando tenga los proveedores adecuados inicializados para la aplicación, puede agregar el componente inicio de sesión del kit de herramientas para implementar de forma fácil y rápida el inicio de sesión y el cierre de sesión del usuario. When you have the right providers initialized for your application, you can add the Toolkit's Login component to easily and quickly implement user login and logout. 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.The component works with the provider to handle all of the authentication logic and login/logout functionality. En el ejemplo siguiente se usan MsalProvider y el componente Login.The following example uses the MsalProvider and the Login component.

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

En los escenarios en los que quiera implementarlo usted mismo, en lugar de usar el componente Login del kit de herramientas, puede hacerlo con los métodos login y logout del proveedor.In scenarios where you want to implement this yourself, rather than using the Toolkit's Login component, you can do so by using the login and logout methods of the provider.

Implementar su propio proveedorImplement your own provider

En escenarios en los que desea agregar componentes del kit de herramientas 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.In scenarios where you want to add Toolkit components to an application with pre-existing authentication code, you can create a custom provider that hooks into your authentication mechanism, instead of using our predefined providers. El kit de herramientas proporciona dos formas de crear nuevos proveedores:The toolkit provides two ways to create new providers:

  • Cree un nuevo SimpleProvider que devuelva un token de acceso desde el código de autenticación pasando una función.Create a new SimpleProvider that returns an access token from your authentication code by passing in a function.
  • Extienda IProvider la clase abstracta.Extend the IProvider abstract class.

Para obtener más información acerca de cada uno de ellos, vea proveedores personalizados.For more details about each one, see custom providers.