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
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.
Zaloguj się do centrum administracyjnego Microsoft Entra jako co najmniej administrator aplikacji w chmurze.
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.
Przejdź do Identity>Applications>App registrations i wybierz pozycję Nowa rejestracja.
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.W przypadku obsługiwanych typów kont wybierz Konta w dowolnym katalogu organizacyjnym.
Wybierz pozycję Zarejestruj, aby utworzyć aplikację.
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).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:- Dla nazwy zakresu, wprowadź
access_as_user
. - W przypadku Kto może wyrazić zgodę, upewnij się, że wybrano opcję administratorzy i użytkownicy.
- W polu nazwa wyświetlana zgody administratora wprowadź
Access TodoListService as a user
. - W opis zgody administratora wprowadź
Accesses the TodoListService web API as a user
. - W polu Nazwa wyświetlana zgody użytkownika wprowadź
Access TodoListService as a user
. - W polu opis zgody użytkownika wprowadź
Accesses the TodoListService web API as a user
. - W przypadku stanu , pozostaw włączone .
- Dla nazwy zakresu, wprowadź
Wybierz pozycję Dodaj zakres.
Konfigurowanie projektu usługi
Skonfiguruj projekt usługi tak, aby był zgodny z zarejestrowanym internetowym interfejsem API.
Otwórz rozwiązanie w programie Visual Studio, a następnie otwórz plik appsettings.json w katalogu głównym projektu TodoListService.
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ściachClientID
iAudience
.
Dodawanie nowego zakresu do pliku app.config
Aby dodać nowy zakres do pliku app.config TodoListClient, wykonaj następujące kroki:
W folderze głównym projektu TodoListClient otwórz plik app.config.
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:
Zaloguj się do centrum administracyjnego Microsoft Entra jako co najmniej Administrator aplikacji w chmurze.
Przejdź do Identity>Applications>App registrations i wybierz New registration.
Wybierz Nową rejestrację.
Po otwarciu strony Rejestrowanie aplikacji wprowadź informacje o rejestracji aplikacji:
- W sekcji Nazwa wprowadź znaczącą nazwę aplikacji, która będzie wyświetlana użytkownikom aplikacji (na przykład NativeClient-DotNet-TodoListClient).
- Dla typów kont obsługiwanych wybierz Konta w dowolnym katalogu organizacyjnym.
- Wybierz pozycję Zarejestruj, aby utworzyć aplikację.
Notatka
W pliku app.config projektu TodoListClient wartość domyślna
ida:Tenant
jest ustawiona nacommon
. 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.
Na stronie Przegląd aplikacji wybierz pozycję Uwierzytelnianie, a następnie wykonaj następujące kroki, aby dodać platformę:
- W obszarze Konfiguracje platformywybierz przycisk Dodaj platformę.
- W przypadku aplikacji mobilnych i klasycznychwybierz pozycję Aplikacje mobilne i klasyczne.
- Dla URI przekierowaniazaznacz pole wyboru
https://login.microsoftonline.com/common/oauth2/nativeclient
. - Wybierz opcję Konfiguruj.
Wybierz uprawnienia interfejsu API, a następnie wykonaj poniższe kroki, aby dodać uprawnienia.
- Wybierz przycisk Dodaj uprawnienie.
- Wybierz kartę Moje API.
- Na liście interfejsów API wybierz pozycję AppModelv2-NativeClient-DotNet-TodoListService API lub nazwę wprowadzoną dla internetowego interfejsu API.
- Zaznacz pole wyboru uprawnień access_as_user, jeśli nie jest jeszcze zaznaczone. W razie potrzeby użyj pola Wyszukiwania.
- Wybierz przycisk Dodaj uprawnienia.
Konfigurowanie projektu
Skonfiguruj projekt TodoListClient, dodając identyfikator aplikacji do pliku app.config.
W portalu App registrations na stronie Przegląd skopiuj wartość identyfikatora aplikacji (klienta).
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;
Kliknij prawym przyciskiem myszy rozwiązanie programu Visual Studio i wybierz pozycję właściwości
W Common Properties wybierz pozycję Startup Project, a następnie Multiple startup projects.
W przypadku obu projektów wybierz Uruchom jako akcję
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.
Naciśnij F5, aby uruchomić projekty. Zostanie otwarta strona usługi, a także aplikacja desktopowa.
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.
- W portalu Rejestracje aplikacji otwórz właściwości aplikacji TodoListService.
- W sekcji Uwidaczniaj interfejs API w obszarze Autoryzowane aplikacje klienckiewybierz pozycję Dodaj aplikację kliencką.
- W polu identyfikatora klienta , wklej identyfikator aplikacji TodoListClient.
- W sekcji Autoryzowane zakresy wybierz zakres dla interfejsu API
api://<Application ID>/access_as_user
. - Wybierz pozycję Dodaj aplikację.
Uruchamianie projektu
- Naciśnij F5, aby uruchomić projekt. Twoja aplikacja TodoListClient otwiera się.
- 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: