Chroniony internetowy interfejs API: rejestracja aplikacji

W tym artykule wyjaśniono, jak zarejestrować aplikację dla chronionego internetowego interfejsu API.

Aby zapoznać się z typowymi krokami rejestrowania aplikacji, zobacz Szybki start: rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft.

Zaakceptowana wersja tokenu

Platforma tożsamości Microsoft może wystawiać tokeny w wersji 1.0 i tokeny w wersji 2.0. Aby uzyskać więcej informacji na temat tych tokenów, zapoznaj się z tematem Tokeny dostępu.

Wersja tokenu, którą może zaakceptować interfejs API, zależy od wyboru obsługiwanych typów kont podczas tworzenia rejestracji aplikacji internetowego interfejsu API w witrynie Azure Portal.

• Jeśli wartość Obsługiwanych typów kont to Konta w dowolnym katalogu organizacyjnym i osobistych kontach Microsoft (takich jak Skype, Xbox, Outlook.com), zaakceptowana wersja tokenu musi być w wersji 2.0.
• W przeciwnym razie zaakceptowana wersja tokenu może być w wersji 1.0.

Po utworzeniu aplikacji można określić lub zmienić zaakceptowaną wersję tokenu, wykonując następujące kroki:

1. W centrum administracyjnym firmy Microsoft Entra wybierz aplikację, a następnie wybierz pozycję Manifest.
2. Znajdź właściwość accessTokenAcceptedVersion w manifeście.
3. Wartość określa firmę Microsoft Entra, która wersja tokenu akceptuje internetowy interfejs API.
   • Jeśli wartość to 2, internetowy interfejs API akceptuje tokeny w wersji 2.0.
   • Jeśli wartość ma wartość null, internetowy interfejs API akceptuje tokeny w wersji 1.0.
4. Jeśli zmieniono wersję tokenu, wybierz pozycję Zapisz.

Internetowy interfejs API określa wersję tokenu, którą akceptuje. Gdy klient żąda tokenu dla internetowego interfejsu API z Platforma tożsamości Microsoft, klient otrzymuje token wskazujący, która wersja tokenu akceptuje internetowy interfejs API.

Brak identyfikatora URI przekierowania

Internetowe interfejsy API nie muszą rejestrować identyfikatora URI przekierowania, ponieważ żaden użytkownik nie jest zalogowany interaktywnie.

Uwidoczniony interfejs API

Inne ustawienia specyficzne dla internetowych interfejsów API to uwidoczniony interfejs API i uwidocznione zakresy lub role aplikacji.

Zakresy i identyfikator URI identyfikatora aplikacji

Zakresy zwykle mają formularz resourceURI/scopeName. W przypadku programu Microsoft Graph zakresy mają skróty. Na przykład User.Read jest skrótem dla elementu https://graph.microsoft.com/user.read.

Podczas rejestracji aplikacji zdefiniuj następujące parametry:

• Identyfikator URI zasobu
• Co najmniej jeden zakres
• Co najmniej jedna rola aplikacji

Domyślnie portal rejestracji aplikacji zaleca użycie identyfikatora URI api://{clientId}zasobu . Ten identyfikator URI jest unikatowy, ale nie czytelny dla człowieka. Jeśli zmienisz identyfikator URI, upewnij się, że nowa wartość jest unikatowa. Portal rejestracji aplikacji zapewni, że używasz skonfigurowanej domeny wydawcy.

W przypadku aplikacji klienckich zakresy są wyświetlane jako delegowane uprawnienia i role aplikacji są wyświetlane jako uprawnienia aplikacji dla internetowego interfejsu API.

Zakresy są również wyświetlane w oknie zgody przedstawionym użytkownikom aplikacji. W związku z tym podaj odpowiednie ciągi, które opisują zakres:

• Jak widzi użytkownik.
• Jak widzi administrator dzierżawy, który może udzielić zgody administratora.

Role aplikacji nie mogą być wyrażane przez użytkownika (ponieważ są one używane przez aplikację, która wywołuje internetowy interfejs API w imieniu siebie). Administrator dzierżawy musi wyrazić zgodę na aplikacje klienckie internetowego interfejsu API uwidaczniającego role aplikacji. Aby uzyskać szczegółowe informacje, zobacz Zgoda administratora.

Uwidacznij delegowane uprawnienia (zakresy)

Aby uwidocznić delegowane uprawnienia lub zakresy, wykonaj kroki opisane w temacie Konfigurowanie aplikacji w celu uwidocznienia internetowego interfejsu API.

Jeśli korzystasz z scenariusza internetowego interfejsu API opisanego w tym zestawie artykułów, użyj następujących ustawień:

