Udostępnij za pośrednictwem

Szybki start: wywoływanie internetowego interfejsu API w przykładowej aplikacji demona

  • Artykuł

W tym przewodniku szybkiego startu użyjesz przykładowej aplikacji usługi systemowej do uzyskania tokenu dostępu i wywołania chronionego API w sieci używając biblioteki Microsoft Authentication Library (MSAL).

Przed rozpoczęciem użyj wybieraka Wybierz typ najemcy na górze tej strony, aby wybrać typ najemcy. Identyfikator Entra firmy Microsoft udostępnia dwie konfiguracje dzierżawy: dla zasobów pracowniczych i dla podmiotów zewnętrznych. Konfiguracja dzierżawy zasobów dla pracowników dotyczy pracowników, aplikacji wewnętrznych i innych zasobów organizacji. Najemca zewnętrzny jest przeznaczony dla aplikacji skierowanych do klientów.

Przykładowa aplikacja używana w tym przewodniku Szybki start uzyskuje token dostępu do wywoływania interfejsu API programu Microsoft Graph.

Warunki wstępne

  • Konto platformy Azure z aktywną subskrypcją. Jeśli jeszcze go nie masz, 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
  • Najemca zasobów ludzkich. Możesz użyć katalogu domyślnego lub skonfigurować nowego najemcę .
  • Zarejestruj nową aplikację w centrum administracyjnym Microsoft Entra przy użyciu następującej konfiguracji. Aby uzyskać więcej informacji, zobacz sekcję Rejestrowanie aplikacji.
    • Nazwa: identity-client-daemon-app
    • Obsługiwane typy kont: konta w tym katalogu organizacyjnym (tylko jedna dzierżawa)

Utwórz tajny klucz klienta

Utwórz klucz tajny klienta dla zarejestrowanej aplikacji. Aplikacja używa tajnego klucza klienta, aby udowodnić swoją tożsamość, gdy występuje o tokeny.

  1. Na stronie Rejestracje aplikacji wybierz utworzoną aplikację (na przykład tajny klucz klienta aplikacji internetowej), aby otworzyć stronę Omówienie.
  2. W obszarze Zarządzajwybierz pozycję certyfikaty certyfikaty & wpisy tajne>kluczami tajnymi klienta>Nowy klucz tajny klienta.
  3. W polu Opis wprowadź opis tajemnicy klienta (na przykład tajemnica klienta aplikacji webowej).
  4. W obszarze Wygasawybierz czas, na jaki tajemnica jest ważna (zgodnie z regułami zabezpieczeń organizacji), a następnie wybierz Dodaj.
  5. Zarejestruj wartość tajemnicy. Ta wartość jest używana do konfiguracji w późniejszym kroku. Wartość sekretna nie zostanie ponownie wyświetlona i nie można jej odzyskać w żaden sposób, gdy opuścisz Certyfikaty i sekrety. Upewnij się, że został on zarejestrowany.

Podczas tworzenia poświadczeń dla poufnej aplikacji klienckiej:

  • Firma Microsoft zaleca użycie certyfikatu zamiast klucza tajnego klienta przed przeniesieniem aplikacji do środowiska produkcyjnego. Aby uzyskać więcej informacji na temat używania certyfikatu, zobacz instrukcje w poświadczenia certyfikatu uwierzytelniania aplikacji platformy tożsamości firmy Microsoft.

  • Na potrzeby testowania możesz utworzyć certyfikat z podpisem własnym i skonfigurować aplikacje do uwierzytelniania przy użyciu niego. Jednak w środowiskuprodukcyjnym należy zakupić certyfikat podpisany przez dobrze znany urząd certyfikacji, a następnie użyć usługi Azure Key Vault do zarządzania dostępem do certyfikatów i okresem ważności.

Udzielanie uprawnień API dla aplikacji demona

