Szybki start: konfigurowanie aplikacji w celu uwidocznienia internetowego interfejsu API

  • Artykuł

W tym przewodniku Szybki start zarejestrujesz internetowy interfejs API przy użyciu Platforma tożsamości Microsoft i uwidocznisz go w aplikacjach klienckich, dodając zakres. Rejestrując internetowy interfejs API i uwidaczniając go za pomocą zakresów, przypisując rolę właściciela i aplikacji, możesz zapewnić dostęp oparty na uprawnieniach do swoich zasobów autoryzowanym użytkownikom i aplikacjom klienckim, które uzyskują dostęp do interfejsu API.

Wymagania wstępne

Rejestrowanie internetowego interfejsu API

Dostęp do interfejsów API wymaga konfiguracji zakresów dostępu i ról. Jeśli chcesz uwidocznić internetowe interfejsy API aplikacji zasobów dla aplikacji klienckich, skonfiguruj zakresy dostępu i role dla interfejsu API. Jeśli chcesz, aby aplikacja kliencka mogła uzyskać dostęp do internetowego interfejsu API, skonfiguruj uprawnienia dostępu do interfejsu API w rejestracji aplikacji.

Aby zapewnić dostęp do zasobów w internetowym interfejsie API w zakresie, należy najpierw zarejestrować interfejs API przy użyciu Platforma tożsamości Microsoft.

Wykonaj kroki opisane w sekcji Rejestrowanie aplikacji w przewodniku Szybki start: rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft.

Pomiń sekcję Identyfikator URI przekierowania (opcjonalnie). Nie musisz konfigurować identyfikatora URI przekierowania dla internetowego interfejsu API, ponieważ żaden użytkownik nie jest zalogowany interaktywnie.

Przypisywanie właściciela aplikacji

  1. W rejestracji aplikacji w obszarze Zarządzanie wybierz pozycję Właściciele i Dodaj właścicieli.
  2. W nowym oknie znajdź i wybierz właścicieli, które chcesz przypisać do aplikacji. Wybrani właściciele są wyświetlani w prawym panelu. Po zakończeniu potwierdź polecenie Wybierz. Właściciele aplikacji będą teraz wyświetlani na liście właściciela.

Uwaga

Upewnij się, że zarówno aplikacja interfejsu API, jak i aplikacja, którą chcesz dodać, aby mieć właściciela, w przeciwnym razie interfejs API nie będzie wyświetlany podczas żądania uprawnień interfejsu API.

Przypisywanie roli aplikacji

  1. W rejestracji aplikacji w obszarze Zarządzanie wybierz pozycję Role aplikacji i Utwórz rolę aplikacji.

  2. Następnie określ atrybuty roli aplikacji w okienku Tworzenie roli aplikacji. W tym przewodniku możesz użyć przykładowych wartości lub określić własne.

    Pole opis Przykład
    Nazwa wyświetlana Nazwa roli aplikacji Rekordy pracowników
    Dozwolone typy składowych Określa, czy rolę aplikacji można przypisać do użytkowników/grup i/lub aplikacji Aplikacje
    Wartość Wartość wyświetlana w oświadczeniu "roles" tokenu Employee.Records
    Opis Bardziej szczegółowy opis roli aplikacji Aplikacje mają dostęp do rekordów pracowników

  3. Zaznacz pole wyboru, aby włączyć rolę aplikacji.

Po zarejestrowaniu internetowego interfejsu API przypisano rolę aplikacji i właściciela, możesz dodać zakresy do kodu interfejsu API, aby zapewnić użytkownikom szczegółowe uprawnienia.

Dodaj zakres

Napiwek

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

Kod w aplikacji klienckiej żąda uprawnień do wykonywania operacji zdefiniowanych przez internetowy interfejs API przez przekazanie tokenu dostępu wraz z żądaniami do chronionego zasobu (internetowego interfejsu API). Internetowy interfejs API wykonuje żądaną operację tylko wtedy, gdy otrzymany token dostępu zawiera zakresy wymagane do wykonania operacji.

