Szybki start: wywoływanie internetowego interfejsu API ASP.NET chronionego przez Platforma tożsamości Microsoft

W poniższym przewodniku Szybki start użyto przykładowego kodu, który pokazuje, jak chronić ASP.NET internetowy interfejs API, ograniczając dostęp do zasobów tylko do autoryzowanych kont. Przykład obsługuje autoryzację osobistych kont Microsoft i kont w dowolnej organizacji firmy Microsoft Entra.

W tym artykule użyto również aplikacji Windows Presentation Foundation (WPF), aby zademonstrować sposób żądania tokenu dostępu w celu uzyskania dostępu do internetowego interfejsu API.

Wymagania wstępne

• Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
• Visual Studio 2022. Pobierz program Visual Studio bezpłatnie.

Klonowanie lub pobieranie przykładu

Przykładowy kod można uzyskać na dwa sposoby:

• Sklonuj go z powłoki lub wiersza polecenia:

  git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git
  

• Pobierz go jako plik ZIP.

Napiwek

Aby uniknąć błędów spowodowanych ograniczeniami długości ścieżki w systemie Windows, zalecamy wyodrębnienie archiwum lub sklonowanie repozytorium do katalogu w pobliżu katalogu głównego dysku.

Rejestrowanie internetowego interfejsu API (TodoListService)

Napiwek

Kroki opisane w tym artykule mogą się nieznacznie różnić w zależności od portalu, od którego zaczynasz.

Zarejestruj internetowy interfejs API w Rejestracje aplikacji w witrynie Azure Portal.

1. Zaloguj się do centrum administracyjnego firmy Microsoft Entra jako co najmniej Administracja istrator aplikacji w chmurze.

2. Jeśli masz dostęp do wielu dzierżaw, użyj ikonyUstawienia w górnym menu, aby przełączyć się do dzierżawy, w której chcesz zarejestrować aplikację z menu Katalogi i subskrypcje.

3. Przejdź do pozycji Identity>Applications> Rejestracje aplikacji i wybierz pozycję Nowa rejestracja.

4. Wprowadź nazwę aplikacji, na przykład AppModelv2-NativeClient-DotNet-TodoListService. Użytkownicy aplikacji mogą zobaczyć tę nazwę i możesz ją zmienić później.

5. W obszarze Obsługiwane typy kont wybierz pozycję Konta w dowolnym katalogu organizacyjnym.

6. Wybierz pozycję Zarejestruj, aby utworzyć aplikację.

7. Na stronie Przegląd aplikacji wyszukaj wartość Identyfikator aplikacji (klienta), a następnie zapisz ją do późniejszego użycia. Będzie on potrzebny do skonfigurowania pliku konfiguracji programu Visual Studio dla tego projektu (czyli ClientId w pliku TodoListService\appsettings.json ).

