Wywoływanie internetowego interfejsu API platformy ASP.NET Core za pomocą biblioteki cURL

W tym artykule przedstawiono sposób wywoływania chronionego internetowego interfejsu API platformy ASP.NET Core przy użyciu adresu URL klienta (cURL). cURL to narzędzie wiersza polecenia, którego deweloperzy używają do transferu danych do i z serwera. 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 biblioteki cURL.

W tym artykule przedstawiono sposób wywoływania chronionego internetowego interfejsu API platformy ASP.NET Core przy użyciu adresu URL klienta (cURL). cURL to narzędzie wiersza polecenia, którego deweloperzy używają do transferu danych do i z serwera. 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żyjesz tokenu, aby wykonać autoryzowane wywołanie interfejsu API przy użyciu biblioteki cURL.

Warunki 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 program cURL na komputerze stacji roboczej.
• Minimalne wymaganie zestawu .NET 8.0 SDK.

• 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
• Ukończenie serii samouczków:
  • Samouczek: rejestrowanie internetowego interfejsu API przy użyciu Platforma tożsamości Microsoft.
  • Samouczek: tworzenie i konfigurowanie projektu ASP.NET Core na potrzeby uwierzytelniania.
  • Samouczek: implementowanie chronionego punktu końcowego do interfejsu API.
• Pobierz i zainstaluj program cURL na komputerze stacji roboczej.

Rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft

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 pozycję 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.

   

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

   

Nuta

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 pozycję Dodaj zakres. Jeśli zakres został wprowadzony poprawnie, zostanie on wyświetlony w okienku Uwidacznianie interfejsu API .

   

Rejestrowanie aplikacji internetowej

Posiadanie internetowego interfejsu API nie wystarczy, ponieważ aplikacja internetowa jest również potrzebna do uzyskania tokenu dostępu w celu uzyskania dostępu do utworzonego internetowego interfejsu API.

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 pozycję Nowa rejestracja.
3. Wprowadź nazwę aplikacji, na przykład 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 pozycję Nowa rejestracja.
5. Wprowadź nazwę aplikacji, na przykład 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 rejestracja jest wyświetlana w okienku Przegląd . Zarejestruj identyfikator katalogu (dzierżawy) i identyfikator aplikacji (klienta), które mają być używane w kolejnych krokach.

Dodawanie wpisu tajnego 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 wygaśnięcie wpisu tajnego lub określ okres istnienia niestandardowego.

   • 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ść wpisu tajnego klienta. Ta wartość wpisu tajnego nigdy nie jest wyświetlana ponownie po opuszczeniu tej strony.

Dodawanie uprawnień aplikacji w celu zezwolenia na dostęp do internetowego interfejsu API

Określając zakresy internetowego interfejsu API w rejestracji aplikacji internetowej, 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 aplikacji internetowej do internetowego interfejsu API:

1. W okienku Przegląd aplikacji internetowej (web-app-that-calls-web-api) w obszarze Zarządzanie wybierz pozycję Uprawnienia>interfejsu API Dodaj interfejsy API uprawnień>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

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 folderu i otwórz ./appsettings.json plik, zastąp element i{DIRECTORY_TENANT_ID}:{APPLICATION_CLIENT_ID}

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

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

   .NET 6.0

   dotnet run
   

   .NET 7.0

   dotnet run --launch-profile https
   

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

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.

.NET 6.0

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

   dotnet run
   

.NET 7.0

1. Wykonaj następujące polecenie, aby uruchomić aplikację w https profilu:

   dotnet run --launch-profile https
   

1. 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}
   ...
   

Żądanie kodu autoryzacji

Przepływ kodu autoryzacji rozpoczyna się od klienta kierującego użytkownika do punktu końcowego /authorize . W tym żądaniu klient żąda Forecast.Read uprawnień od użytkownika.

https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize?client_id={web-app-calls-web-api_application_client_id}&response_type=code&redirect_uri=http://localhost&response_mode=query&scope=api://{web_API_application_client_id}/Forecast.Read

1. Skopiuj adres URL, zastąp następujące parametry i wklej go w przeglądarce:

   • {tenant_id}to identyfikator katalogu aplikacji internetowej (dzierżawy).
   • {web-app-calls-web-api_application_client_id}to identyfikator aplikacji (klienta) w okienku Przegląd aplikacji internetowej (web-app-calls-web-api).
   • {web_API_application_client_id}to identyfikator aplikacji (klienta) w okienku Przegląd interfejsu API sieci Web (NewWebAPI1).

