Udostępnij za pośrednictwem


Samouczek: uzyskiwanie dostępu do programu Microsoft Graph z zabezpieczonej aplikacji .NET jako użytkownika

Dowiedz się, jak uzyskać dostęp do programu Microsoft Graph z poziomu aplikacji internetowej działającej w usłudze aplikacja systemu Azure Service.

Diagram przedstawiający dostęp do programu Microsoft Graph.

Chcesz dodać dostęp do programu Microsoft Graph z aplikacji internetowej i wykonać jakąś akcję jako zalogowany użytkownik. W tej sekcji opisano sposób udzielania delegowanych uprawnień do aplikacji internetowej i uzyskiwania informacji o profilu zalogowanego użytkownika z identyfikatora Entra firmy Microsoft.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

  • Przyznawanie delegowanych uprawnień do aplikacji internetowej.
  • Wywołaj program Microsoft Graph z aplikacji internetowej dla zalogowanego użytkownika.

Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto platformy Azure.

Wymagania wstępne

  • Aplikacja internetowa działająca w usłudze aplikacja systemu Azure z włączonym modułem uwierzytelniania/autoryzacji usługi App Service.

Udzielanie dostępu frontonu w celu wywołania programu Microsoft Graph

Po włączeniu uwierzytelniania i autoryzacji w aplikacji internetowej aplikacja internetowa jest zarejestrowana w Platforma tożsamości Microsoft i jest wspierana przez aplikację Firmy Microsoft Entra. W tym kroku przyznasz aplikacji internetowej uprawnienia dostępu do programu Microsoft Graph dla użytkownika. (Technicznie należy przyznać aplikacji internetowej Microsoft Entra uprawnienia dostępu do aplikacji Microsoft Entra programu Microsoft Graph dla użytkownika).

  1. W centrum administracyjnym firmy Microsoft Entra wybierz pozycję Aplikacje.

  2. Wybierz pozycję Rejestracje aplikacji> Owned aplikacje>Wyświetl wszystkie aplikacje w tym katalogu. Wybierz nazwę aplikacji internetowej, a następnie wybierz pozycję Uprawnienia interfejsu API.

  3. Wybierz pozycję Dodaj uprawnienie, a następnie wybierz pozycję Interfejsy API firmy Microsoft i program Microsoft Graph.

  4. Wybierz pozycję Delegowane uprawnienia, a następnie wybierz pozycję User.Read z listy. Wybierz Przyznaj uprawnienia.

Konfigurowanie usługi App Service do zwracania nadającego się do użycia tokenu dostępu

Aplikacja internetowa ma teraz wymagane uprawnienia dostępu do programu Microsoft Graph jako zalogowany użytkownik. W tym kroku skonfigurujesz uwierzytelnianie i autoryzację usługi App Service w celu udzielenia użytecznego tokenu dostępu do uzyskiwania dostępu do programu Microsoft Graph. W tym kroku należy dodać zakres User.Read dla usługi podrzędnej (Microsoft Graph): https://graph.microsoft.com/User.Read.

Ważne

Jeśli nie skonfigurujesz usługi App Service w celu zwrócenia użytecznego tokenu dostępu, podczas wywoływania interfejsów API programu Microsoft Graph w kodzie wystąpi CompactToken parsing failed with error code: 80049217 błąd.

Przejdź do Eksploratora zasobów platformy Azure i użyj drzewa zasobów, znajdź aplikację internetową. Adres URL zasobu powinien być podobny do https://resources.azure.com/subscriptions/subscriptionId/resourceGroups/SecureWebApp/providers/Microsoft.Web/sites/SecureWebApp20200915115914.

Eksplorator zasobów platformy Azure jest teraz otwierany przy użyciu aplikacji internetowej wybranej w drzewie zasobów.

  1. W górnej części strony wybierz pozycję Odczyt/Zapis , aby włączyć edytowanie zasobów platformy Azure.

  2. W lewej przeglądarce przejdź do szczegółów konfiguracji>authsettingsV2.

  3. W widoku authsettingsV2 wybierz pozycję Edytuj.

  4. Znajdź sekcję logowania identityProviders ->azureActiveDirectory i dodaj następujące ustawienia loginParameters: "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. Zapisz ustawienia, wybierając pozycję PUT. Zastosowanie tego ustawienia może potrwać kilka minut. Aplikacja internetowa jest teraz skonfigurowana do uzyskiwania dostępu do programu Microsoft Graph przy użyciu odpowiedniego tokenu dostępu. Jeśli tego nie zrobisz, program Microsoft Graph zwróci błąd z informacją, że format tokenu kompaktowego jest niepoprawny.

