Szybki start: konfigurowanie aplikacji w celu uwidocznienia internetowego interfejsu API
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
- Konto platformy Azure z aktywną subskrypcją — utwórz bezpłatne konto
- Ukończenie przewodnika Szybki start: konfigurowanie dzierżawy
- Aplikacja zarejestrowana w centrum administracyjnym firmy Microsoft Entra. Jeśli go nie masz, zarejestruj aplikację teraz.
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.
- Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako administrator aplikacji w chmurze.
- 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. - Wykonaj kroki opisane w sekcji Rejestrowanie aplikacji i 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
- W rejestracji aplikacji w obszarze Zarządzanie wybierz pozycję Właściciele i Dodaj właścicieli.
- 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
W rejestracji aplikacji w obszarze Zarządzanie wybierz pozycję Role aplikacji i Utwórz rolę aplikacji.
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.RecordsOpis Bardziej szczegółowy opis roli aplikacji Aplikacje mają dostęp do rekordów pracowników Zaznacz pole wyboru, aby włączyć rolę aplikacji, a następnie wybierz pozycję Zastosuj.
Dodaj zakres
Napiwek
Kroki opisane w tym artykule mogą się nieznacznie różnić w zależności od portalu, od którego zaczynasz.
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.
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.
Dodawanie zakresu wymagającego zgody administratora i użytkownika
Najpierw wykonaj następujące kroki, aby utworzyć przykładowy zakres o nazwie Employees.Read.All:
Wybierz opcję Uwidacznianie interfejsu API.
W górnej części strony wybierz pozycję Dodaj obok pozycji Identyfikator URI identyfikatora aplikacji. Ta wartość domyślna to
api://<application-client-id>. 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. Wybierz pozycję Zapisz.Wybierz pozycję Dodaj zakres:
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.AllKto może wyrazić zgodę Czy ten zakres może być wyrażony przez użytkowników, czy też jest wymagana zgoda administratora. Administratorzy powinni używać tylko w przypadku uprawnień z wyższymi uprawnieniami. Administratorzy i użytkownicy Nazwa wyświetlana zgody administratora Krótki opis celu zakresu, który będą widoczne tylko dla administratorów. Dostęp tylko do odczytu do rekordów pracowników 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. Zezwalaj aplikacji na dostęp tylko do odczytu do wszystkich danych pracownika. Nazwa wyświetlana na potrzeby wyrażenia zgody przez użytkownika Krótki opis przeznaczenia zakresu. Wyświetlane użytkownikom tylko wtedy, gdy ustawisz opcję Kto może wyrazić zgodę na administratorów i użytkowników. Dostęp tylko do odczytu do rekordów pracowników 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 opcję Kto może wyrazić zgodę na administratorów i użytkowników. Zezwól aplikacji na dostęp tylko do odczytu do danych pracownika. Stanowy Określa, czy zakres jest włączony, czy wyłączony. Włączono Wybierz Dodaj zakres.
(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.
- W obszarze Autoryzowane aplikacje klienckie wybierz pozycję Dodaj aplikację kliencką
- Wprowadź identyfikator aplikacji (klienta) aplikacji klienckiej, którą chcesz wstępnie autoryzować. Na przykład aplikacja internetowa, która została wcześniej zarejestrowana.
- 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.
Dodawanie zakresu wymagającego zgody administratora
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 te wartości w okienku Dodawanie zakresu . Po zakończeniu wybierz pozycję Dodaj zakres :
| Pole | Przykładowa wartość |
|---|---|
| Nazwa zakresu | Employees.Write.All |
| Kto może wyrazić zgodę | Tylko administratorzy |
| Nazwa wyświetlana zgody administratora | Dostęp do zapisu do rekordów pracowników |
| Opis na potrzeby wyrażenia zgody przez administratora | Zezwól aplikacji na dostęp do zapisu do wszystkich danych pracowników. |
| 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) |
| Stanowy | Włączono |
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:
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ępny krok
Teraz, po udostępnieniu internetowego interfejsu API, konfigurując jego zakresy, skonfiguruj rejestrację aplikacji klienckiej z uprawnieniami dostępu do zakresów.