Udostępnij za pomocą

Wywoływanie internetowego interfejsu API platformy ASP.NET Core z bezsennością

W tym artykule przedstawiono, jak wywołać chroniony internetowy interfejs API ASP.NET Core przy użyciu Insomnia. Bezsenność to aplikacja, która umożliwia wysyłanie żądań HTTP do internetowego interfejsu API w celu przetestowania zasad autoryzacji i kontroli dostępu (uwierzytelniania). W tym artykule zarejestrujesz aplikację internetową i internetowy interfejs API w dzierżawie. Aplikacja internetowa służy do uzyskiwania tokenu dostępu wygenerowanego przez Platforma tożsamości Microsoft. Następnie użyj tokenu, aby wykonać autoryzowane wywołanie internetowego interfejsu API przy użyciu bezsenności.

W tym artykule przedstawiono, jak wywołać chroniony internetowy interfejs API ASP.NET Core przy użyciu Insomnia. Bezsenność to aplikacja, która umożliwia wysyłanie żądań HTTP do internetowego interfejsu API w celu przetestowania zasad autoryzacji i kontroli dostępu (uwierzytelniania). Kontynuując z Samouczek: zaimplementuj chroniony punkt końcowy do interfejsu API, który stworzyłeś, musisz zarejestrować aplikację internetową w platformie tożsamości firmy Microsoft, aby wygenerować token dostępu. Następnie użyj tokenu, aby wykonać autoryzowane wywołanie interfejsu API przy użyciu bezsenności.

Wymagania wstępne

  • Konto platformy Azure z aktywną subskrypcją. Utwórz bezpłatne konto.
  • To konto platformy Azure musi mieć uprawnienia do zarządzania aplikacjami. Każda z następujących ról firmy Microsoft Entra obejmuje wymagane uprawnienia:
    • Administrator aplikacji
    • Deweloper aplikacji
    • Administrator aplikacji w chmurze
  • Pobierz i zainstaluj Insomnia. Użyj opcji Bezsenność, aby uzyskać token dostępu dla żądań interfejsu API.
  • Minimalne wymaganie zestawu .NET 8.0 SDK.

Rejestrowanie aplikacji

Platforma tożsamości Microsoft wymaga zarejestrowania aplikacji przed udostępnieniem usług zarządzania tożsamościami i dostępem. Rejestracja aplikacji umożliwia określenie nazwy i typu aplikacji oraz odbiorców logowania. Odbiorcy logowania określają, jakie typy kont użytkowników mogą logować się do danej aplikacji.

Rejestrowanie internetowego interfejsu API

Wykonaj następujące kroki, aby utworzyć rejestrację internetowego interfejsu API:

  1. Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako 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 obszaruRejestracje aplikacji>.

  4. Wybierz pozycję Nowa rejestracja.

  5. Wprowadź nazwę aplikacji, na przykład NewWebAPI1.

  6. Dla Obsługiwane typy kont wybierz Konta tylko w tym katalogu organizacyjnym. Aby uzyskać informacje na temat różnych typów 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 możesz wyświetlić okienko Przegląd aplikacji. Zapisz identyfikator katalogu (dzierżawy) oraz identyfikator aplikacji (klienta), które będą używane w kolejnych krokach.

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

Uwaga

