Wywoływanie interfejsu API w przykładowej aplikacji demona platformy .NET
W tym przewodniku użyto przykładowej aplikacji demona platformy .NET, aby pokazać, jak aplikacja demona uzyskuje token w celu wywołania chronionego internetowego interfejsu API. Firma Microsoft Entra chroni internetowy interfejs API.
Aplikacja demona uzyskuje token w imieniu siebie (nie w imieniu użytkownika). Użytkownicy nie mogą wchodzić w interakcje z aplikacją demona, ponieważ wymaga własnej tożsamości. Ten typ aplikacji żąda tokenu dostępu przy użyciu tożsamości aplikacji i przedstawienia identyfikatora aplikacji, poświadczeń (hasła lub certyfikatu) oraz identyfikatora URI identyfikatora aplikacji do Tożsamość zewnętrzna Microsoft Entra.
Wymagania wstępne
- Visual Studio Code lub inny edytor kodu
- .NET 7.0 lub nowszy.
- Dzierżawa zewnętrzna. Aby go utworzyć, wybierz jedną z następujących metod:
- (Zalecane) Użyj rozszerzenia Tożsamość zewnętrzna Microsoft Entra, aby skonfigurować dzierżawę zewnętrzną bezpośrednio w programie Visual Studio Code.
- Utwórz nową dzierżawę zewnętrzną w centrum administracyjnym firmy Microsoft Entra.
Rejestrowanie aplikacji demona i internetowego interfejsu API
W tym kroku utworzysz demona i rejestrację aplikacji internetowego interfejsu API, a następnie określisz zakresy internetowego interfejsu API.
Rejestrowanie aplikacji internetowego interfejsu API
Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako deweloper aplikacji.
Jeśli masz dostęp do wielu dzierżaw, użyj ikony
Ustawienia w górnym menu, aby przełączyć się do dzierżawy zewnętrznej z menu Katalogi i subskrypcje.Przejdź do aplikacji tożsamości>> Rejestracje aplikacji.
Wybierz pozycję + Nowa rejestracja.
Na wyświetlonej stronie Rejestrowanie aplikacji wprowadź informacje o rejestracji aplikacji:
W sekcji Nazwa wprowadź zrozumiałą nazwę aplikacji, która będzie wyświetlana użytkownikom aplikacji, na przykład ciam-ToDoList-api.
W obszarze Obsługiwane typy kont wybierz pozycję Konta tylko w tym katalogu organizacyjnym.
Wybierz pozycję Zarejestruj, aby utworzyć aplikację.
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.
Konfigurowanie ról aplikacji
Interfejs API musi opublikować co najmniej jedną rolę aplikacji dla aplikacji, nazywanych również uprawnieniem aplikacji, aby aplikacje klienckie uzyskały token dostępu jako siebie. Uprawnienia aplikacji to typ uprawnień, które interfejsy API powinny publikować, gdy chcą umożliwić aplikacjom klienckim pomyślne uwierzytelnienie się jako siebie i nie trzeba logować użytkowników. Aby opublikować uprawnienie aplikacji, wykonaj następujące kroki:
Na stronie Rejestracje aplikacji wybierz utworzoną aplikację (np. ciam-ToDoList-api), aby otworzyć stronę Przegląd.
W obszarze Zarządzanie wybierz pozycję Role aplikacji.
Wybierz pozycję Utwórz rolę aplikacji, a następnie wprowadź następujące wartości, a następnie wybierz pozycję Zastosuj , aby zapisać zmiany:
Właściwości Wartość Display name ToDoList.Read.All Dozwolone typy składowych Aplikacje Wartość ToDoList.Read.All opis Zezwalaj aplikacji na odczytywanie listy zadań do wykonania każdego użytkownika przy użyciu listy "TodoListApi" Ponownie wybierz pozycję Utwórz rolę aplikacji, a następnie wprowadź następujące wartości dla drugiej roli aplikacji, a następnie wybierz pozycję Zastosuj , aby zapisać zmiany:
Właściwości Wartość Display name ToDoList.ReadWrite.All Dozwolone typy składowych Aplikacje Wartość ToDoList.ReadWrite.All opis Zezwalaj aplikacji na odczytywanie i zapisywanie listy zadań do wykonania każdego użytkownika przy użyciu listy "ToDoListApi"
Konfigurowanie opcjonalnych oświadczeń
Możesz idtyp opcjonalne oświadczenie, aby ułatwić interfejsowi API sieci Web określenie, czy token jest tokenem aplikacji, czy aplikacją i tokenem użytkownika. Mimo że w tym samym celu można użyć kombinacji oświadczeń scp i ról , użycie oświadczenia idtyp jest najprostszym sposobem przekazania tokenu aplikacji i tokenu użytkownika. Na przykład wartość tego oświadczenia to aplikacja , gdy token jest tokenem tylko dla aplikacji.
Rejestrowanie aplikacji demona
Aby umożliwić aplikacji logowanie użytkowników w usłudze Microsoft Entra, Tożsamość zewnętrzna Microsoft Entra należy pamiętać o tworzonej aplikacji. Rejestracja aplikacji ustanawia relację zaufania między aplikacją a firmą Microsoft Entra. Podczas rejestrowania aplikacji identyfikator zewnętrzny generuje unikatowy identyfikator znany jako identyfikator aplikacji (klienta) — wartość używana do identyfikowania aplikacji podczas tworzenia żądań uwierzytelniania.
W poniższych krokach pokazano, jak zarejestrować aplikację w centrum administracyjnym firmy Microsoft Entra:
Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako deweloper aplikacji.
Jeśli masz dostęp do wielu dzierżaw, użyj ikony
Ustawienia w górnym menu, aby przełączyć się do dzierżawy zewnętrznej z menu Katalogi i subskrypcje.Przejdź do aplikacji tożsamości>> Rejestracje aplikacji.
Wybierz pozycję + Nowa rejestracja.
Na wyświetlonej stronie Rejestrowanie aplikacji ;
- Wprowadź zrozumiałą nazwę aplikacji wyświetlaną użytkownikom aplikacji, na przykład ciam-client-app.
- W obszarze Obsługiwane typy kont wybierz pozycję Konta tylko w tym katalogu organizacyjnym.
Wybierz pozycję Zarejestruj.
Po pomyślnej rejestracji zostanie wyświetlone okienko Przegląd aplikacji. Zarejestruj identyfikator aplikacji (klienta), który ma być używany w kodzie źródłowym aplikacji.
Tworzenie wpisu tajnego klienta
Utwórz klucz tajny klienta dla zarejestrowanej aplikacji. Aplikacja używa wpisu tajnego klienta, aby udowodnić swoją tożsamość, gdy żąda tokenów.
- Na stronie Rejestracje aplikacji wybierz utworzoną aplikację (np. ciam-client-app), aby otworzyć stronę Przegląd.
- W obszarze Zarządzanie wybierz pozycję Certyfikaty i wpisy tajne.
- Wybierz Nowy klucz tajny klienta.
- W polu Opis wprowadź opis wpisu tajnego klienta (na przykład wpis tajny klienta aplikacji ciam).
- W obszarze Wygasa wybierz czas trwania, dla którego wpis tajny jest prawidłowy (zgodnie z regułami zabezpieczeń organizacji), a następnie wybierz pozycję Dodaj.
- Zarejestruj wartość wpisu tajnego. Użyjesz tej wartości do konfiguracji w późniejszym kroku. Wartość wpisu tajnego nie zostanie ponownie wyświetlona i nie będzie pobierana w żaden sposób po przejściu z obszaru Certyfikaty i wpisy tajne. Upewnij się, że został on zarejestrowany.
Udzielanie uprawnień interfejsu API do aplikacji demona
Na stronie Rejestracje aplikacji wybierz utworzoną aplikację, na przykład ciam-client-app.
W obszarze Zarządzanie wybierz pozycję Uprawnienia interfejsu API.
W obszarze Skonfigurowane uprawnienia wybierz pozycję Dodaj uprawnienie.
Wybierz kartę Interfejsy API używane przez moją organizację.
Na liście interfejsów API wybierz interfejs API, taki jak ciam-ToDoList-api.
Wybierz opcję Uprawnienia aplikacji. Wybieramy tę opcję, gdy aplikacja loguje się jako sama, ale nie w imieniu użytkownika.
Z listy uprawnień wybierz pozycję TodoList.Read.All, ToDoList.ReadWrite.All (w razie potrzeby użyj pola wyszukiwania).
Wybierz przycisk Dodaj uprawnienia.
W tym momencie przypisano uprawnienia poprawnie. Jednak ponieważ aplikacja demona nie zezwala użytkownikom na interakcję z nią, sami użytkownicy nie mogą wyrazić zgody na te uprawnienia. Aby rozwiązać ten problem, administrator musi wyrazić zgodę na te uprawnienia w imieniu wszystkich użytkowników w dzierżawie:
- Wybierz pozycję Udziel zgody administratora dla <swojej nazwy> dzierżawy, a następnie wybierz pozycję Tak.
- Wybierz pozycję Odśwież, a następnie sprawdź, czy w obszarze Stan dla obu uprawnień jest wyświetlana wartość Przyznane dla <nazwy> dzierżawy.
Klonowanie lub pobieranie przykładowej aplikacji demona i internetowego interfejsu API
Aby uzyskać przykładową aplikację, możesz ją sklonować z usługi GitHub lub pobrać jako plik .zip.
Aby sklonować przykład, otwórz wiersz polecenia i przejdź do miejsca, w którym chcesz utworzyć projekt, a następnie wprowadź następujące polecenie:
git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.gitPobierz plik .zip. Wyodrębnij go do ścieżki pliku, w której długość nazwy jest mniejsza niż 260 znaków.
Konfigurowanie przykładowej aplikacji demona i interfejsu API
Aby użyć rejestracji aplikacji w przykładowej aplikacji internetowej klienta:
W edytorze kodu otwórz plik ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListClient/appsettings.json .
Znajdź symbol zastępczy:
Enter_the_Application_Id_Herezastąp go identyfikatorem aplikacji (klienta) zarejestrowanej wcześniej aplikacji demona.Enter_the_Tenant_Subdomain_Herei zastąp ją poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy tocontoso.onmicrosoft.com, użyj poleceniacontoso. Jeśli nie masz swojej nazwy dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.Enter_the_Client_Secret_Herei zastąp ją skopiowaną wcześniej wartością wpisu tajnego aplikacji demona.Enter_the_Web_Api_Application_Id_Herezastąp go identyfikatorem aplikacji (klienta) skopiowanego wcześniej internetowego interfejsu API.
Aby użyć rejestracji aplikacji w przykładowym internetowym interfejsie API:
W edytorze kodu otwórz plik ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI/appsettings.json .
Znajdź symbol zastępczy:
Enter_the_Application_Id_Herei zastąp go identyfikatorem aplikacji (klienta) skopiowanego internetowego interfejsu API.Enter_the_Tenant_Id_Herei zastąp go skopiowanymi wcześniej identyfikatorami katalogu (dzierżawy).Enter_the_Tenant_Subdomain_Herei zastąp ją poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy tocontoso.onmicrosoft.com, użyj poleceniacontoso. Jeśli nie masz swojej nazwy dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
Uruchamianie i testowanie przykładowej aplikacji demona i interfejsu API
Otwórz okno konsoli, a następnie uruchom internetowy interfejs API przy użyciu następujących poleceń:
cd 2-Authorization\3-call-own-api-dotnet-core-daemon\ToDoListAPI dotnet runUruchom klienta demona, używając następujących poleceń:
cd 2-Authorization\3-call-own-api-dotnet-core-daemon\ToDoListClient dotnet run
Jeśli aplikacja demona i internetowy interfejs API zostały pomyślnie uruchomione, w oknie konsoli powinien zostać wyświetlony kod podobny do następującej tablicy JSON:
Posting a to-do...
Retrieving to-do's from server...
To-do data:
ID: 1
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Bake bread
Posting a second to-do...
Retrieving to-do's from server...
To-do data:
ID: 1
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Bake bread
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Butter bread
Deleting a to-do...
Retrieving to-do's from server...
To-do data:
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Butter bread
Editing a to-do...
Retrieving to-do's from server...
To-do data:
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Eat bread
Deleting remaining to-do...
Retrieving to-do's from server...
There are no to-do's in server
Jak to działa
Aplikacja demona używa poświadczeń klienta OAuth2.0, aby uzyskać token dostępu dla siebie, a nie dla użytkownika. Token dostępu, którego żąda aplikacja, zawiera uprawnienia reprezentowane jako role. Przepływ poświadczeń klienta używa tego zestawu uprawnień zamiast zakresów użytkownika dla tokenów aplikacji. Te uprawnienia aplikacji zostały ujawnione wcześniej w internetowym interfejsie API, a następnie przyznano je aplikacji demona. Aplikacja demona w tym artykule używa biblioteki Microsoft Authentication Library for .NET , aby uprościć proces uzyskiwania tokenu.
Po stronie interfejsu API internetowy interfejs API musi sprawdzić, czy token dostępu ma wymagane uprawnienia (uprawnienia aplikacji). Internetowy interfejs API odrzuca tokeny dostępu, które nie mają wymaganych uprawnień.