2. Zaloguj się jako użytkownik w dzierżawie firmy Microsoft Entra, w której są zarejestrowane aplikacje. W razie potrzeby wyrażanie zgody na wszelkie żądania dostępu.

3. Przeglądarka zostanie przekierowana do http://localhost/. Zapoznaj się z paskiem nawigacyjnym przeglądarki i skopiuj element {authorization_code} , aby użyć go w poniższych krokach. Adres URL ma postać następującego fragmentu kodu:

   http://localhost/?code={authorization_code}
   

Uzyskiwanie tokenu dostępu przy użyciu kodu autoryzacji i biblioteki cURL

Program cURL może teraz służyć do żądania tokenu dostępu z Platforma tożsamości Microsoft.

1. Skopiuj polecenie cURL w poniższym fragmencie kodu. Zastąp wartości w nawiasach następującymi parametrami do terminalu. Pamiętaj, aby usunąć nawiasy:

   Bash

   curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token \
   -d 'client_id={web-app-calls-web-api_application_client_id}' \
   -d 'api://{web_API_application_client_id}/Forecast.Read' \
   -d 'code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}' \
   -d 'redirect_uri=http://localhost' \
   -d 'grant_type=authorization_code' \
   -d 'client_secret={client_secret}'
   

   Wiersz polecenia systemu Windows

   curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token ^
    -d "client_id={web-app-calls-web-api_application_client_id}" ^
    -d "api://{web_API_application_client_id}/Forecast.Read" ^
    -d "code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}" ^
    -d "redirect_uri=http://localhost" ^
    -d "grant_type=authorization_code" ^
    -d "client_secret={client_secret}"
   

   • {tenant_id}to identyfikator katalogu aplikacji internetowej (dzierżawy).
   • client_id={web-app-calls-web-api_application_client_id}i to identyfikator aplikacji (klienta) w okienku Przegląd aplikacji internetowej (web-app-calls-web-api). session_state={web-app-calls-web-api_application_client_id}
   • api://{web_API_application_client_id}/Forecast.Readto identyfikator aplikacji (klienta) w okienku Przegląd interfejsu API sieci Web (NewWebAPI1).
   • code={authorization_code} to kod autoryzacji, który został odebrany w żądaniu kodu autoryzacji. Dzięki temu narzędzie cURL może zażądać tokenu dostępu.
   • client_secret={client_secret}to wartość wpisu tajnego klienta zarejestrowana w obszarze Dodawanie wpisu tajnego klienta.

2. Uruchom polecenie cURL i jeśli wprowadzono poprawnie, powinna zostać odebrana odpowiedź JSON podobna do następujących danych wyjściowych:

   {
      "token_type": "Bearer",
      "scope": "api://{web_API_application_client_id}/Forecast.Read",
      "expires_in": 3600,
      "ext_expires_in": 3600,
      "access_token": "{access_token}"
   }
   

Wywoływanie internetowego interfejsu API przy użyciu tokenu dostępu

Uruchamiając poprzednie polecenie cURL, Platforma tożsamości Microsoft dostarczył token dostępu. Uzyskany token może być teraz używany jako element nośny w żądaniu HTTP w celu wywołania internetowego interfejsu API.

1. Aby wywołać internetowy interfejs API, skopiuj następujące polecenie cURL, zastąp następujące wartości w nawiasach i wklej go w terminalu:

   curl -X GET https://localhost:{port}/weatherforecast -ki \
   -H 'Content-Type: application/json' \
   -H "Authorization: Bearer {access_token}"
   

   • {access_token} wartość tokenu dostępu zarejestrowana z danych wyjściowych JSON w poprzedniej sekcji.
   • {port} numer portu z internetowego interfejsu API zarejestrowany podczas uruchamiania interfejsu API w terminalu. Upewnij się, że jest https to numer portu.

2. W przypadku prawidłowego tokenu dostępu zawartego w żądaniu oczekiwana odpowiedź jest HTTP/2 200 z danymi wyjściowymi podobnymi do następujących danych wyjściowych:

   HTTP/2 200
   content-type: application/json; charset=utf-8
   date: Day, DD Month YYYY HH:MM:SS
   server: Kestrel
   [{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":36,"summary":"Hot","temperatureF":96},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":43,"summary":"Warm","temperatureF":109},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":18,"summary":"Warm","temperatureF":64},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":50,"summary":"Chilly","temperatureF":121},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":3,"summary":"Bracing","temperatureF":37}]
   

Następne kroki

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

• przepływ kodu autoryzacji Platforma tożsamości Microsoft i protokołu OAuth 2.0
• Typy aplikacji dla Platforma tożsamości Microsoft