Provedores do Microsoft Graph Toolkit

Artigo
10/18/2023

Os provedores do Microsoft Graph Toolkit permitem que seu aplicativo se autentique com o Microsoft Identity e acesse o Microsoft Graph em apenas algumas linhas de código. Cada provedor manipula a autenticação do usuário e a aquisição dos tokens de acesso para chamar APIs do Microsoft Graph, para que você não precise escrever esse código por conta própria.

Você pode usar os provedores por conta própria, sem componentes, para implementar rapidamente a autenticação para seu aplicativo e fazer chamadas para o Microsoft Graph por meio do SDK do cliente JavaScript.

Os provedores são necessários ao usar os componentes do Kit de Ferramentas do Microsoft Graph, pois os componentes os usam para acessar o Microsoft Graph. Se você já tiver sua própria autenticação e quiser usar os componentes, poderá usar um provedor personalizado .

O Kit de Ferramentas inclui os provedores a seguir.

Provedores	Descrição
Personalizados	Cria um provedor personalizado para habilitar a autenticação e o acesso ao Microsoft Graph usando o código de autenticação existente do aplicativo.
Elétron	Autentica e fornece acesso do Microsoft Graph a componentes dentro de aplicativos Electron.
MSAL2	Usa o navegador MSAL para entrar em usuários e adquirir tokens a serem usados com o Microsoft Graph.
Proxy	Permite o uso da autenticação de back-end roteando todas as chamadas para o Microsoft Graph por meio do back-end.
SharePoint	Autentica e fornece acesso do Microsoft Graph a componentes dentro de web parts do SharePoint.
TeamsFx	Use o provedor TeamsFx dentro de seus aplicativos do Microsoft Teams para fornecer acesso aos componentes do Microsoft Graph Toolkit ao Microsoft Graph.

Inicializando um provedor

Para usar um provedor em seu aplicativo, você precisa inicializar um novo provedor e defini-lo como o provedor global no namespace Provedores. Recomendamos fazer isso antes de começar a usar qualquer um dos componentes. Você pode fazer isso de duas maneiras:

Opção 1: usar o componente do provedor

Você pode usar a versão do componente do provedor diretamente em seu HTML. Nos bastidores, um novo provedor é inicializado e definido como o provedor global. O exemplo a seguir mostra como usar o provedor 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>

Opção 2: Inicializar no código

Inicializar seu provedor no código JavaScript permite que você forneça mais opções. Para fazer isso, crie uma nova instância de provedor e defina o valor da Providers.globalProvider propriedade para o provedor que você gostaria de usar. O exemplo a seguir mostra como usar o provedor MSAL2.

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

Nota: Para obter detalhes sobre como registrar seu aplicativo e obter uma ID do cliente, consulte Criar um aplicativo Microsoft Entra.

Escopos de permissão

Recomendamos adicionar todos os escopos de permissão que seu aplicativo precisa ao scopes atributo ou à propriedade ao inicializar seu provedor (isso não se aplica ao provedor do SharePoint). Isso é opcional, mas melhorará sua experiência de usuário apresentando uma única tela de consentimento ao usuário com uma lista agregada de permissões solicitadas por todos os componentes em seu aplicativo, em vez de apresentar telas separadas para cada componente. Os exemplos a seguir mostram como fazer isso com o Provedor 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>

Se você estiver inicializando o provedor no código, forneça os escopos de permissão em uma matriz na scopes propriedade.

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

Você pode encontrar a lista de escopos de permissão exigidos por cada componente na seção permissões do Microsoft Graph da página de documentação de cada componente.

Hosts personalizados

Você pode especificar hosts personalizados para o cliente do Microsoft Graph. Isso permite que você chame APIs não protegidas por Microsoft Entra ID do Microsoft Graph. Ao especificar hosts personalizados, certifique-se de solicitar o escopo do token de acesso.

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

Se você estiver inicializando o provedor no código, forneça os nomes de host em uma matriz na customHosts propriedade.

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

