Tutorial: Mengakses Microsoft Graph dari aplikasi aman sebagai pengguna

Pelajari cara mengakses Microsoft Graph dari aplikasi web yang berjalan di Azure App Service.

Anda ingin menambah akses ke Microsoft Graph dari aplikasi web dan melakukan beberapa tindakan sebagai pengguna masuk. Bagian ini menjelaskan cara memberikan izin yang didelegasikan ke aplikasi web dan mendapatkan informasi profil pengguna yang masuk dari ID Microsoft Entra.

Dalam tutorial ini, Anda akan mempelajari cara:

• Memberikan izin yang didelegasikan ke aplikasi web.
• Panggil Microsoft Graph dari aplikasi web untuk pengguna yang masuk.

Jika Anda tidak memiliki Langganan Azure, buat Akun gratis Azure sebelum memulai.

Prasyarat

• Aplikasi web yang berjalan di Azure App Service yang mengaktifkan modul autentikasi/otorisasi Layanan Aplikasi.

Memberikan akses front-end untuk memanggil Microsoft Graph

Sekarang setelah Anda mengaktifkan autentikasi dan otorisasi di aplikasi web Anda, aplikasi web terdaftar dengan platform identitas Microsoft dan didukung oleh aplikasi Microsoft Entra. Dalam langkah ini, Anda memberikan izin aplikasi web untuk mengakses Microsoft Graph untuk pengguna. (Secara teknis, Anda memberi aplikasi Microsoft Entra aplikasi web izin untuk mengakses aplikasi Microsoft Graph Microsoft Entra untuk pengguna.)

Di menu pusat admin Microsoft Entra, pilih Aplikasi.

Pilih Pendaftaran aplikasi>Aplikasi yang dimiliki>Lihat semua aplikasi dalam direktori ini. Pilih nama aplikasi web Anda, lalu pilih izin API.

Pilih Tambah izin, lalu pilih Microsoft API dan Microsoft Graph.

Pilih Izin yang didelegasikan, lalu pilih Pengguna.Baca dari daftar. Pilih Tambahkan izin.

Mengonfigurasi App Service untuk mengembalikan token akses yang dapat digunakan

Aplikasi web sekarang memiliki izin yang diperlukan untuk mengakses Microsoft Graph sebagai pengguna masuk. Dalam langkah ini, Anda mengonfigurasi autentikasi dan otorisasi Layanan Aplikasi untuk memberi token akses yang dapat digunakan untuk mengakses Microsoft Graph. Untuk langkah ini, Anda perlu menambahkan cakupan User.Read untuk layanan downstream (Microsoft Graph): https://graph.microsoft.com/User.Read.

Penting

Jika Anda tidak mengonfigurasi Layanan Aplikasi untuk mengembalikan token akses yang dapat digunakan, Anda menerima CompactToken parsing failed with error code: 80049217 kesalahan saat memanggil API Microsoft Graph dalam kode Anda.

Azure Resource Explorer

Buka Azure Resource Explorer dan menggunakan pohon sumber daya, temukan aplikasi web Anda. URL sumber daya harus mirip dengan https://resources.azure.com/subscriptions/subscriptionId/resourceGroups/SecureWebApp/providers/Microsoft.Web/sites/SecureWebApp20200915115914.

Azure Resource Explorer sekarang dibuka dengan aplikasi web Anda dipilih di pohon sumber daya. Di bagian atas halaman, pilih Baca/Tulis untuk mengaktifkan pengeditan sumber daya Azure Anda.

Di browser kiri, telusuri paling detail untuk config>authsettingsV2.

Dalam tampilan authsettingsV2, pilih Edit. Temukan bagian login dari identityProviders ->azureActiveDirectory dan tambahkan pengaturan loginParameters berikut: "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"
        ]
      }
    }
  }
},

Simpan pengaturan Anda dengan memilih PUT. Pengaturan ini dapat memerlukan waktu beberapa menit untuk diterapkan. Aplikasi web Anda sekarang dikonfigurasi untuk mengakses Microsoft Graph dengan token akses yang tepat. Jika tidak, Microsoft Graph mengembalikan kesalahan yang mengatakan bahwa format token ringkas salah.

Azure CLI

Gunakan Azure CLI untuk memanggil API REST Aplikasi Web App Service untuk mendapatkan dan memperbarui pengaturan konfigurasi autentikasi sehingga aplikasi web Anda dapat memanggil Microsoft Graph. Buka jendela perintah dan masuk ke Azure CLI:

az login

Dapatkan pengaturan 'config/authsettingsv2' yang ada dan simpan ke file authsettings.json lokal.

az rest --method GET --url '/subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.Web/sites/{WEBAPP_NAME}/config/authsettingsv2/list?api-version=2020-06-01' > authsettings.json

Buka file authsettings.json menggunakan editor teks pilihan Anda. Temukan bagian login dari identityProviders ->azureActiveDirectory dan tambahkan pengaturan loginParameters berikut: "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"
        ]
      }
    }
  }
},

