Acessar o Microsoft Graph em um aplicativo protegido como o aplicativo

Saiba como acessar o Microsoft Graph de um aplicativo Web em execução no Serviço de Aplicativo do Azure.

Você deseja chamar o Microsoft Graph para o aplicativo Web. Um modo seguro de permitir o acesso do aplicativo Web aos dados é usar uma identidade gerenciada atribuída ao sistema. Uma identidade gerenciada da ID do Microsoft Entra permite que o Serviço de Aplicativo acesse recursos pelo controle de acesso baseado em função (RBAC), sem a necessidade de credenciais do aplicativo. Depois de atribuir uma identidade gerenciada ao seu aplicativo Web, o Azure cuida da criação e da distribuição de um certificado. Você não precisa se preocupar em gerenciar segredos nem credenciais de aplicativo.

Neste tutorial, você aprenderá como:

• Criar uma identidade gerenciada atribuída ao sistema em um aplicativo Web.
• Adicionar permissões de API do Microsoft Graph a uma identidade gerenciada.
• Chamar o Microsoft Graph em um aplicativo Web usando identidades gerenciadas.

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

Pré-requisitos

• Um aplicativo Web em execução no Serviço de Aplicativo do Azure que tem o módulo de autenticação/autorização do Serviço de Aplicativo habilitado.

Habilitar a identidade gerenciada no aplicativo

Se você criar e publicar o aplicativo Web por meio do Visual Studio, a identidade gerenciada foi habilitada no aplicativo para você. No serviço de aplicativo, selecione Identidade no painel esquerdo e escolha Atribuído ao sistema. Verifique se Status está definido como Ativado. Caso contrário, selecione Salvar e Sim para habilitar a identidade gerenciada atribuída ao sistema. Quando a identidade gerenciada é habilitada, o status é definido como Ativado e a ID do objeto fica disponível.

Anote o valor da ID do Objeto, que será necessária na próxima etapa.

Permitir acesso ao Microsoft Graph

Ao acessar o Microsoft Graph, a identidade gerenciada precisa ter as permissões adequadas para a operação que ele deseja executar. Atualmente, não há opção para atribuir essas permissões por meio do centro de administração do Microsoft Entra. O script a seguir adicionará as permissões de API do Microsoft Graph solicitadas ao objeto de entidade de serviço de identidade gerenciada.

PowerShell

# Install the module.
# Install-Module Microsoft.Graph -Scope CurrentUser

# The tenant ID
$TenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee"

# The name of your web app, which has a managed identity.
$webAppName = "SecureWebApp-20201106120003" 
$resourceGroupName = "SecureWebApp-20201106120003ResourceGroup"

# The name of the app role that the managed identity should be assigned to.
$appRoleName = "User.Read.All"

# Get the web app's managed identity's object ID.
Connect-AzAccount -Tenant $TenantId
$managedIdentityObjectId = (Get-AzWebApp -ResourceGroupName $resourceGroupName -Name $webAppName).identity.principalid

Connect-MgGraph -TenantId $TenantId -Scopes 'Application.Read.All','AppRoleAssignment.ReadWrite.All'

# Get Microsoft Graph app's service principal and app role.
$serverApplicationName = "Microsoft Graph"
$serverServicePrincipal = (Get-MgServicePrincipal -Filter "DisplayName eq '$serverApplicationName'")
$serverServicePrincipalObjectId = $serverServicePrincipal.Id

$appRoleId = ($serverServicePrincipal.AppRoles | Where-Object {$_.Value -eq $appRoleName }).Id

# Assign the managed identity access to the app role.
New-MgServicePrincipalAppRoleAssignment `
    -ServicePrincipalId $managedIdentityObjectId `
    -PrincipalId $managedIdentityObjectId `
    -ResourceId $serverServicePrincipalObjectId `
    -AppRoleId $appRoleId

CLI do Azure

az login

webAppName="SecureWebApp-20201106120003"

spId=$(az resource list -n $webAppName --query [*].identity.principalId --out tsv)

graphResourceId=$(az ad sp list --display-name "Microsoft Graph" --query [0].id --out tsv)

appRoleId=$(az ad sp list --display-name "Microsoft Graph" --query "[0].appRoles[?value=='User.Read.All' && contains(allowedMemberTypes, 'Application')].id" --output tsv)

uri=https://graph.microsoft.com/v1.0/servicePrincipals/$spId/appRoleAssignments

body="{'principalId':'$spId','resourceId':'$graphResourceId','appRoleId':'$appRoleId'}"

az rest --method post --uri $uri --body $body --headers "Content-Type=application/json"

Depois de executar o script, é possível verificar no centro de administração do Microsoft Entra se as permissões de API solicitadas foram atribuídas à identidade gerenciada.

Acesse Aplicativos e, em seguida, selecione Aplicativos empresariais. Esse painel exibe todas as entidades de serviço no seu locatário. Adicione um filtro para “Tipo de aplicativo == Identidades Gerenciadas” e selecione a entidade de serviço para a identidade gerenciada.