Aby aplikacja demona uzyskiwała dostęp do danych w interfejsie API programu Microsoft Graph, przyznajesz jej wymagane uprawnienia. Aplikacja demona wymaga uprawnień typu aplikacji. Użytkownicy nie mogą wchodzić w interakcje z aplikacją demona, więc administrator dzierżawy musi wyrazić zgodę na te uprawnienia. Wykonaj następujące kroki, aby udzielić uprawnień i wyrazić na nie zgodę:

W przypadku aplikacji demona platformy .NET nie musisz udzielać ani wyrażać zgody na jakiekolwiek uprawnienia. Ta aplikacja demona odczytuje własne informacje o rejestracji aplikacji, dzięki czemu może to zrobić bez udzielenia żadnych uprawnień aplikacji.

Klonowanie lub pobieranie przykładowej aplikacji

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-docs-code-dotnet.git
  • pobierz plik .zip. Wyodrębnij go do ścieżki pliku, w której długość nazwy jest mniejsza niż 260 znaków.

Konfigurowanie projektu

Aby użyć szczegółów rejestracji aplikacji w przykładzie aplikacji demona klienta, wykonaj następujące kroki:

  1. Otwórz okno konsoli, a następnie przejdź do katalogu ms-identity-docs-code-dotnet/console-daemon:

    cd ms-identity-docs-code-dotnet/console-daemon

  2. Otwórz Program.cs i zastąp zawartość pliku następującym fragmentem kodu;

     // Full directory URL, in the form of https://login.microsoftonline.com/<tenant_id>
 Authority = " https://login.microsoftonline.com/Enter_the_tenant_ID_obtained_from_the_Microsoft_Entra_admin_center",
 // 'Enter the client ID obtained from the Microsoft Entra admin center
 ClientId = "Enter the client ID obtained from the Microsoft Entra admin center",
 // Client secret 'Value' (not its ID) from 'Client secrets' in the Microsoft Entra admin center
 ClientSecret = "Enter the client secret value obtained from the Mifcrosoft Entra admin center",
 // Client 'Object ID' of app registration in Microsoft Entra admin center - this value is a GUID
 ClientObjectId = "Enter the client Object ID obtained from the Microsoft Entra admin center"
    • Authority — Autorytet jest adresem URL wskazującym katalog, z którego można żądać tokenów przy użyciu biblioteki MSAL. Zastąp wartość Enter_the_tenant_ID_obtained_from_the_Microsoft_Entra_admin_center identyfikatorem usługi Directory (dzierżawa), która została zarejestrowana wcześniej.
    • ClientId — identyfikator aplikacji, nazywany również klientem. Zastąp tekst w cudzysłowach wartością Application (client) ID zarejestrowaną wcześniej na stronie przeglądu zarejestrowanej aplikacji.
    • ClientSecret — klucz tajny klienta utworzony dla aplikacji w centrum administracyjnym firmy Microsoft Entra. Wprowadź wartość klucza tajnego klienta.
    • ClientObjectId — identyfikator obiektu aplikacji klienckiej. Zastąp tekst w cudzysłowach wartością Object ID zarejestrowaną wcześniej na stronie przeglądu zarejestrowanej aplikacji.

Uruchamianie i testowanie aplikacji

Skonfigurowano przykładową aplikację. Możesz kontynuować uruchamianie i testowanie.

W oknie konsoli uruchom następujące polecenie, aby skompilować i uruchomić aplikację:

dotnet run

Po pomyślnym uruchomieniu aplikacji zostanie wyświetlona odpowiedź podobna do poniższego fragmentu kodu (skrócona w celu zwięzłości):

{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications/$entity",
"id": "00001111-aaaa-2222-bbbb-3333cccc4444",
"deletedDateTime": null,
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"applicationTemplateId": null,
"disabledByMicrosoftStatus": null,
"createdDateTime": "2021-01-17T15:30:55Z",
"displayName": "identity-dotnet-console-app",
"description": null,
"groupMembershipClaims": null,
...
}