Obsługiwane typy kont można zmienić, odwołując się do modyfikowania 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 jest prawidłowy.

  1. W obszarze Zarządzanie wybierz pozycję Uwidaczniaj interfejs API > Dodaj zakres. Zaakceptuj proponowany URI identyfikatora aplikacji(api://{clientId}) poprzez wybranie Zapisz i kontynuuj. Ta wartość {clientId} jest zarejestrowana na stronie Przegląd. Następnie wprowadź następujące informacje:

    1. W polu Nazwa zakresu wprowadź wartość Forecast.Read.
    2. W obszarze Kto może wyrazić zgodę, upewnij się, że wybrano opcję Administratorzy i użytkownicy .
    3. W polu Nazwa wyświetlana zgody administratora wprowadź tutaj Read forecast data.
    4. W polu Opis zgody administratora wprowadź Allows the application to read weather forecast data
    5. W polu Nazwa wyświetlana zgody użytkownika wprowadź Read forecast data.
    6. W polu Opis zgody użytkownika wprowadź wartość Allows the application to read weather forecast data.
    7. Upewnij się, że stan jest ustawiony na Włączone.

  2. Wybierz Dodaj zakres. Jeśli zakres został wprowadzony poprawnie, zostanie wyświetlony w okienku Uwidacznij interfejs API .

    Zrzut ekranu przedstawiający wartości pól podczas dodawania zakresu do interfejsu API.

Rejestrowanie aplikacji internetowej

Nie wystarczy mieć internetowy interfejs API. Aby uzyskać token dostępu do internetowego interfejsu API, potrzebna jest również aplikacja internetowa.

Wykonaj następujące kroki, aby utworzyć rejestrację aplikacji internetowej:

  1. Wybierz pozycję Strona główna , aby wrócić do strony głównej. Przejdź do obszaruRejestracje aplikacji>.
  2. Wybierz pozycję Nowa rejestracja.
  3. Wprowadź nazwę aplikacji, taką jak web-app-calls-web-api.
  4. Dla Obsługiwane typy kont wybierz Konta tylko w tym katalogu organizacyjnym. Aby uzyskać informacje o różnych typach kont, wybierz opcję Pomóż mi wybrać.
  5. W obszarze Identyfikator URI przekierowania (opcjonalnie) wybierz Web, a następnie wprowadź http://localhost w polu Adres URL.
  6. Wybierz pozycję Zarejestruj.
  1. Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako 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 obszaruRejestracje aplikacji>.
  4. Wybierz pozycję Nowa rejestracja.
  5. Wprowadź nazwę aplikacji, taką jak web-app-calls-web-api.
  6. Dla Obsługiwane typy kont wybierz Konta tylko w tym katalogu organizacyjnym. Aby uzyskać informacje o różnych typach kont, wybierz opcję Pomóż mi wybrać.
  7. W obszarze Identyfikator URI przekierowania (opcjonalnie) wybierz Web, a następnie wprowadź http://localhost w polu Adres URL.
  8. Wybierz pozycję Zarejestruj.

Po zakończeniu rejestracji możesz wyświetlić okienko Przegląd aplikacji. Zapisz identyfikator katalogu (dzierżawy) oraz identyfikator aplikacji (klienta), które będą używane w kolejnych krokach.

Dodaj klucz tajny klienta

Tajny kod klienta to ciąg znaków, którego aplikacja może używać do identyfikacji i czasami jest nazywany hasłem aplikacji. Aplikacja internetowa używa klucza tajnego klienta, aby udowodnić swoją tożsamość podczas żądania tokenów.

Wykonaj następujące kroki, aby skonfigurować klucz tajny klienta:

  1. W okienku Przegląd w obszarze Zarządzanie wybierz pozycję Certyfikaty i tajemnice>Tajemnice klienta>Nowy klucz tajny klienta.

  2. Dodaj opis dla tajnego klucza klienta, na przykład Mój tajny klucz klienta.

  3. Wybierz datę wygaśnięcia klucza tajnego lub określ niestandardowy okres ważności.

    • Okres istnienia wpisu tajnego klienta jest ograniczony do dwóch lat (24 miesięcy) lub mniej. Nie można określić niestandardowego okresu istnienia dłuższego niż 24 miesiące.
    • Firma Microsoft zaleca ustawienie wartości wygaśnięcia mniejszej niż 12 miesięcy.

  4. Wybierz pozycję Dodaj.

  5. Pamiętaj, aby zarejestrować wartość tajnego klienta. Ta tajna wartość nigdy nie jest wyświetlana ponownie po opuszczeniu tej strony.

Aby uzyskać więcej informacji na temat bezpiecznego przechowywania wpisu tajnego klienta, zobacz Najlepsze rozwiązania dotyczące zarządzania wpisami tajnymi w usłudze Key Vault.

Dodawanie uprawnień dostępu do internetowego interfejsu API

Określając zakresy internetowego interfejsu API, aplikacja internetowa może uzyskać token dostępu zawierający zakresy dostarczone przez Platforma tożsamości Microsoft. W kodzie internetowy interfejs API może następnie zapewnić dostęp oparty na uprawnieniach do swoich zasobów na podstawie zakresów znalezionych w tokenie dostępu.

Wykonaj następujące kroki, aby skonfigurować uprawnienia klienta do internetowego interfejsu API:

  1. W okienku Przegląd aplikacji w obszarze Zarządzanie wybierz pozycję Uprawnienia interfejsu API>Dodaj uprawnienie>API używane przez moją organizację.
  2. Wybierz NewWebAPI1 lub interfejs API, do którego chcesz dodać uprawnienia.
  3. W obszarze Wybierz uprawnienia zaznacz pole wyboru obok pozycji Forecast.Read. Może być konieczne rozwinięcie listy Uprawnienia . Spowoduje to wybranie uprawnień, które aplikacja kliencka powinna mieć w imieniu zalogowanego użytkownika.
  4. Wybierz pozycję Dodaj uprawnienia , aby ukończyć proces.

Po dodaniu tych uprawnień do interfejsu API powinny zostać wyświetlone wybrane uprawnienia w obszarze Skonfigurowane uprawnienia.

Możesz również zauważyć uprawnienie User.Read dla interfejsu API programu Microsoft Graph. To uprawnienie jest dodawane automatycznie podczas rejestrowania aplikacji.

Testowanie internetowego interfejsu API

Aby upewnić się, że interfejs API działa i jest gotowy do obsługi żądań, wykonaj następujące kroki:

  1. Sklonuj repozytorium ms-identity-docs-code-dotnet .

    git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git

  2. Przejdź do ms-identity-docs-code-dotnet/web-api i otwórz plik appsettings.json, zastąp wartości {APPLICATION_CLIENT_ID} i {DIRECTORY_TENANT_ID} następującymi wartościami:

    • {APPLICATION_CLIENT_ID} to identyfikator aplikacji internetowego interfejsu API (klienta) w okienku Przegląd aplikacji.
    • {DIRECTORY_TENANT_ID} to identyfikator katalogu internetowego interfejsu API (dzierżawy) w okienku Przegląd aplikacji.

  3. Uruchom następujące polecenie, aby uruchomić aplikację:

    dotnet run

  4. Zostaną wyświetlone dane wyjściowe podobne do poniższych. Zarejestruj numer portu w adresie https://localhost:{port} URL.

    ...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

Testowanie internetowego interfejsu API

Aby upewnić się, że interfejs API działa i jest gotowy do obsługi żądań, wykonaj następujące kroki:

  1. Przejdź do internetowego interfejsu API utworzonego w artykule Samouczek: tworzenie projektu ASP.NET Core i konfigurowanie interfejsu API, na przykład NewWebAPILocal, i otwórz folder.

  2. Otwórz nowe okno terminalu i przejdź do folderu, w którym znajduje się projekt internetowego interfejsu API.

    1. Uruchom następujące polecenie, aby uruchomić aplikację:

      dotnet run

  3. Zostaną wyświetlone dane wyjściowe podobne do poniższych. Zarejestruj numer portu w adresie https://localhost:{port} URL.

    ...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

Konfigurowanie autoryzowanego żądania do internetowego interfejsu API w obszarze Bezsenność

Aby uzyskać token dostępu dla żądań interfejsu API, wykonaj następujące kroki:

  1. Uruchom aplikację Bezsenność .

  2. Wybierz pozycję Nowe żądanie HTTP lub możesz użyć Ctrl + N , aby utworzyć nowe żądanie HTTP.

  3. W oknie modalnym New Request wybierz metodę GET z listy rozwijanej.

  4. Jako adres URL żądania wprowadź adres URL punktu końcowego uwidocznionego przez internetowy interfejs API. https://localhost:{port}/weatherforecast

  5. Z menu rozwijanego Uwierzytelnianie wybierz pozycję OAuth 2.0. Spowoduje to wyświetlenie formularza OAuth 2.0 .

  6. Wprowadź następujące wartości w formularzu OAuth 2.0 :

    Ustawienie Wartość
    TYP UDZIELENIA Wybieranie kodu autoryzacji
    ADRES URL AUTORYZACJI https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
    Zastąp {tenantId} element identyfikatorem katalogu (dzierżawy)
    ADRES URL TOKENU DOSTĘPU https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
    Zastąp {tenantId} element identyfikatorem katalogu (dzierżawy)
    IDENTYFIKATOR KLIENTA Wartość identyfikatora aplikacji (klienta) rejestracji aplikacji internetowej
    KLUCZ TAJNY KLIENTA Wartość tajnego klucza klienta rejestracji aplikacji internetowej
    PRZEKIEROWANIE URL Wprowadź http://localhostwartość , która ustawia adres URL przekierowania na identyfikator URI przekierowania zarejestrowany za pomocą identyfikatora Entra firmy Microsoft.
    Opcje zaawansowane>Zakres api://{application_client_id}/Forecast.Read
    Przejdź do rejestracji aplikacji internetowej w obszarze Zarządzanie, wybierz pozycję Uprawnienia interfejsu API, a następnie wybierz pozycję Forecast.Read
    Skopiuj wartość w polu tekstowym zawierającym wartość Zakres

Uzyskiwanie tokenu dostępu i wysyłanie żądania do internetowego interfejsu API

  1. Po wprowadzeniu tych wartości wybierz pozycję Pobierz tokeny na końcu formularza. Spowoduje to uruchomienie okna przeglądarki Bezsenność, w którym uwierzytelniasz się przy użyciu poświadczeń użytkownika. Pamiętaj, aby zezwolić na wyskakujące okienka z aplikacji Bezsenność w przeglądarce.
  2. Po uwierzytelnieniu wybierz pozycję Wyślij , aby wysłać żądanie do chronionego internetowego punktu końcowego interfejsu API.

W przypadku prawidłowego tokenu dostępu zawartego w żądaniu oczekiwana odpowiedź to 200 OK z danymi wyjściowymi podobnymi do następujących:

[
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": -16,
    "summary": "Scorching",
    "temperatureF": 4
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 1,
    "summary": "Sweltering",
    "temperatureF": 33
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 26,
    "summary": "Freezing",
    "temperatureF": 78
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 54,
    "summary": "Mild",
    "temperatureF": 129
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 11,
    "summary": "Bracing",
    "temperatureF": 51
  }
]

Powiązana zawartość

Aby uzyskać więcej informacji na temat przepływu kodu autoryzacji OAuth 2.0 i typów aplikacji, zobacz:

  • Last updated on