Se você estiver seguindo este tutorial, haverá duas entidades de serviço com o mesmo nome de exibição (SecureWebApp2020094113531, por exemplo). A entidade de serviço que tem uma URL de Home Page representa o aplicativo Web no locatário. A entidade de serviço que aparece em Identidades Gerenciadasnão deve ter uma URL de Home Page listada e a ID do objeto deve corresponder ao valor da ID de objeto da identidade gerenciada na etapa anterior.

Selecione a entidade de serviço para a identidade gerenciada.

Em Visão geral, selecione Permissões e você verá as permissões adicionadas ao Microsoft Graph.

Chamar o Microsoft Graph

C#

As classes ChainedTokenCredential, ManagedIdentityCredential e EnvironmentCredential são usadas para obtenção de uma credencial de token para o código destinada à autorização de solicitações ao Microsoft Graph. Crie uma instância da classe ChainedTokenCredential, que usa a identidade gerenciada no ambiente do Serviço de Aplicativo ou as variáveis de ambiente de desenvolvimento para buscar tokens e anexá-los ao cliente do serviço. O exemplo de código a seguir obtém a credencial de token autenticada e a usa para criar um objeto de cliente de serviço, que obtém os usuários no grupo.

Para ver esse código como parte de um aplicativo de exemplo, confira o exemplo no GitHub.

Instalar o pacote de biblioteca de clientes Microsoft.Identity.Web.GraphServiceClient

Instale os pacotes NuGet Microsoft.Graph e Microsoft.Identity.Web.GraphServiceClient em seu projeto usando a interface de linha de comando (CLI) do .NET ou o console do gerenciador de pacotes no Visual Studio.

CLI do .NET

Abra uma linha de comando e alterne para o diretório que contém o arquivo de projeto.

Execute os comandos de instalação.

dotnet add package Microsoft.Identity.Web.GraphServiceClient
dotnet add package Microsoft.Graph

Console do Gerenciador de Pacotes

Abra o projeto/a solução no Visual Studio e abra o console do usando o comando Ferramentas>Gerenciador de Pacotes NuGet>Console do Gerenciador de Pacotes.

Execute os comandos de instalação.

Install-Package Microsoft.Identity.Web.GraphServiceClient
Install-Package Microsoft.Graph

Exemplo

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.Extensions.Logging;
using Microsoft.Graph;
using Azure.Identity;

...

public IList<MSGraphUser> Users { get; set; }

public async Task OnGetAsync()
{
    // Create the Graph service client with a ChainedTokenCredential which gets an access
    // token using the available Managed Identity or environment variables if running
    // in development.
    var credential = new ChainedTokenCredential(
        new ManagedIdentityCredential(),
        new EnvironmentCredential());

    string[] scopes = new[] { "https://graph.microsoft.com/.default" };

    var graphServiceClient = new GraphServiceClient(
        credential, scopes);

    List<MSGraphUser> msGraphUsers = new List<MSGraphUser>();
    try
    {
        //var users = await graphServiceClient.Users.Request().GetAsync();
        var users = await graphServiceClient.Users.GetAsync();
        foreach (var u in users.Value)
        {
            MSGraphUser user = new MSGraphUser();
            user.userPrincipalName = u.UserPrincipalName;
            user.displayName = u.DisplayName;
            user.mail = u.Mail;
            user.jobTitle = u.JobTitle;

            msGraphUsers.Add(user);
        }
    }
    catch (Exception ex)
    {
        string msg = ex.Message;
    }

    Users = msGraphUsers;
}

Node.js

A classe DefaultAzureCredential do pacote DefaultAzureCredential é usada para obter credenciais de token para o código autorizar solicitações no Armazenamento do Microsoft Azure. Crie uma instância da classe DefaultAzureCredential, que usa a identidade gerenciada para buscar tokens e anexá-los ao cliente do serviço. O exemplo de código a seguir obtém a credencial de token autenticada e a usa para criar um objeto de cliente de serviço, que obtém os usuários no grupo.

Exemplo

const graphHelper = require('../utils/graphHelper');
const { DefaultAzureCredential } = require("@azure/identity");

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

    const defaultAzureCredential = new DefaultAzureCredential();
    
    try {
        const tokenResponse = await defaultAzureCredential.getToken("https://graph.microsoft.com/.default");

        const graphClient = graphHelper.getAuthenticatedClient(tokenResponse.token);

        const users = await graphClient
            .api('/users')
            .get();

        res.render('users', { user: req.session.user, users: users });   
    } catch (error) {
        next(error);
    }
}

Para consultar o Microsoft Graph, o exemplo usa o SDK do Microsoft Graph para JavaScript.

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

Se você concluiu este tutorial e não precisa mais do aplicativo Web nem dos recursos associados, limpe os recursos que você criou.

Próximas etapas

Limpar os recursos)