Simpan perubahan Anda ke file authsettings.json dan unggah pengaturan lokal ke aplikasi web Anda:

az rest --method PUT --url '/subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.Web/sites/{WEBAPP_NAME}/config/authsettingsv2?api-version=2020-06-01' --body @./authsettings.json

Memanggil Microsoft Graph

Aplikasi web Anda sekarang memiliki izin yang diperlukan dan juga menambah ID klien Microsoft Graph ke parameter login.

C#

Menggunakan pustaka Microsoft.Identity.Web, aplikasi web mendapatkan token akses untuk autentikasi dengan Microsoft Graph. Di versi 1.2.0 dan yang lebih baru, pustaka Microsoft.Identity.Web terintegrasi dengan dan dapat berjalan bersama modul autentikasi/otorisasi Layanan Aplikasi. Microsoft.Identity.Web mendeteksi bahwa aplikasi web dihosting di Layanan Aplikasi dan mendapatkan token akses dari modul autentikasi/otorisasi Layanan Aplikasi. Token akses kemudian diteruskan ke permintaan terautentikasi dengan Microsoft Graph API.

Untuk melihat kode ini sebagai bagian dari aplikasi sampel, lihat sampel di GitHub.

Catatan

Pustaka Microsoft.Identity.Web tidak diperlukan di aplikasi web Anda untuk autentikasi/otorisasi dasar atau untuk mengautentikasi permintaan dengan Microsoft Graph. Dimungkinkan untuk memanggil API hilir dengan aman hanya dengan modul autentikasi/otorisasi Layanan Aplikasi yang diaktifkan.

Namun, autentikasi/otorisasi Layanan Aplikasi dirancang untuk skenario autentikasi yang lebih mendasar. Untuk skenario yang lebih kompleks (menangani klaim kustom, contohnya), Anda memerlukan pustaka Microsoft.Identity.Web atau Pustaka Autentikasi Microsoft. Ada sedikit lebih banyak pekerjaan pengaturan dan konfigurasi di awal, tetapi pustaka Microsoft.Identity.Web dapat berjalan bersama modul autentikasi /otorisasi Layanan Aplikasi. Nantinya, ketika aplikasi web Anda perlu menangani skenario yang lebih kompleks, Anda dapat menonaktifkan modul autentikasi/otorisasi Layanan Aplikasi dan Microsoft.Identity.Web sudah menjadi bagian dari aplikasi Anda.

Instal paket pustaka klien

Instal paket NuGet Microsoft.Identity.Web dan Microsoft.Identity.Web.GraphServiceClient di proyek Anda dengan menggunakan antarmuka baris perintah (CLI) .NET atau Package Manager Console di Visual Studio.

.NET CLI

Buka baris perintah, dan beralih ke direktori yang memuat file proyek Anda.

Jalankan perintah instalasi.

dotnet add package Microsoft.Identity.Web.GraphServiceClient

dotnet add package Microsoft.Identity.Web

Konsol Manajer Paket

Buka proyek/solusi di Visual Studio, dan buka konsol dengan menggunakan perintah Alat>Manajer Paket NuGet>Konsol Manajer Paket.

Jalankan perintah instalasi.

Install-Package Microsoft.Identity.Web.GraphServiceClient

Install-Package Microsoft.Identity.Web

Startup.cs

Dalam file Startup.cs, metode AddMicrosoftIdentityWebApp ini menambah Microsoft.Identity.Web ke aplikasi web Anda. Metode AddMicrosoftGraph ini menambah dukungan Microsoft Graph.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Identity.Web;
using Microsoft.AspNetCore.Authentication.OpenIdConnect;

// Some code omitted for brevity.
public class Startup
{
    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
      services.AddOptions();
      string[] initialScopes = Configuration.GetValue<string>("DownstreamApi:Scopes")?.Split(' ');

      services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
              .AddMicrosoftIdentityWebApp(Configuration.GetSection("AzureAd"))
              .EnableTokenAcquisitionToCallDownstreamApi(initialScopes)
                      .AddMicrosoftGraph(Configuration.GetSection("DownstreamApi"))
                      .AddInMemoryTokenCaches(); 

      services.AddAuthorization(options =>
      {
          // By default, all incoming requests will be authorized according to the default policy
          options.FallbackPolicy = options.DefaultPolicy;
      });
      services.AddRazorPages()
          .AddMvcOptions(options => {})                
          .AddMicrosoftIdentityUI();

      services.AddControllersWithViews()
              .AddMicrosoftIdentityUI();
    }
}

appsettings.json

ID Microsoft Entra menentukan konfigurasi untuk pustaka Microsoft.Identity.Web. Di pusat admin Microsoft Entra, pilih Aplikasi dari menu portal lalu pilih Pendaftaran aplikasi. Pilih pendaftaran aplikasi yang dibuat saat Anda mengaktifkan modul autentikasi/otorisasi Layanan Aplikasi. (Pendaftaran aplikasi harus memiliki nama yang sama dengan aplikasi web.) Anda dapat menemukan ID penyewa dan ID klien di halaman ringkasan pendaftaran aplikasi. Nama domain dapat ditemukan di halaman gambaran umum Microsoft Entra untuk penyewa Anda.

