Udostępnij za pośrednictwem

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

  • Artykuł

W tym artykule przedstawiono sposób wywoływania chronionego internetowego interfejsu API ASP.NET Core przy użyciu bezsenności. 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 sposób wywoływania chronionego internetowego interfejsu API ASP.NET Core przy użyciu bezsenności. 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 sekcji Samouczek: zaimplementuj chroniony punkt końcowy do interfejsu API, w którym utworzono chroniony interfejs API, musisz zarejestrować aplikację internetową przy użyciu Platforma tożsamości Microsoft w celu wygenerowania tokenu 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 konto bezpłatnie.
  • 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 bezsenność. 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

Napiwek

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

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 aplikacji tożsamości>> Rejestracje aplikacji.

  4. Wybierz opcjęNowa rejestracja.

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

  6. W obszarze Obsługiwane typy kont wybierz pozycję 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. Zarejestruj identyfikator katalogu (dzierżawy) i identyfikator aplikacji (klienta), które mają być 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 identyfikator URI (api://{clientId}) identyfikatora aplikacji, wybierając pozycję Zapisz i kontynuuj. Jest {clientId} to wartość 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ź .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 aplikacji tożsamości>> Rejestracje aplikacji.
  2. Wybierz opcjęNowa rejestracja.
  3. Wprowadź nazwę aplikacji, taką jak web-app-calls-web-api.
  4. W obszarze Obsługiwane typy kont wybierz pozycję Konta tylko w tym katalogu organizacyjnym. Aby uzyskać informacje o różnych typach kont, wybierz opcję Pomoc dla mnie .
  5. W obszarze Identyfikator URI przekierowania (opcjonalnie) wybierz pozycję Sieć Web, a następnie wprowadź http://localhost w polu tekstowym 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 aplikacji tożsamości>> Rejestracje aplikacji.
  4. Wybierz opcjęNowa rejestracja.
  5. Wprowadź nazwę aplikacji, taką jak web-app-calls-web-api.
  6. W obszarze Obsługiwane typy kont wybierz pozycję Konta tylko w tym katalogu organizacyjnym. Aby uzyskać informacje o różnych typach kont, wybierz opcję Pomoc dla mnie .
  7. W obszarze Identyfikator URI przekierowania (opcjonalnie) wybierz pozycję Sieć Web, a następnie wprowadź http://localhost w polu tekstowym Adres URL.
  8. Wybierz pozycję Zarejestruj.

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

Dodaj klucz tajny klienta

Wpis tajny klienta to wartość ciągu, której aplikacja może używać do samodzielnej tożsamości, a czasami jest nazywana 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 wpisy tajne Wpisy>tajne>klienta Nowy klucz tajny klienta.

  2. Dodaj opis wpisu tajnego klienta, na przykład Mój klucz tajny 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 Dodaj.

  5. Pamiętaj, aby zarejestrować wartość wpisu tajnego klienta. Ta wartość wpisu tajnego 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 interfejsy>API używane przez moją organizację.>
  2. Wybierz pozycję 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. Na liście rozwijanej Wybierz metodę GET z listy rozwijanej New Request (Nowe żądanie).

  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ść wpisu tajnego klienta rejestracji aplikacji internetowej
    ADRES URL PRZEKIEROWANIA Wprowadź http://localhostwartość , która ustawia adres URL przekierowania na identyfikator URI przekierowania zarejestrowany za pomocą identyfikatora Entra firmy Microsoft.
    Zakres opcji>zaawansowanych 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: