Udostępnij za pośrednictwem

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

  • Artykuł

Dotyczy: Zielony okrąg z białym symbolem haczyka. Najemcy usługi Workforce Biały okrąg z szarym symbolem X. Najemcy zewnętrzni (dowiedzieć się więcej)

W tym krótkim przewodniku użyjesz przykładowej aplikacji internetowej, aby pokazać, jak chronić internetowy interfejs API ASP.NET przy użyciu platformy tożsamości Microsoftu. W przykładzie użyto biblioteki Microsoft Authentication Library (MSAL) do obsługi uwierzytelniania.

Warunki wstępne

Rejestracja aplikacji webowego API

Aby ukończyć rejestrację, podaj nazwę aplikacji i określ obsługiwane typy kont. Po zarejestrowaniu, strona przeglądowa aplikacji wyświetla identyfikatory potrzebne w kodzie źródłowym aplikacji.

  1. Zaloguj się do centrum administracyjnego Microsoft Entra jako co najmniej Deweloper Aplikacji.

  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.

  4. Wybierz pozycję Nowa rejestracja.

  5. Wprowadź Nazwa dla aplikacji, na przykład NewWebAPI1.

  6. W przypadku obsługiwanych typów kont wybierz opcję "Konta tylko w tym katalogu organizacyjnym" . Aby uzyskać informacje o różnych typach kont, wybierz pozycję Pomóż mi wybrać opcję.

  7. Wybierz pozycję Zarejestruj.

    Zrzut ekranu przedstawiający sposób wprowadzania nazwy i wybierania typu konta.

  8. Po zakończeniu rejestracji zostanie wyświetlone okienko Przegląd aplikacji. Zanotuj identyfikator katalogu (dzierżawy) oraz identyfikator aplikacji (klienta) do użycia w kodzie źródłowym aplikacji.

    Zrzut ekranu przedstawiający wartości identyfikatorów na stronie przeglądu.

Notatka

Typy kont obsługiwanych można zmienić, powołując się na Modyfikowanie kont obsługiwanych przez aplikację.

Uwidacznianie interfejsu API

Po zarejestrowaniu interfejsu API można skonfigurować jego uprawnienia, definiując zakresy, które interfejs API uwidacznia aplikacjom klienckim. Aplikacje klienckie żądają uprawnień do wykonywania operacji, przekazując token dostępu wraz z żądaniami do chronionego internetowego interfejsu API. Internetowy interfejs API wykonuje żądaną operację tylko wtedy, gdy otrzymany token dostępu zawiera wymagane zakresy.

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

    1. Dla nazwa 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. Dla stanu , pozostaw włączone.

  2. Wybierz pozycję Dodaj zakres.

Klonowanie lub pobieranie przykładowej aplikacji

Aby uzyskać przykładową aplikację, możesz ją sklonować z usługi GitHub lub pobrać jako plik .zip.

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.

Konfigurowanie przykładowej aplikacji

Skonfiguruj przykładowy kod, 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 zarejestrowanej w portalu App registrations, zarówno we właściwościach ClientID, jak 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 rejestracje aplikacji w Azure Portal, a następnie w projekcie TodoListClient skonfiguruj kod. 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 mając uprawnienia co najmniej Administratora aplikacji w chmurze.

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

  3. Wybierz pozycję Nowa rejestracja.

  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 obsługiwanych typów kont 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ądu aplikacji wybierz Authentication, a następnie wykonaj te kroki, aby dodać platformę:

    1. W obszarze Konfiguracje platformywybierz przycisk Dodaj platformę.
    2. W przypadku aplikacji mobilnych i komputerowychwybierz pozycję aplikacje mobilne i komputerowe.
    3. Dla identyfikatorów URI przekierowaniawybierz pole wyboru https://login.microsoftonline.com/common/oauth2/nativeclient.
    4. Wybierz 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 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 uprawnienia 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ść Identyfikator aplikacji w parametrze ida:ClientId.

Uruchamianie przykładowej aplikacji

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

  1. Kliknij prawym przyciskiem myszy na rozwiązaniu Visual Studio i wybierz Właściwości

  2. W Common Properties wybierz pozycję Startup Project, a następnie wiele projektów startowych.

  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 komputerowa.

  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ć uzyskanie dostępu do internetowego interfejsu API usługi TodoListService i manipulowanie listą zadań do wykonania, podczas logowania również żądany jest token dostępu do zakresu access_as_user.

Wstępna 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 Uwidaczniaj interfejs API w obszarze Autoryzowane aplikacje klienckiewybierz pozycję Dodaj aplikację kliencką.
  3. W polu identyfikator klienta wklej ID aplikacji TodoListClient.
  4. W sekcji Autoryzowane zakresy wybierz zakres dla internetowego interfejsu api://<Application ID>/access_as_user API.
  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 identyfikatorem Microsoft Entra mogą żądać tokenów i uzyskiwać dostęp do internetowego interfejsu API.

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

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