Tutorial: Acede ao Microsoft Graph a partir de uma aplicação JavaScript segura como utilizador

Aprenda como aceder ao Microsoft Graph a partir de uma aplicação web a correr no Azure App Service.

Diagrama que mostra o acesso a Microsoft Graph.

Quer adicionar acesso ao Microsoft Graph na sua aplicação web e executar ações como o utilizador com sessão iniciada. Esta secção descreve como conceder permissões delegadas à aplicação web e obter as informações de perfil do utilizador com sessão iniciada a partir do Microsoft Entra ID.

Neste tutorial, irá aprender a:

  • Conceda permissões delegadas a um aplicativo Web.
  • Chame a Microsoft Graph a partir de uma aplicação web para um utilizador autenticado.

Se não tiver uma conta Azure, crie uma conta free antes de começar.

Pré-requisitos

  • Uma aplicação web a correr em Azure App Service que tem ativado o módulo de autenticação/autorização App Service.

Conceder acesso front-end para aceder ao Microsoft Graph

Depois de ativar a autenticação e autorização na sua aplicação web, esta é registada na Microsoft Identity Platform e é suportada por uma aplicação Microsoft Entra. Neste passo, dá permissões à aplicação web para aceder ao Microsoft Graph ao utilizador.

Note

Tecnicamente, dá à aplicação Microsoft Entra da aplicação web as permissões para aceder à aplicação Microsoft Entra Microsoft Graph para o utilizador.

  1. No Microsoft Entra admin center, selecione Entra ID.

  2. Selecione App registrations>Aplicações próprias>Veja todas as aplicações neste diretório. Selecione o nome do aplicativo Web e, em seguida, selecione Permissões de API.

  3. Selecione Adicionar uma permissão, depois selecione as APIs da Microsoft, depois Microsoft Graph.

  4. Selecione Permissões delegadas e, em seguida, selecione User.Read na lista. Selecione Adicionar permissões.

Configurar o Serviço de Aplicações para devolver um token de acesso utilizável

A aplicação web tem agora as permissões necessárias para aceder ao Microsoft Graph enquanto utilizador iniciado sessão. Nesta secção, configura a autenticação e autorização dos Serviços de Aplicação para lhe fornecer um token de acesso utilizável para aceder ao Microsoft Graph. Para este passo, é necessário adicionar o User.Read escopo para o serviço downstream (Microsoft Graph): https://graph.microsoft.com/User.Read.

Importante

Se não configurar o App Service para devolver um token de acesso utilizável, recebe um erro CompactToken parsing failed with error code: 80049217 ao chamar Microsoft Graph APIs no seu código.

Vai a Azure Resource Explorer e usando a árvore de recursos, localiza a tua aplicação web. O URL do recurso deve ser semelhante ao https://management.azure.com/subscriptions/subscriptionId/resourceGroups/SecureWebApp/providers/Microsoft.Web/sites/SecureWebApp20200915115914.

O Azure Resource Explorer é agora aberto com a sua aplicação web selecionada na árvore de recursos.

  1. No topo da página, selecione Edit para permitir a edição dos seus recursos Azure.

  2. No navegador à esquerda, aprofunde-se em config>authsettingsV2.

  3. Na visualização authsettingsV2, selecione Editar.

  4. Encontre a secção de login do identityProviders>azureActiveDirectory e adicione as seguintes definições de LoginParparameters : "loginParameters":[ "response_type=code id_token","scope=openid offline_access profile https://graph.microsoft.com/User.Read" ].

    "identityProviders": {
    "azureActiveDirectory": {
      "enabled": true,
      "login": {
        "loginParameters":[
          "response_type=code id_token",
          "scope=openid offline_access profile https://graph.microsoft.com/User.Read"
        ]
      }
    }
  }
},

  5. Salve suas configurações selecionando PUT.

Essa configuração pode levar vários minutos para entrar em vigor. A sua aplicação web está agora configurada para aceder ao Microsoft Graph com um token de acesso adequado. Se não o fizer, o Microsoft Graph retorna um erro que indica que o formato do token compacto está incorreto.

Chamar o Microsoft Graph a partir do Node.js

A sua aplicação web tem agora as permissões necessárias. Também adiciona o ID do cliente do Microsoft Graph aos parâmetros de login.

Instalar pacotes de biblioteca cliente

Instale os pacotes @azure/identity e os pacotes @microsoft/microsoft-graph-client no seu projeto com o npm.

npm install @microsoft/microsoft-graph-client

Configurar informações de autenticação

Crie um objeto para manter as configurações de autenticação:

// partial code in app.js
const appSettings = {
    appCredentials: {
        clientId: process.env.WEBSITE_AUTH_CLIENT_ID, // Enter the client Id here,
        tenantId: "common", // Enter the tenant info here,
        clientSecret: process.env.MICROSOFT_PROVIDER_AUTHENTICATION_SECRET // Enter the client secret here,
    },
    authRoutes: {
        redirect: "/.auth/login/aad/callback", // Enter the redirect URI here
        error: "/error", // enter the relative path to error handling route
        unauthorized: "/unauthorized" // enter the relative path to unauthorized route
    },
    protectedResources: {
        graphAPI: {
            endpoint: "https://graph.microsoft.com/v1.0/me", // resource endpoint
            scopes: ["User.Read"] // resource scopes
        },
    },
}

Ligue para a Microsoft Graph em nome do utilizador

O código seguinte mostra como chamar o controlador Microsoft Graph como a aplicação e obter alguma informação do utilizador.

// controllers/graphController.js

// get the name of the app service instance from environment variables
const appServiceName = process.env.WEBSITE_SITE_NAME;

const graphHelper = require('../utils/graphHelper');

exports.getProfilePage = async(req, res, next) => {

    try {
        // get user's access token scoped to Microsoft Graph from session
        // use token to create Graph client
        const graphClient = graphHelper.getAuthenticatedClient(req.session.protectedResources["graphAPI"].accessToken);

        // return user's profile
        const profile = await graphClient
            .api('/me')
            .get();

        res.render('profile', { isAuthenticated: req.session.isAuthenticated, profile: profile, appServiceName: appServiceName });   
    } catch (error) {
        next(error);
    }
}

O código anterior baseia-se na seguinte função getAuthenticatedClient para devolver o cliente Microsoft Graph.

// utils/graphHelper.js

const graph = require('@microsoft/microsoft-graph-client');

getAuthenticatedClient = (accessToken) => {
    // Initialize Graph client
    const client = graph.Client.init({
        // Use the provided access token to authenticate requests
        authProvider: (done) => {
            done(null, accessToken);
        }
    });

    return client;
}

Limpar recursos

Se você concluiu todas as etapas neste tutorial com várias partes, criou um Serviço de Aplicativo, um plano de hospedagem do Serviço de Aplicativo e uma conta de armazenamento em um grupo de recursos. Também criou um registo de aplicação no Microsoft Entra ID. Se escolheste uma configuração externa, podes ter criado um novo inquilino externo. Quando não for mais necessário, exclua esses recursos e o registro do aplicativo para não continuar acumulando cobranças.

Neste tutorial, irá aprender a:

  • Apaga os recursos do Azure criados enquanto segues o tutorial.

Eliminar o grupo de recursos

  1. No portal Azure, no menu do portal Azure, selecione Grupos de recursos.

  2. Selecione o grupo de recursos que contém o seu Serviço de Aplicações e plano de Serviços de Aplicações.

  3. Selecione Excluir grupo de recursos para excluir o grupo de recursos e todos os recursos.

    Captura de tela que mostra a exclusão do grupo de recursos.

Esta ação pode demorar vários minutos.

Excluir o registro do aplicativo

  1. No centro de administração do Microsoft Entra, selecione Registos de Aplicações. Em seguida, selecione o aplicativo que você criou.

    Captura de ecrã que mostra a seleção do registo na aplicação.

  2. Na visão geral de registro do aplicativo, selecione Excluir.

    Captura de ecrã que mostra a eliminação do registo da aplicação.

Excluir o locatário externo

Se você criou um novo locatário externo, poderá excluí-lo.

  1. No centro de administração do Microsoft Entra, navegue até Entra ID>Visão Geral>Gerir locatários.

  2. Selecione o inquilino que pretende eliminar e, em seguida, selecione Eliminar.

    Talvez seja necessário concluir as ações necessárias antes de excluir o locatário. Por exemplo, talvez seja necessário excluir todos os fluxos de usuários e registros de aplicativos no locatário.

  3. Se você estiver pronto para excluir o locatário, selecione Excluir.

Próximos passos

Neste tutorial, ficou a saber como:

  • Conceda permissões delegadas a um aplicativo Web.
  • Chame a Microsoft Graph a partir de uma aplicação web para um utilizador autenticado.

O serviço de aplicativo acede ao Microsoft Graph como um aplicativo

  • Last updated on