Wywoływanie programu Microsoft Graph za pomocą platformy .NET

Aplikacja internetowa ma teraz wymagane uprawnienia, a także dodaje identyfikator klienta programu Microsoft Graph do parametrów logowania.

Korzystając z biblioteki Microsoft.Identity.Web, aplikacja internetowa pobiera token dostępu do uwierzytelniania za pomocą programu Microsoft Graph. W wersji 1.2.0 lub nowszej biblioteka Microsoft.Identity.Web integruje się z modułem i może działać wraz z modułem uwierzytelniania/autoryzacji usługi App Service. Microsoft.Identity.Web wykrywa, że aplikacja internetowa jest hostowana w usłudze App Service i pobiera token dostępu z modułu uwierzytelniania/autoryzacji usługi App Service. Token dostępu jest następnie przekazywany do uwierzytelnionych żądań przy użyciu interfejsu API programu Microsoft Graph.

Aby zobaczyć ten kod w ramach przykładowej aplikacji, zobacz:

Uwaga

Biblioteka Microsoft.Identity.Web nie jest wymagana w aplikacji internetowej do podstawowego uwierzytelniania/autoryzacji ani do uwierzytelniania żądań za pomocą programu Microsoft Graph. Można bezpiecznie wywoływać podrzędne interfejsy API tylko z włączonym modułem uwierzytelniania/autoryzacji usługi App Service.

Jednak uwierzytelnianie/autoryzacja usługi App Service jest przeznaczone dla bardziej podstawowych scenariuszy uwierzytelniania. W przypadku bardziej złożonych scenariuszy (na przykład obsługi oświadczeń niestandardowych) potrzebna jest biblioteka Microsoft.Identity.Web lub biblioteka Microsoft Authentication Library. Na początku działa nieco więcej konfiguracji i konfiguracji, ale biblioteka Microsoft.Identity.Web może działać razem z modułem uwierzytelniania/autoryzacji usługi App Service. Później, gdy aplikacja internetowa musi obsługiwać bardziej złożone scenariusze, możesz wyłączyć moduł uwierzytelniania/autoryzacji usługi App Service, a witryna Microsoft.Identity.Web będzie już częścią aplikacji.

Instalowanie pakietów bibliotek klienta

Zainstaluj pakiety NuGet Microsoft.Identity.Web i Microsoft.Identity.Web.MicrosoftGraph w projekcie przy użyciu interfejsu wiersza polecenia platformy .NET Core lub konsoli Menedżer pakietów w programie Visual Studio.

Wiersz polecenia platformy .NET Core

Otwórz wiersz polecenia i przejdź do katalogu zawierającego plik projektu.

Uruchom polecenia instalacji.

dotnet add package Microsoft.Identity.Web.MicrosoftGraph

dotnet add package Microsoft.Identity.Web

Konsola menedżera pakietów

Otwórz projekt/rozwiązanie w programie Visual Studio i otwórz konsolę za pomocą polecenia Narzędzia>NuGet Menedżer pakietów> Menedżer pakietów Console.

Uruchom polecenia instalacji.

Install-Package Microsoft.Identity.Web.GraphServiceClient

Install-Package Microsoft.Identity.Web

Startup.cs

W pliku AddMicrosoftIdentityWebApp Startup.cs metoda dodaje plik Microsoft.Identity.Web do aplikacji internetowej. Metoda AddMicrosoftGraph dodaje obsługę programu Microsoft Graph. Aby uzyskać informacje na temat zarządzania zgody przyrostowej i dostępu warunkowego, przeczytaj ten artykuł.

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