8. W obszarze Zarządzanie wybierz pozycję Uwidaczniaj interfejs API>Dodaj zakres. Zaakceptuj proponowany identyfikator URI identyfikatora aplikacji (api://{clientId}), wybierając pozycję Zapisz i kontynuuj, a następnie wprowadź następujące informacje:

   1. W polu Nazwa zakresu wprowadź wartość access_as_user.
   2. W przypadku KtoTo może wyrazić zgodę, upewnij się, że wybrano opcję Administracja i użytkowników.
   3. W polu nazwa wyświetlana zgody Administracja wprowadź .Access TodoListService as a user
   4. W polu opis Administracja zgody wprowadź .Accesses the TodoListService web API as a user
   5. W polu Nazwa wyświetlana zgody użytkownika wprowadź .Access TodoListService as a user
   6. W polu Opis zgody użytkownika wprowadź wartość Accesses the TodoListService web API as a user.
   7. W obszarze Stan zachowaj wartość Włączone.

9. Wybierz Dodaj zakres.

Konfigurowanie projektu usługi

Skonfiguruj projekt usługi tak, aby był zgodny z zarejestrowanym internetowym interfejsem API.

1. Otwórz rozwiązanie w programie Visual Studio, a następnie otwórz plik appsettings.json w katalogu głównym projektu TodoListService.

2. Zastąp wartość Enter_the_Application_Id_here wartości identyfikatora klienta (identyfikator aplikacji) z aplikacji zarejestrowanej w portalu Rejestracje aplikacji zarówno we właściwościachAudience, jak ClientID i .

Dodawanie nowego zakresu do pliku app.config

Aby dodać nowy zakres do pliku TodoListClient app.config , wykonaj następujące kroki:

1. W folderze głównym projektu TodoListClient otwórz plik app.config .

2. Wklej identyfikator aplikacji z aplikacji zarejestrowanej dla projektu TodoListService w parametrze TodoListServiceScope , zastępując {Enter the Application ID of your TodoListService from the app registration portal} ciąg.

Uwaga

Upewnij się, że identyfikator aplikacji używa następującego formatu: api://{TodoListService-Application-ID}/access_as_user (gdzie {TodoListService-Application-ID} to identyfikator GUID reprezentujący identyfikator aplikacji dla aplikacji TodoListService).

Rejestrowanie aplikacji internetowej (TodoListClient)

Zarejestruj aplikację TodoListClient w Rejestracje aplikacji w witrynie Azure Portal, a następnie skonfiguruj kod w projekcie TodoListClient. Jeśli klient i serwer są traktowane jako ta sama aplikacja, możesz ponownie użyć aplikacji zarejestrowanej w kroku 2. Użyj tej samej aplikacji, jeśli chcesz, aby użytkownicy logować się przy użyciu osobistego konta Microsoft.

Rejestrowanie aplikacji

Aby zarejestrować aplikację TodoListClient, wykonaj następujące kroki:

1. Zaloguj się do centrum administracyjnego firmy Microsoft Entra jako co najmniej Administracja istrator aplikacji w chmurze.

2. Przejdź do pozycji Identity>Applications> Rejestracje aplikacji i wybierz pozycję Nowa rejestracja.

3. Wybierz opcjęNowa rejestracja.

4. Po otwarciu strony Rejestrowanie aplikacji wprowadź informacje o rejestracji aplikacji:

   1. W sekcji Nazwa wprowadź zrozumiałą nazwę aplikacji, która będzie wyświetlana użytkownikom aplikacji (na przykład NativeClient-DotNet-TodoListClient).
   2. W obszarze Obsługiwane typy kont wybierz pozycję Konta w dowolnym katalogu organizacyjnym.
   3. Wybierz pozycję Zarejestruj, aby utworzyć aplikację.

   Uwaga

   W pliku projektu TodoListClient app.config wartość domyślna parametru ida:Tenant ma wartość common. Możliwe wartości to:

   • common: Możesz zalogować się przy użyciu konta służbowego lub osobistego konta Microsoft (ponieważ w poprzednim kroku wybrano pozycję Konta w dowolnym katalogu organizacyjnym).
   • organizations: Możesz zalogować się przy użyciu konta służbowego.
   • consumers: Możesz zalogować się tylko przy użyciu konta osobistego Microsoft.

5. Na stronie Przegląd aplikacji wybierz pozycję Uwierzytelnianie, a następnie wykonaj następujące kroki, aby dodać platformę:

   1. W obszarze Konfiguracje platformy wybierz przycisk Dodaj platformę .
   2. W obszarze Aplikacje mobilne i klasyczne wybierz pozycję Aplikacje mobilne i klasyczne.
   3. W polu Identyfikatory URI przekierowania zaznacz https://login.microsoftonline.com/common/oauth2/nativeclient pole wyboru.
   4. Wybierz Konfiguruj.

6. Wybierz pozycję Uprawnienia interfejsu API, a następnie wykonaj następujące kroki, aby dodać uprawnienia:

   1. Wybierz przycisk Dodaj uprawnienia.
   2. Wybierz kartę Moje interfejsy API.
   3. Na liście interfejsów API wybierz pozycję AppModelv2-NativeClient-DotNet-TodoListService API lub nazwę wprowadzoną dla internetowego interfejsu API.
   4. Zaznacz pole wyboru access_as_user uprawnienie, jeśli nie jest jeszcze zaznaczone. W razie potrzeby użyj pola Wyszukiwania.
   5. Wybierz przycisk Dodaj uprawnienia.

Konfigurowanie projektu

Skonfiguruj projekt TodoListClient, dodając identyfikator aplikacji do pliku app.config .

1. W portalu Rejestracje aplikacji na stronie Przegląd skopiuj wartość identyfikatora aplikacji (klienta).

2. W folderze głównym projektu TodoListClient otwórz plik app.config , a następnie wklej wartość Identyfikator aplikacji w parametrze ida:ClientId .

Uruchamianie projektów

Uruchom oba projekty. Dla użytkowników programu Visual Studio;

1. Kliknij prawym przyciskiem myszy rozwiązanie programu Visual Studio i wybierz polecenie Właściwości

2. W obszarze Wspólne właściwości wybierz pozycję Projekt startowy, a następnie pozycję Wiele projektów startowych.

3. W przypadku obu projektów wybierz pozycję Rozpocznij jako akcję

4. Upewnij się, że usługa TodoListService jest uruchamiana jako pierwsza, przenosząc ją na pierwszą pozycję na liście przy użyciu strzałki w górę.

Zaloguj się, aby uruchomić projekt TodoListClient.

1. Naciśnij klawisz F5, aby uruchomić projekty. Zostanie otwarta strona usługi, a także aplikacja klasyczna.

2. W aplikacji TodoListClient w prawym górnym rogu wybierz pozycję Zaloguj, a następnie zaloguj się przy użyciu tych samych poświadczeń, które były używane do zarejestrowania aplikacji lub zaloguj się jako użytkownik w tym samym katalogu.

   Jeśli logujesz się po raz pierwszy, może zostać wyświetlony monit o wyrażenie zgody na internetowy interfejs API todoListService.

   Aby ułatwić dostęp do internetowego interfejsu API usługi TodoListService i manipulować listą Zadań do wykonania , logowanie również żąda tokenu dostępu do zakresu access_as_user .

Wstępne autoryzacja aplikacji klienckiej

Możesz zezwolić użytkownikom z innych katalogów na dostęp do internetowego interfejsu API przez wstępne autoryzowanie aplikacji klienckiej w celu uzyskania dostępu do internetowego interfejsu API. W tym celu należy dodać identyfikator aplikacji z aplikacji klienckiej do listy wstępnie autoryzowanych aplikacji dla internetowego interfejsu API. Dodając wstępnie autoryzowanego klienta, zezwalasz użytkownikom na dostęp do internetowego interfejsu API bez konieczności udzielania zgody.

1. W portalu Rejestracje aplikacji otwórz właściwości aplikacji TodoListService.
2. W sekcji Uwidacznij interfejs API w obszarze Autoryzowane aplikacje klienckie wybierz pozycję Dodaj aplikację kliencką.
3. W polu Identyfikator klienta wklej identyfikator aplikacji TodoListClient.
4. W sekcji Autoryzowane zakresy wybierz zakres internetowego interfejsu api://<Application ID>/access_as_user API.
5. Wybierz Dodaj aplikację.

Uruchamianie projektu

1. Naciśnij klawisz F5 , aby uruchomić projekt. Zostanie otwarta aplikacja TodoListClient.
2. W prawym górnym rogu wybierz pozycję Zaloguj, a następnie zaloguj się przy użyciu osobistego konta Microsoft, takiego jak konto live.com lub hotmail.com albo konto służbowe.

Opcjonalnie: Ogranicz dostęp do logowania do niektórych użytkowników

Domyślnie wszystkie konta osobiste, takie jak outlook.com lub konta live.com , konta służbowe z organizacji zintegrowanych z identyfikatorem Entra firmy Microsoft mogą żądać tokenów i uzyskiwać dostęp do internetowego interfejsu API.

Aby określić, kto może zalogować się do aplikacji, zmieniając TenantId właściwość w pliku appsettings.json .

Pomoc i obsługa techniczna 

Jeśli potrzebujesz pomocy, chcesz zgłosić problem lub poznać opcje pomocy technicznej, zobacz Pomoc i obsługa techniczna dla deweloperów.

Następne kroki

Dowiedz się więcej, tworząc chroniony interfejs API sieci Web ASP.NET Core w następującej serii samouczków:

Samouczek dotyczący chronionego internetowego interfejsu API