Najpierw wykonaj następujące kroki, aby utworzyć przykładowy zakres o nazwie Employees.Read.All:

  1. Zaloguj się do centrum administracyjnego firmy Microsoft Entra jako co najmniej Administracja istrator aplikacji w chmurze.

  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 zawierającej rejestrację aplikacji z menu Katalogi i subskrypcje.

  3. Przejdź do pozycji Identity>Applications> Rejestracje aplikacji, a następnie wybierz rejestrację aplikacji interfejsu API.

  4. Wybieranie pozycji Uwidacznianie interfejsu API

  5. Wybierz pozycję Dodaj obok pozycji Identyfikator URI identyfikatora aplikacji, jeśli jeszcze go nie skonfigurowano.

    Możesz użyć wartości domyślnej lub innego obsługiwanego api://<application-client-id> wzorca identyfikatora URI identyfikatora aplikacji. Identyfikator URI identyfikatora aplikacji działa jako prefiks dla zakresów, do których odwołujesz się w kodzie interfejsu API, i musi być globalnie unikatowy.

  6. Wybierz pozycję Dodaj zakres:

    An app registration's Expose an API pane in the Azure portal

  7. Następnie określ atrybuty zakresu w okienku Dodawanie zakresu . W tym przewodniku możesz użyć przykładowych wartości lub określić własne.

    Pole opis Przykład
    Nazwa zakresu Nazwa zakresu. Typowa konwencja nazewnictwa zakresu to resource.operation.constraint. Employees.Read.All
    Kto może wyrazić zgodę Czy ten zakres może być wyrażony przez użytkowników, czy też jest wymagana zgoda administratora. Wybierz pozycję Tylko administratorzy dla uprawnień dających duże przywileje. Administracja i użytkownicy
    Nazwa wyświetlana zgody administratora Krótki opis celu zakresu, który będą widoczne tylko dla administratorów. Read-only access to Employee records
    Opis na potrzeby wyrażenia zgody przez administratora Bardziej szczegółowy opis uprawnień przyznanych przez zakres, który będzie widoczny tylko dla administratorów. Allow the application to have read-only access to all Employee data.
    Nazwa wyświetlana na potrzeby wyrażenia zgody przez użytkownika Krótki opis przeznaczenia zakresu. Wyświetlane użytkownikom tylko wtedy, gdy ustawisz KtoTo może wyrazić zgodę na Administracja i użytkowników. Read-only access to your Employee records
    Opis na potrzeby wyrażenia zgody przez użytkownika Bardziej szczegółowy opis uprawnień przyznanych przez zakres. Wyświetlane użytkownikom tylko wtedy, gdy ustawisz KtoTo może wyrazić zgodę na Administracja i użytkowników. Allow the application to have read-only access to your Employee data.

  8. Ustaw stan na Włączone, a następnie wybierz pozycję Dodaj zakres.

  9. (Opcjonalnie) Aby pominąć monitowanie o wyrażenie zgody przez użytkowników aplikacji do zdefiniowanych zakresów, możesz wstępnie autoryzować aplikację kliencą w celu uzyskania dostępu do internetowego interfejsu API. Autoryzowanie wstępnie tylko zaufanych aplikacji klienckich, ponieważ użytkownicy nie będą mieli możliwości odrzucenia zgody.

    1. W obszarze Autoryzowane aplikacje klienckie wybierz pozycję Dodaj aplikację kliencką
    2. Wprowadź identyfikator aplikacji (klienta) aplikacji klienckiej, którą chcesz wstępnie autoryzować. Na przykład aplikacja internetowa, która została wcześniej zarejestrowana.
    3. W obszarze Autoryzowane zakresy wybierz zakresy, dla których chcesz pominąć monitowanie o wyrażenie zgody, a następnie wybierz pozycję Dodaj aplikację.

    Jeśli wykonano ten opcjonalny krok, aplikacja kliencka jest teraz wstępnie autoryzowaną aplikacją kliencką (PCA), a użytkownicy nie będą monitowani o zgodę podczas logowania się do niej.

Następnie dodaj kolejny przykładowy zakres o nazwie Employees.Write.All , na który mogą wyrazić zgodę tylko administratorzy. Zakresy wymagające zgody administratora są zwykle używane do zapewniania dostępu do operacji z wyższymi uprawnieniami, a często przez aplikacje klienckie uruchamiane jako usługi zaplecza lub demony, które nie logują się interaktywnie użytkownika.

Aby dodać przykładowy Employees.Write.All zakres, wykonaj kroki opisane w sekcji Dodawanie zakresu i określ następujące wartości w okienku Dodawanie zakresu :

Pole Przykładowa wartość
Nazwa zakresu Employees.Write.All
Kto może wyrazić zgodę tylko Administracja
Nazwa wyświetlana zgody administratora Write access to Employee records
Opis na potrzeby wyrażenia zgody przez administratora Allow the application to have write access to all Employee data.
Nazwa wyświetlana na potrzeby wyrażenia zgody przez użytkownika Brak (pozostaw pusty)
Opis na potrzeby wyrażenia zgody przez użytkownika Brak (pozostaw pusty)

Ustaw stan na Włączone, a następnie wybierz pozycję Dodaj zakres.

Weryfikowanie uwidocznionych zakresów

Jeśli oba przykładowe zakresy opisane w poprzednich sekcjach zostały pomyślnie dodane, zostaną one wyświetlone w okienku Uwidacznianie interfejsu API rejestracji aplikacji internetowego interfejsu API , podobnie jak na poniższej ilustracji:

Screenshot of the Expose an API pane showing two exposed scopes.

Jak pokazano na obrazie, pełny ciąg zakresu to łączenie identyfikatora URI identyfikatora aplikacji internetowego interfejsu API i nazwy zakresu.

Jeśli na przykład identyfikator URI aplikacji internetowego interfejsu API to https://contoso.com/api i nazwa zakresu to Employees.Read.All, pełny zakres to:

https://contoso.com/api/Employees.Read.All

Korzystanie z uwidocznionych zakresów

W następnym artykule z tej serii skonfigurujesz rejestrację aplikacji klienckiej z dostępem do internetowego interfejsu API i zakresami zdefiniowanymi przez wykonanie kroków opisanych w tym artykule.

Gdy rejestracja aplikacji klienckiej ma uprawnienie dostępu do internetowego interfejsu API, klient może otrzymać token dostępu OAuth 2.0 przez platformę tożsamości. Gdy klient wywołuje internetowy interfejs API, przedstawia token dostępu, którego oświadczenie zakresu (scp) jest ustawione na uprawnienia określone w rejestracji aplikacji klienta.

Jeśli jest to konieczne, później można uwidocznić dodatkowe zakresy. Należy wziąć pod uwagę, że internetowy interfejs API może uwidocznić wiele zakresów skojarzonych z kilkoma operacjami. Zasób może kontrolować dostęp do internetowego interfejsu API w czasie wykonywania, oceniając oświadczenia zakresu (scp) w odbieranych tokenach dostępu OAuth 2.0.

Następne kroki

Teraz, po udostępnieniu internetowego interfejsu API, konfigurując jego zakresy, skonfiguruj rejestrację aplikacji klienckiej z uprawnieniami dostępu do zakresów.

Konfigurowanie rejestracji aplikacji na potrzeby dostępu do internetowego interfejsu API