Grafik menentukan titik akhir Microsoft Graph dan cakupan awal yang diperlukan oleh aplikasi.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "Domain": "[Enter the domain of your tenant, e.g. contoso.onmicrosoft.com]",
    "TenantId": "[Enter 'common', or 'organizations' or the Tenant Id (Obtained from the Entra admin center. Select 'Endpoints' from the 'App registrations' blade and use the GUID in any of the URLs), e.g. aaaabbbb-0000-cccc-1111-dddd2222eeee]",
    "ClientId": "[Enter the Client Id (Application ID obtained from the Microsoft Entra admin center), e.g. 00001111-aaaa-2222-bbbb-3333cccc4444]",
    "ClientSecret": "[Copy the client secret added to the app from the Microsoft Entra admin center]",
    "ClientCertificates": [
    ],
    // the following is required to handle Continuous Access Evaluation challenges
    "ClientCapabilities": [ "cp1" ],
    "CallbackPath": "/signin-oidc"
  },
  "DownstreamApis": {
    "MicrosoftGraph": {
      // Specify BaseUrl if you want to use Microsoft graph in a national cloud.
      // See https://learn.microsoft.com/graph/deployments#microsoft-graph-and-graph-explorer-service-root-endpoints
      // "BaseUrl": "https://graph.microsoft.com/v1.0",

      // Set RequestAppToken this to "true" if you want to request an application token (to call graph on 
      // behalf of the application). The scopes will then automatically
      // be ['https://graph.microsoft.com/.default'].
      // "RequestAppToken": false

      // Set Scopes to request (unless you request an app token).
      "Scopes": [ "User.Read" ]

      // See https://aka.ms/ms-id-web/downstreamApiOptions for all the properties you can set.
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

Index.cshtml.cs

Contoh berikut memperlihatkan cara memanggil Microsoft Graph sebagai pengguna yang masuk dan mendapatkan beberapa informasi pengguna. Objek GraphServiceClient disuntikkan ke pengontrol, dan autentikasi telah dikonfigurasi untuk Anda oleh pustaka Microsoft.Identity.Web.

using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.Graph;
using System.IO;
using Microsoft.Identity.Web;
using Microsoft.Extensions.Logging;

// Some code omitted for brevity.

[AuthorizeForScopes(Scopes = new[] { "User.Read" })]
public class IndexModel : PageModel
{
    private readonly ILogger<IndexModel> _logger;
    private readonly GraphServiceClient _graphServiceClient;

    public IndexModel(ILogger<IndexModel> logger, GraphServiceClient graphServiceClient)
    {
        _logger = logger;
        _graphServiceClient = graphServiceClient;
    }

    public async Task OnGetAsync()
    {
        try
        {
            var user = await _graphServiceClient.Me.GetAsync();
            ViewData["Me"] = user;
            ViewData["name"] = user.DisplayName;

            using (var photoStream = await _graphServiceClient.Me.Photo.Content.GetAsync())
            {
                byte[] photoByte = ((MemoryStream)photoStream).ToArray();
                ViewData["photo"] = Convert.ToBase64String(photoByte);
            }
        }
        catch (Exception ex)
        {
            ViewData["photo"] = null;
        }
    }
}

Node.js

Menggunakan kelas AuthProvider kustom yang merangkum logika autentikasi, aplikasi web mendapatkan token akses pengguna dari header permintaan masuk. Instans AuthProvider mendeteksi bahwa aplikasi web dihosting di App Service dan mendapatkan token akses dari modul autentikasi/otorisasi App Service. Token akses kemudian diteruskan ke klien Microsoft Graph SDK untuk membuat permintaan terautentikasi ke /me titik akhir.

Untuk melihat kode ini sebagai bagian dari contoh aplikasi, lihat StorageHelper.js di contoh di GitHub.

Catatan

Autentikasi/otorisasi App Service dirancang untuk skenario autentikasi yang lebih dasar. Nantinya, ketika aplikasi web Anda perlu menangani skenario yang lebih kompleks, Anda dapat menonaktifkan modul autentikasi/otorisasi App Service dan instans AuthProvider dalam sampel akan mundur untuk menggunakan MSAL Node, yang merupakan pustaka yang direkomendasikan untuk menambahkan autentikasi/otorisasi ke aplikasi Node.js.

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

// Some code omitted for brevity.

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

    try {
        const graphClient = graphHelper.getAuthenticatedClient(req.session.protectedResources["graphAPI"].accessToken);

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

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

Untuk meminta Microsoft Graph, gunakan Microsoft Graph JavaScript SDK. Kode untuk ini terletak di utils / graphHelper.js:

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

// Some code omitted for brevity.

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

Membersihkan sumber daya

Jika Anda sudah selesai dengan tutorial ini dan tidak lagi memerlukan aplikasi web atau sumber daya terkait, bersihkan sumber daya yang Anda buat.

Langkah berikutnya

Layanan aplikasi mengakses Microsoft Graph sebagai aplikasi