Jak to działa

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, używając tożsamości aplikacji, poprzez przedstawienie identyfikatora aplikacji, poświadczenia (tajnego wpisu lub certyfikatu) oraz identyfikatora URI aplikacji. Aplikacja demona używa standardowego trybu udzielania poświadczeń klienta w OAuth 2.0 w celu uzyskania tokenu dostępu.

Aplikacja uzyskuje token dostępu z platformy tożsamości firmy Microsoft. Token dostępu dotyczy API Microsoft Graph. Następnie aplikacja używa tokenu dostępu do żądania własnych szczegółów rejestracji aplikacji z interfejsu API programu Microsoft Graph. Aplikacja może zażądać dowolnego zasobu z interfejsu API programu Microsoft Graph, o ile token dostępu ma odpowiednie uprawnienia.

W przykładzie pokazano, jak zadanie nienadzorowane lub usługa systemu Windows może być uruchamiana przy użyciu tożsamości aplikacji zamiast tożsamości użytkownika.

Powiązana zawartość

Warunki wstępne

  • Konto platformy Azure z aktywną subskrypcją. Jeśli jeszcze go nie masz, 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
  • Zewnętrzny najemca Aby go utworzyć, wybierz jedną z następujących metod:
  • Zarejestruj nową aplikację w centrum administracyjnym Microsoft Entra przy użyciu następującej konfiguracji. Aby uzyskać więcej informacji, zobacz Rejestrowanie aplikacji.
    • Nazwa: ciam-daemon-app
    • Obsługiwane typy kont: konta w tym katalogu organizacyjnym (pojedynczy dzierżawca)
  • Visual Studio Code lub inny edytor kodu.
  • .NET 7.0 lub nowsza.
  • Node.js (tylko w przypadku implementacji węzła)

Utwórz tajny klucz klienta

Utwórz klucz tajny klienta dla zarejestrowanej aplikacji. Aplikacja używa sekretu klienta, aby udowodnić swoją tożsamość, gdy żąda tokenów.

  1. Na stronie Rejestracje aplikacji wybierz utworzoną aplikację (taką jak tajny klucz klienta aplikacji webowej), aby otworzyć stronę Przegląd.
  2. W obszarze Zarządzajwybierz pozycję Certyfikaty & tajne>tajne klienta>Nowe tajne klienta.
  3. W polu Opis wprowadź opis tajnego klucza klienta (na przykład tajny klucz klienta aplikacji internetowej).
  4. W obszarze Wygasawybierz okres ważności, przez który tajna wartość jest ważna (zgodnie z regułami zabezpieczeń organizacji), a następnie wybierz pozycję Dodaj.
  5. Zarejestruj wartość sekretną. Ta wartość jest używana do konfiguracji w późniejszym kroku. Wartość tajna nie zostanie ponownie wyświetlona i nie będzie można jej odzyskać w żaden sposób, po przejściu z Certyfikaty i sekrety. Upewnij się, że został on zarejestrowany.

Podczas tworzenia poświadczeń dla poufnej aplikacji klienckiej:

  • Firma Microsoft zaleca użycie certyfikatu zamiast klucza tajnego klienta przed przeniesieniem aplikacji do środowiska produkcyjnego. Aby uzyskać więcej informacji na temat używania certyfikatu, zobacz instrukcje w poświadczenia certyfikatu uwierzytelniania aplikacji na platformie tożsamości Microsoft.

  • Na potrzeby testowania możesz utworzyć certyfikat z podpisem własnym i skonfigurować aplikacje do uwierzytelniania przy użyciu niego. Jednak wprodukcyjnym należy zakupić certyfikat podpisany przez dobrze znany urząd certyfikacji, a następnie użyć usługi Azure Key Vault do zarządzania dostępem do certyfikatów i okresem istnienia.