• Identyfikator URI identyfikatora aplikacji: zaakceptuj proponowany identyfikator URI identyfikatora aplikacji (api://< clientId>) (jeśli zostanie wyświetlony monit)
• Nazwa zakresu: access_as_user
• Kto może wyrazić zgodę: Administratorzy i użytkownicy
• Nazwa wyświetlana zgody administratora: Dostęp do usługi TodoListService jako użytkownik
• Opis zgody administratora: uzyskuje dostęp do internetowego interfejsu API TodoListService jako użytkownik
• Nazwa wyświetlana zgody użytkownika: Dostęp do aplikacji TodoListService jako użytkownik
• Opis zgody użytkownika: uzyskuje dostęp do internetowego interfejsu API todoListService jako użytkownik
• Stan: Włączone

Napiwek

W przypadku identyfikatora URI identyfikatora aplikacji możesz ustawić go na urząd fizyczny interfejsu API, na przykład https://graph.microsoft.com. Może to być przydatne, jeśli jest znany adres URL interfejsu API, który należy wywołać.

Jeśli internetowy interfejs API jest wywoływany przez usługę lub aplikację demona

Uwidaczniaj uprawnienia aplikacji zamiast delegowanych uprawnień, jeśli dostęp do interfejsu API powinny uzyskiwać demony, usługi lub inne aplikacje nieinterakcyjne (przez człowieka). Ponieważ aplikacje demona i typu usługi działają nienadzorowane i uwierzytelniają się przy użyciu własnej tożsamości, nie ma żadnego użytkownika, aby "delegować" swoje uprawnienia.

Uwidacznij uprawnienia aplikacji (role aplikacji)

Aby uwidocznić uprawnienia aplikacji, wykonaj kroki opisane w temacie Dodawanie ról aplikacji do aplikacji.

W okienku Tworzenie roli aplikacji w obszarze Dozwolone typy elementów członkowskich wybierz pozycję Aplikacje. Możesz też dodać rolę przy użyciu edytora manifestu aplikacji zgodnie z opisem w artykule.

Ograniczanie tokenów dostępu do określonych aplikacji klienckich

Role aplikacji to mechanizm używany przez dewelopera aplikacji do uwidaczniania uprawnień aplikacji. Kod internetowego interfejsu API powinien sprawdzać role aplikacji w tokenach dostępu odbieranych od obiektów wywołujących.

Aby dodać kolejną warstwę zabezpieczeń, administrator dzierżawy firmy Microsoft Entra może skonfigurować swoją dzierżawę, aby Platforma tożsamości Microsoft wystawiać tokeny zabezpieczające tylko aplikacjom klienckim zatwierdzonym do uzyskiwania dostępu do interfejsu API.

Aby zwiększyć bezpieczeństwo, ograniczając wystawianie tokenów tylko do aplikacji klienckich, do których przypisano role aplikacji:

1. W centrum administracyjnym firmy Microsoft Entra wybierz swoją aplikację w obszarze Aplikacje>Rejestracje aplikacji.
2. Na stronie Przegląd aplikacji w obszarze Podstawy znajdź i wybierz link Aplikacja zarządzana w katalogu lokalnym, aby przejść do strony Przegląd aplikacji dla przedsiębiorstw.
3. W obszarze Zarządzanie wybierz pozycję Właściwości.
4. Ustawić przypisanie jako wymagane? na Nie.
5. Wybierz pozycję Zapisz.

Identyfikator entra firmy Microsoft będzie teraz sprawdzać przypisania ról aplikacji klienckich, które żądają tokenów dostępu dla internetowego interfejsu API. Jeśli aplikacja kliencka nie ma przypisanych żadnych ról aplikacji, identyfikator Entra firmy Microsoft zwraca komunikat o błędzie do klienta podobny do _invalid_client: AADSTS501051: Application \<application name\> isn't assigned to a role for the \<web API\>_.

Ostrzeżenie

NIE używaj kodów błędów AADSTS ani ich ciągów komunikatów jako literałów w kodzie aplikacji. Kody błędów "AADSTS" i ciągi komunikatów o błędzie zwrócone przez identyfikator Entra firmy Microsoft nie są niezmienne i mogą zostać zmienione przez firmę Microsoft w dowolnym momencie i bez Twojej wiedzy. Jeśli podejmujesz decyzje dotyczące rozgałęziania w kodzie na podstawie wartości kodów AADSTS lub ich ciągów komunikatów, możesz zagrozić funkcjonalności i stabilności aplikacji.

Następny krok

Następny artykuł z tej serii to Konfiguracja kodu aplikacji.