AzureAd określa konfigurację biblioteki Microsoft.Identity.Web. W centrum administracyjnym firmy Microsoft Entra wybierz pozycję Aplikacje z menu portalu, a następnie wybierz pozycję Rejestracje aplikacji. Wybierz rejestrację aplikacji utworzoną po włączeniu modułu uwierzytelniania/autoryzacji usługi App Service. (Rejestracja aplikacji powinna mieć taką samą nazwę jak aplikacja internetowa). Identyfikator dzierżawy i identyfikator klienta można znaleźć na stronie przeglądu rejestracji aplikacji. Nazwę domeny można znaleźć na stronie przeglądu firmy Microsoft dla twojej dzierżawy.

Program Graph określa punkt końcowy programu Microsoft Graph i początkowe zakresy wymagane przez aplikację.

{
  "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 Microsoft Entra admin center. Select 'Endpoints' from the 'App registrations' blade and use the GUID in any of the URLs), e.g. da41245a5-11b3-996c-00a8-4d99re19f292]",
    "ClientId": "[Enter the Client Id (Application ID obtained from the Microsoft Entra admin center), e.g. ba74781c2-53c2-442a-97c2-3d60re42f403]",
    "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": "*"
}

Wywoływanie programu Microsoft Graph w imieniu użytkownika

W poniższym przykładzie pokazano, jak wywołać program Microsoft Graph jako zalogowany użytkownik i uzyskać informacje o użytkowniku. Obiekt GraphServiceClient jest wstrzykiwany do kontrolera, a uwierzytelnianie zostało skonfigurowane przez bibliotekę Microsoft.Identity.Web.

// Index.cshtml.cs
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;
        }
    }
}

Czyszczenie zasobów

Jeśli wszystkie kroki opisane w tym samouczku wieloczęściowym zostały wykonane, utworzono usługę App Service, plan hostingu usługi App Service i konto magazynu w grupie zasobów. Utworzono również rejestrację aplikacji w identyfikatorze Entra firmy Microsoft. Jeśli wybrano konfigurację zewnętrzną, być może utworzono nową dzierżawę zewnętrzną. Gdy te zasoby i rejestracja aplikacji nie będą już potrzebne, usuń je, aby nie były naliczane opłaty.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

  • Usuń zasoby platformy Azure utworzone podczas wykonywania kroków samouczka.

Usuwanie grupy zasobów

W witrynie Azure Portal wybierz pozycję Grupy zasobów z menu portalu i wybierz grupę zasobów zawierającą plan usługi App Service i usługi App Service.

Wybierz pozycję Usuń grupę zasobów, aby usunąć grupę zasobów i wszystkie zasoby.

Zrzut ekranu przedstawiający usuwanie grupy zasobów.

Uruchomienie tego polecenia może potrwać kilka minut.

Usuwanie rejestracji aplikacji

W centrum administracyjnym firmy Microsoft Entra wybierz pozycję Aplikacje> Rejestracje aplikacji. Następnie wybierz utworzoną aplikację. Zrzut ekranu przedstawiający wybieranie rejestracji aplikacji.

W przeglądzie rejestracji aplikacji wybierz pozycję Usuń. Zrzut ekranu przedstawiający usuwanie rejestracji aplikacji.

Usuwanie dzierżawy zewnętrznej

Jeśli utworzono nową dzierżawę zewnętrzną, możesz usunąć. W centrum administracyjnym firmy Microsoft Entra przejdź do pozycji Przegląd>tożsamości>Zarządzanie dzierżawami.

Wybierz dzierżawę, którą chcesz usunąć, a następnie wybierz pozycję Usuń.

Może być konieczne wykonanie wymaganych akcji przed usunięciem dzierżawy. Na przykład może być konieczne usunięcie wszystkich przepływów użytkownika i rejestracji aplikacji w dzierżawie.

Jeśli wszystko będzie gotowe do usunięcia dzierżawy, wybierz pozycję Usuń.

Następne kroki

W tym samouczku zawarto informacje na temat wykonywania następujących czynności:

  • Przyznawanie delegowanych uprawnień do aplikacji internetowej.
  • Wywołaj program Microsoft Graph z aplikacji internetowej dla zalogowanego użytkownika.