Udziel uprawnień API aplikacji demona

  1. Na stronie Rejestracje aplikacji wybierz utworzoną aplikację, taką jak ciam-client-app.

  2. W obszarze Zarządzajwybierz pozycję uprawnienia interfejsu API .

  3. W obszarze Skonfigurowane uprawnieniawybierz pozycję Dodaj nowe uprawnienie.

  4. Wybierz interfejsy API używane przez moją organizację na karcie.

  5. Na liście interfejsów API wybierz API, takie jak ciam-ToDoList-api.

  6. Wybierz opcję Uprawnienia aplikacji. Wybieramy tę opcję, gdy aplikacja loguje się jako sama, ale nie w imieniu użytkownika.

  7. Z listy uprawnień wybierz pozycję TodoList.Read.All, ToDoList.ReadWrite.All (w razie potrzeby użyj pola wyszukiwania).

  8. Wybierz przycisk Dodaj uprawnienia.

  9. W tym momencie poprawnie przypisałeś uprawnienia. 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:

    1. Wybierz Udziel zgody administratora dla <nazwy dzierżawy>, a następnie wybierz Tak.
    2. Wybierz pozycję Odśwież, a następnie sprawdź, czy Udzielono <nazwa dzierżawy> jest wyświetlana w obszarze Stan dla obu uprawnień.

Konfigurowanie ról aplikacji

Interfejs API musi opublikować co najmniej jedną rolę aplikacji dla aplikacji, nazywanych również uprawnieniami aplikacji , aby aplikacje klienckie uzyskiwały token dostępu samodzielnie. Uprawnienia aplikacji to typ uprawnień, które interfejsy API powinny publikować, gdy chcą umożliwić aplikacjom klienckim pomyślne uwierzytelnienie się własnym imieniem, bez konieczności logowania użytkowników. Aby opublikować uprawnienie aplikacji, wykonaj następujące kroki:

  1. Na stronie rejestracje aplikacji wybierz utworzoną aplikację (na przykład ciam-ToDoList-api), aby otworzyć jej stronę Przegląd.

  2. W obszarze Zarządzajwybierz Role aplikacji.

  3. 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łasność Wartość
    Nazwa wyświetlana ToDoList.Read.All
    Dozwolone typy członków Aplikacji
    Wartość ToDoList.Read.All
    Opis Zezwalaj aplikacji na odczytywanie listy zadań każdego użytkownika przy użyciu "TodoListApi"
    Czy chcesz włączyć tę rolę aplikacji? Pozostaw zaznaczone

  4. 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łasność Wartość
    Nazwa wyświetlana ToDoList.ReadWrite.All
    Dozwolone typy składowych Aplikacje
    Wartość ToDoList.ReadWrite.All
    Opis Zezwól aplikacji na odczytywanie i zapisywanie list zadań do wykonania każdego użytkownika przy użyciu "ToDoListApi".
    Czy chcesz włączyć tę rolę aplikacji? Pozostaw to zaznaczone

Konfigurowanie opcjonalnych oświadczeń

Możesz dodać opcjonalne oświadczenie idtyp, aby ułatwić interfejsowi API sieci Web określenie, czy token jest tokenem aplikacji , czy tokenem aplikacji i tokenu użytkownika. Chociaż można użyć kombinacji oświadczeń scp i ról w tym samym celu, użycie oświadczenia idtyp jest najprostszym sposobem na odróżnienie tokenu aplikacji od tokenu aplikacji + użytkownika. Na przykład wartość tego roszczenia to aplikacji, gdy token jest tokenem wyłącznie dla aplikacji.

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-javascript-tutorial.git

  • Alternatywnie pobrać pliki przykładowe .zip, a następnie wyodrębnić do ścieżki, mającej długość nazwy krótszą niż 260 znaków.

Instalowanie zależności projektu

  1. Otwórz okno konsoli i przejdź do katalogu zawierającego przykładową aplikację Node.js:

    cd 2-Authorization\3-call-api-node-daemon\App

  2. Uruchom następujące polecenia, aby zainstalować zależności aplikacji:

    npm install && npm update

Konfigurowanie przykładowej aplikacji demona i interfejsu API

