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

W poniższym przewodniku „Szybki start” użyto przykładowego kodu, który pokazuje, jak chronić interfejs API ASP.NET, ograniczając dostęp do zasobów wyłącznie do autoryzowanych kont. Przykładowa aplikacja obsługuje autoryzację osobistych kont Microsoft oraz kont w dowolnej organizacji 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.

Warunki wstępne

• Konto platformy Azure z aktywną subskrypcją. Utwórz bezpłatne konto.
• Visual Studio 2022. Pobierz Visual Studioza darmo.

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.

Rejestracja interfejsu API sieci Web (TodoListService)

Zarejestruj interfejs API sieci Web w Rejestracje aplikacji w Azure Portal.

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

2. Jeśli masz dostęp do wielu dzierżaw, użyj ikony ustawienia 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 Identity>Applications>App registrations i wybierz pozycję Nowa rejestracja.

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

5. W przypadku obsługiwanych typów kont wybierz Konta w dowolnym katalogu organizacyjnym.

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

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

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

   1. Dla nazwy zakresu, wprowadź access_as_user.
   2. W przypadku Kto może wyrazić zgodę, upewnij się, że wybrano opcję administratorzy i użytkownicy.
   3. W polu nazwa wyświetlana zgody administratora wprowadź Access TodoListService as a user.
   4. W opis zgody administratora 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ź Accesses the TodoListService web API as a user.
   7. W przypadku stanu , pozostaw włączone .

9. Wybierz pozycję 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 (identyfikatora aplikacji) z aplikacji, którą zarejestrowałeś w portalu App registrations, w obu właściwościach ClientID i Audience.

Dodawanie nowego zakresu do pliku app.config

Aby dodać nowy zakres do pliku app.config TodoListClient, 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 ciąg {Enter the Application ID of your TodoListService from the app registration portal}.

Notatka

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

Rejestrowanie aplikacji internetowej (TodoListClient)

Zarejestruj aplikację TodoListClient w sekcji Rejestracje aplikacji w 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 Microsoft Entra jako co najmniej Administrator aplikacji w chmurze.

2. Przejdź do Identity>Applications>App registrations i wybierz New registration.

3. Wybierz Nową rejestrację.

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

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

   Notatka

   W pliku app.config projektu TodoListClient wartość domyślna ida:Tenant jest ustawiona na 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 opcję Konta w dowolnym katalogu organizacyjnym).
   • organizations: Możesz zalogować się przy użyciu konta służbowego lub szkolnego.
   • 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 platformywybierz przycisk Dodaj platformę.
   2. W przypadku aplikacji mobilnych i klasycznychwybierz pozycję Aplikacje mobilne i klasyczne.
   3. Dla URI przekierowaniazaznacz pole wyboru https://login.microsoftonline.com/common/oauth2/nativeclient.
   4. Wybierz opcję Konfiguruj.

6. Wybierz uprawnienia interfejsu API, a następnie wykonaj poniższe kroki, aby dodać uprawnienia.

   1. Wybierz przycisk Dodaj uprawnienie.
   2. Wybierz kartę Moje 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 uprawnień access_as_user, 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 App registrations 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ść identyfikatora 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 pozycję właściwości

2. W Common Properties wybierz pozycję Startup Project, a następnie Multiple startup projects.

3. W przypadku obu projektów wybierz Uruchom 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 F5, aby uruchomić projekty. Zostanie otwarta strona usługi, a także aplikacja desktopowa.

2. W aplikacji TodoListClient w prawym górnym rogu wybierz pozycję Zaloguj się, a następnie zaloguj się przy użyciu tych samych poświadczeń, które użyto 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ć uzyskiwanie dostępu do internetowego interfejsu API usługi TodoListService i manipulowanie listą zadań do wykonania, logowanie również żąda tokenu dostępu do obszaru zakresu access_as_user.

Dokonaj wstępnej autoryzacji aplikacji klienckiej

Możesz zezwolić użytkownikom z innych katalogów na dostęp do web API przez wstępne autoryzowanie aplikacji klienckiej do dostępu do web 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 Uwidaczniaj interfejs API w obszarze Autoryzowane aplikacje klienckiewybierz pozycję Dodaj aplikację kliencką.
3. W polu identyfikatora klienta , wklej identyfikator aplikacji TodoListClient.
4. W sekcji Autoryzowane zakresy wybierz zakres dla interfejsu API api://<Application ID>/access_as_user.
5. Wybierz pozycję Dodaj aplikację.

Uruchamianie projektu

1. Naciśnij F5, aby uruchomić projekt. Twoja aplikacja TodoListClient otwiera się.
2. W prawym górnym rogu wybierz pozycję Zaloguj się, 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 live.com, oraz konta służbowe lub szkolne z organizacji zintegrowanych z Microsoft Entra ID mogą żądać tokenów i uzyskiwać dostęp do Twojego internetowego interfejsu API.

Aby określić, kto może zalogować się do aplikacji, zmieniając właściwość TenantId 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 interfejsu API sieciowego