Observação: são nomes de host, não URIs.

Para chamar as APIs personalizadas, solicite esse escopo de 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();
...

Estado do provedor

O provedor mantém o controle do estado de autenticação do usuário e comunica-o aos componentes. Por exemplo, quando um usuário entra com êxito, ele ProviderState é atualizado para SignedIn, sinalizando para os componentes que eles agora são capazes de fazer chamadas para o Microsoft Graph. O ProviderState enum define três estados, conforme mostrado.

export enum ProviderState {
  Loading,
  SignedOut,
  SignedIn,
}

Em alguns cenários, você deseja mostrar determinada funcionalidade ou executar uma ação somente depois que um usuário tiver se conectado com êxito. Você pode acessar e marcar o estado do provedor, conforme mostrado no exemplo a seguir.

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

//assuming a provider has already been initialized

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

Você também pode usar o Providers.onProviderUpdated método para ser notificado sempre que o estado do provedor for alterado.

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

Como obter um token de acesso

Cada provedor expõe uma função chamada getAccessToken que pode recuperar o token de acesso atual ou recuperar um novo token de acesso para os escopos fornecidos. O exemplo a seguir mostra como obter um novo token de acesso com o escopo de User.Read permissão.

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

Fazendo suas próprias chamadas para o Microsoft Graph

Todos os componentes podem acessar o Microsoft Graph sem qualquer personalização necessária desde que você inicialize um provedor (conforme descrito nas seções anteriores). Se você quiser fazer suas próprias chamadas para o Microsoft Graph, poderá fazer isso obtendo uma referência ao mesmo SDK do Microsoft Graph usado pelos componentes. Primeiro, obtenha uma referência ao global IProvider e use o graph objeto conforme mostrado:

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

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

Pode haver casos em que você precisa passar permissões adicionais, dependendo da API que você está chamando. O exemplo a seguir mostra como fazer isso.

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

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

Usando vários provedores

Em alguns cenários, seu aplicativo será executado em ambientes diferentes e exigirá um provedor diferente para cada um. Por exemplo, o aplicativo pode ser executado como um aplicativo Web e uma guia do Microsoft Teams, o que significa que talvez seja necessário usar o provedor MSAL2 e o provedor MSAL2 do Teams. Para esse cenário, todos os componentes do provedor têm o depends-on atributo para criar uma cadeia de fallback, conforme mostrado no exemplo a seguir.

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

Nesse cenário, o provedor MSAL2 só será usado se seu aplicativo estiver em execução como um aplicativo Web e o provedor MSAL2 do Teams não estiver disponível no ambiente atual.

Para realizar o mesmo no código, você pode usar a isAvailable propriedade no provedor, conforme mostrado.

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

Logon/Logon do Usuário

Quando você tiver os provedores certos inicializados para seu aplicativo, você pode adicionar o componente Logon do Kit de Ferramentas para implementar o logon e o logon do usuário com facilidade e rapidez. O componente funciona com o provedor para lidar com toda a lógica de autenticação e a funcionalidade de logon/logout. O exemplo a seguir usa o provedor MSAL2 e o componente Logon.

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

Em cenários em que você deseja implementar isso por conta própria, em vez de usar o componente Logon do Kit de Ferramentas, você pode fazê-lo usando os login métodos e logout do provedor.

Implementar seu próprio provedor

Em cenários em que você deseja adicionar componentes do Toolkit a um aplicativo com código de autenticação pré-existente, você pode criar um provedor personalizado que se conecta ao mecanismo de autenticação, em vez de usar nossos provedores predefinidos. O kit de ferramentas fornece duas maneiras de criar novos provedores:

Crie um novo SimpleProvider que retorna um token de acesso do código de autenticação passando uma função.
Estenda a IProvider classe abstrata.

Para obter mais detalhes sobre cada um deles, consulte provedores personalizados.

Partilhar via