Aby użyć szczegółów rejestracji aplikacji w przykładzie aplikacji internetowej klienta, wykonaj następujące kroki:

  1. W edytorze kodu otwórz plik App\authConfig.js.

  2. Znajdź symbol zastępczy:

    • Enter_the_Application_Id_Here i zastąp go identyfikatorem aplikacji (klienta) dla demona, który zarejestrowałeś wcześniej.

    • Enter_the_Tenant_Subdomain_Here i zastąp ją poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj contoso. Jeśli nie masz nazwy lokatora, dowiedz się, jak sprawdzać dane lokatora.

    • Enter_the_Client_Secret_Here i zastąp to wcześniej skopiowaną wartością tajnego klucza aplikacji demon.

    • Enter_the_Web_Api_Application_Id_Here i zastąp go identyfikatorem aplikacji (klienta) skopiowanego wcześniej internetowego interfejsu API.

Aby użyć rejestracji aplikacji w przykładowym interfejsie API dla sieci:

  1. W edytorze kodu otwórz plik API\ToDoListAPI\appsettings.json.

  2. Znajdź symbol zastępczy:

    • Enter_the_Application_Id_Here i zastąp go identyfikatorem aplikacji (klienta) skopiowanego internetowego interfejsu API.

    • Enter_the_Tenant_Id_Here i zastąp go wcześniej skopiowanym identyfikatorem katalogu (dzierżawy).

    • Enter_the_Tenant_Subdomain_Here i zastąp ją poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj contoso. Jeśli nie masz nazwy dzierżawcy, dowiedz się, jak sprawdzić szczegóły dzierżawcy.

Uruchamianie i testowanie przykładowej aplikacji demona i interfejsu API

Skonfigurowano przykładową aplikację. Możesz kontynuować uruchamianie i testowanie.

  1. Otwórz okno konsoli, a następnie uruchom internetowy interfejs API przy użyciu następujących poleceń:

    cd 2-Authorization\3-call-api-node-daemon\API\ToDoListAPI
dotnet run

  2. Uruchom klienta aplikacji internetowej przy użyciu następujących poleceń:

    2-Authorization\3-call-api-node-daemon\App
node . --op getToDos

Jeśli aplikacja demona i internetowy interfejs API zostały pomyślnie uruchomione, w oknie konsoli powinien zostać wyświetlony kod podobny do poniższej tablicy JSON.

{
    "id": 1,
    "owner": "3e8....-db63-43a2-a767-5d7db...",
    "description": "Pick up grocery"
},
{
    "id": 2,
    "owner": "c3cc....-c4ec-4531-a197-cb919ed.....",
    "description": "Finish invoice report"
},
{
    "id": 3,
    "owner": "a35e....-3b8a-4632-8c4f-ffb840d.....",
    "description": "Water plants"
}

Jak to działa

Aplikacja Node.js używa potoku udzielania dostępu dla poświadczeń klienta OAuth 2.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 wcześniej eksponowałeś w interfejsie API sieciowym, a następnie przyznałeś je aplikacji demona.

Po stronie interfejsu API przykładowy internetowy interfejs API platformy .NET musi sprawdzić, czy token dostępu ma wymagane uprawnienia (uprawnienia aplikacji). Internetowy interfejs API nie może zaakceptować tokenu dostępu, który nie ma wymaganych uprawnień.

Dostęp do danych

Punkt końcowy internetowego interfejsu API powinien być przygotowany do akceptowania wywołań zarówno od użytkowników, jak i aplikacji. W związku z tym powinna ona mieć sposób na odpowiednie reagowanie na każde żądanie. Na przykład, wywołanie od użytkownika za pośrednictwem delegowanych uprawnień/zakresów uzyskuje dostęp do listy danych użytkownika to-do. Z drugiej strony wywołanie z aplikacji za pośrednictwem uprawnień/ról aplikacji może odbierać całą listę to-do. Jednak w tym artykule wykonujemy tylko wywołanie aplikacji, więc nie musieliśmy konfigurować delegowanych uprawnień/zakresów.

Powiązana zawartość