Udostępnij za pośrednictwem

Ochrona interfejsu API

Gdy jako deweloper chronisz interfejs API, koncentrujesz się na autoryzacji. Aby wywołać interfejs API zasobu, aplikacje muszą uzyskać autoryzację aplikacji. Zasób wymusza autoryzację. W tym artykule poznasz najlepsze praktyki, aby osiągnąć swoje cele Zero Trust. Opisano w nim sposób ochrony interfejsu API za pomocą rejestracji, uprawnień i definicji zgody oraz wymuszania dostępu.

Zarejestruj chroniony interfejs API

Aby chronić interfejs API przy użyciu identyfikatora Entra firmy Microsoft (Microsoft Entra ID), zarejestruj swój interfejs API. Następnie możesz zarządzać zarejestrowanymi interfejsami API. W usłudze Microsoft Entra ID interfejs API to aplikacja z określonymi ustawieniami rejestracji aplikacji, które definiują je jako zasób lub interfejs API, do którego może uzyskiwać dostęp inna aplikacja. W centrum administracyjnym Microsoft Entra, Microsoft Identity Developer, rejestracje aplikacji to API, które znajdują się w dzierżawie jako interfejsy API dla linii biznesowej lub usługi od dostawców oprogramowania jako usługi (SaaS), które mają API chronione przez Microsoft Entra ID.

Podczas rejestracji definiujesz sposób, w jaki aplikacje wywołujące odwołują się do twojego interfejsu API oraz jego uprawnień delegowanych i aplikacyjnych. Rejestracja aplikacji może reprezentować rozwiązanie, które ma zarówno aplikacje klienckie, jak i interfejsy API. Jednak w tym artykule omówimy scenariusz, w którym zasób autonomiczny uwidacznia interfejs API.

Zwykle interfejs API nie wykonuje uwierzytelniania ani bezpośrednio prosi o autoryzację. API weryfikuje token, który przedstawia aplikacja wywołująca. Interfejsy API nie mają logowania interakcyjnego, więc nie trzeba rejestrować ustawień, takich jak identyfikator URI przekierowania lub typ aplikacji. Interfejsy API pobierają swoje tokeny z aplikacji, które je wywołują, a nie przez interakcję z Microsoft Entra ID. W przypadku internetowych interfejsów API użyj tokenów dostępu OAuth2 do autoryzacji. Internetowe interfejsy API weryfikują tokeny elementu nośnego do autoryzowania wywołujących. Nie akceptuj tokenów identyfikatorów jako dowodu uprawnień.

Domyślnie identyfikator Entra firmy Microsoft dodaje User.Read do uprawnień interfejsu API każdej nowej rejestracji aplikacji. Usuwasz to uprawnienie dla większości webowych interfejsów API. Usługa Microsoft Entra ID wymaga uprawnień API tylko wtedy, gdy jedno API wywołuje inne. Jeśli Twoje API nie wywołuje innego API, usuń uprawnienie User.Read podczas rejestrowania API.

Potrzebujesz unikatowego identyfikatora dla swojego interfejsu API, znanego jako identyfikator URI aplikacji, aby aplikacje klienckie, które muszą uzyskać dostęp do twojego interfejsu API, mogły prosić o pozwolenie na jego wywołanie. Identyfikator URI aplikacji musi być unikatowy we wszystkich dzierżawach Microsoft Entra. Możesz użyć api://<clientId> (sugestii domyślnej w portalu), gdzie <clientId> jest identyfikatorem aplikacji zarejestrowanego interfejsu API.

Aby udostępnić deweloperom wywołującym Twój interfejs API bardziej przyjazną nazwę, możesz użyć adresu tego interfejsu API jako URI identyfikatora aplikacji. Możesz na przykład użyć https://API.yourdomain.com, gdy yourdomain.com jest skonfigurowaną domeną wydawcy w dzierżawie Microsoft Entra. Firma Microsoft sprawdza, czy masz własność domeny, aby można było jej użyć jako unikatowego identyfikatora interfejsu API. Nie musisz mieć kodu pod tym adresem. Interfejs API może być umieszczony wszędzie tam, gdzie chcesz, ale dobrą praktyką jest użycie https adresu interfejsu API jako URI Identyfikatora aplikacji.

Definiowanie uprawnień delegowanych z najniższymi uprawnieniami

Jeśli aplikacje z użytkownikami będą wywoływać interfejs API, zdefiniuj co najmniej jedno delegowane uprawnienie (zobacz Dodawanie zakresu w rejestracji aplikacji Uwidacznianie interfejsu API).

Interfejsy API, które zapewniają dostęp do magazynów danych organizacji, mogą przyciągnąć uwagę złych podmiotów, którzy chcą uzyskać dostęp do tych danych. Zamiast mieć tylko jedno delegowane uprawnienie, zaprojektuj swoje uprawnienia z myślą o zasadzie zero zaufania dostępu do najniższych uprawnień . Jeśli wszystkie aplikacje klienckie zaczynają korzystać z pełnego uprzywilejowanego dostępu, może być trudno później przejść do modelu o najniższych uprawnieniach.

Często deweloperzy popadają w schemat używania pojedynczego uprawnienia, takiego jak dostęp jako użytkownik lub personifikacja użytkownika (co jest często technicznie niedokładną frazą). Pojedyncze uprawnienia, takie jak te, umożliwiają tylko pełny uprzywilejowany dostęp do interfejsu API.

Zadeklaruj zakresy najniższych uprawnień, aby aplikacje nie były narażone na naruszenie zabezpieczeń lub były używane do wykonywania zadania, którego nigdy nie zamierzasz wykonać. Zdefiniuj wiele zakresów w Uprawnieniach API. Na przykład odseparuj zakresy od odczytywania i aktualizowania danych i rozważ oferowanie uprawnień tylko do odczytu. Dostęp do zapisu obejmuje uprawnienia do operacji tworzenia, aktualizowania i usuwania. Klient nigdy nie powinien wymagać dostępu do zapisu tylko do odczytu danych.

Podczas pracy interfejsu API z danymi poufnymi należy wziąć pod uwagę standardowe i pełne uprawnienia dostępu. Ogranicz właściwości poufne, aby standardowe uprawnienie nie zezwalało na dostęp (na przykład Resource.Read). Następnie zaimplementuj uprawnienie pełnego dostępu (na przykład Resource.ReadFull), które zwraca właściwości i informacje poufne.

Zawsze oceniaj uprawnienia, o które prosisz, aby upewnić się, że prosisz o absolutnie najmniej uprzywilejowany zestaw, aby wykonać zadanie. Unikaj żądania wyższych uprawnień. Zamiast tego utwórz indywidualne uprawnienia dla każdego podstawowego scenariusza. Zapoznaj się z dokumentacją dotyczącą uprawnień programu Microsoft Graph , aby zapoznać się z dobrymi przykładami tego podejścia. Zlokalizuj i użyj odpowiedniej liczby uprawnień, aby spełnić Twoje potrzeby.

W ramach definicji zakresu zdecyduj, czy zakres operacji, które można wykonać z określonym zakresem , wymaga zgody administratora.

Jako projektant interfejsu API możesz podać wskazówki dotyczące zakresów, które mogą bezpiecznie wymagać tylko zgody użytkownika. Jednak administratorzy dzierżawcy mogą skonfigurować dzierżawcę tak, aby wszystkie uprawnienia wymagały zgody administratora. Jeśli zdefiniujesz zakres jako wymagający zgody administratora, uprawnienie zawsze wymaga zgody administratora.

Jeśli zdecydujesz się na zgodę użytkownika lub administratora, masz następujące podstawowe zagadnienia:

  • Czy zakres operacji związanych z uprawnieniem ma wpływ na więcej niż jednego użytkownika. Jeśli uprawnienie pozwala użytkownikowi wybrać, która aplikacja może uzyskiwać dostęp tylko do własnych informacji, zgoda użytkownika może być odpowiednia. Na przykład użytkownik może wyrazić zgodę na wybór preferowanej aplikacji na potrzeby poczty e-mail. Jeśli jednak operacje związane z uprawnieniem obejmują więcej niż jednego użytkownika (na przykład wyświetlanie pełnych profilów użytkowników innych użytkowników), zdefiniuj to uprawnienie jako wymagające zgody administratora.

  • Czy zakres operacji związanych z uprawnieniem ma szeroki zakres. Na przykład szeroki zakres polega na tym, że uprawnienie umożliwia aplikacji zmianę wszystkiego w dzierżawie lub wykonanie czegoś, co może być nieodwracalne. Szeroki zakres wskazuje, że potrzebujesz zgody administratora, a nie zgody użytkownika.

Zawsze wybieraj opcje konserwatywne i wymagaj zgody administratora, jeśli masz jakieś wątpliwości. Jasno i zwięźle opisz konsekwencje zgody w łańcuchach uprawnień. Załóżmy, że osoba czytająca ciągi opisu nie ma znajomości interfejsów API ani produktu.

Unikaj dodawania interfejsów API do istniejących uprawnień w sposób, który zmienia semantykę uprawnienia. Przeciążenie istniejących uprawnień osłabia rozumowanie, na podstawie którego klienci wcześniej udzielali zgody.

Definiowanie uprawnień aplikacji

Podczas tworzenia aplikacji dla systemu, w których nie ma użytkownika, nie możesz wyświetlić monitu o podanie nazwy użytkownika i hasła ani uwierzytelniania wieloskładnikowego (MFA). Jeśli aplikacje bez użytkowników (takie jak zadania robocze, usługi, i demony) wywołują API, zdefiniuj uprawnienia aplikacji dla API. Podczas definiowania uprawnień aplikacji należy użyć roli aplikacji zamiast używać zakresów.

Podobnie jak w przypadku uprawnień delegowanych, należy podać szczegółowe uprawnienia aplikacji, aby obciążenia wywołujące interfejs API mogły przestrzegać najniższych uprawnień dostępu i dostosować je do zasad zero trust. Unikaj publikowania tylko jednej roli aplikacji (uprawnienia aplikacji) i jednego zakresu (uprawnienia delegowane) lub uwidaczniania wszystkich operacji dla każdego klienta.

Aplikacje uwierzytelniają się za pomocą poświadczeń klienta i żądają tokenu z zakresem .default, jak pokazano w poniższym przykładowym kodzie.

// With client credentials flows the scopes is ALWAYS of the shape "resource/.default", as the 
// application permissions need to be set statically (in the portal or by PowerShell), 
// and then granted by a tenant administrator
string[] scopes = new string[] { "https://kkaad.onmicrosoft.com/webapi/.default" };
 
AuthenticationResult result = null;
try
{
  result = await app.AcquireTokenForClient(scopes)
    .ExecuteAsync();
  Console.WriteLine("Token acquired \n");
}
catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
{
  // Invalid scope. The scope has to be of the form "https://resourceurl/.default"
  // Mitigation: change the scope to be as expected
  Console.WriteLine("Scope provided is not supported");
}

Uprawnienia wymagają zgody administratora, jeśli nie ma użytkownika przed aplikacją i gdy uprawnienie aplikacji umożliwia szeroką gamę operacji.

Wymuszanie dostępu

Upewnij się, że interfejsy API wymuszają dostęp, sprawdzając i interpretując tokeny dostępu, które wywołujące aplikacje udostępniają jako tokeny elementu nośnego w https nagłówku autoryzacji żądania. Wymuszanie dostępu przez weryfikowanie tokenów, zarządzanie odświeżaniem metadanych oraz wymuszanie zakresów i ról zgodnie z opisem w poniższych sekcjach.

Weryfikowanie tokenów

Po odebraniu tokenu przez interfejs API upewnij się, że weryfikuje token. Walidacja gwarantuje, że token pochodzi z odpowiedniego wystawcy jako nienaruszony i niezmodyfikowany. Sprawdź podpis, ponieważ token nie jest uzyskiwany bezpośrednio z Microsoft Entra ID, tak jak to się dzieje w przypadku tokenów tożsamości. Zweryfikuj podpis po tym, jak Twoje API otrzyma token z niezaufanego źródła w sieci.

Ponieważ istnieją znane luki w zabezpieczeniach dotyczące weryfikacji sygnatury tokenu internetowego w formacie JSON, należy użyć dobrze utrzymywanej i ustalonej standardowej biblioteki weryfikacji tokenów. Biblioteki uwierzytelniania (takie jak Microsoft.Identity.Web) korzystają z odpowiednich kroków i ograniczają znane luki w zabezpieczeniach.

Opcjonalnie rozszerz weryfikację tokenu. Użyj oświadczenia identyfikatora dzierżawy (tid), aby ograniczyć dzierżawy, w których interfejs API może pobrać token. Użyj azp i appid żądań, aby filtrować aplikacje, które mogą wywoływać twoje API. Użyj oświadczenia o identyfikatorze obiektu (oid), aby dokładniej zawęzić dostęp do poszczególnych użytkowników.

Zarządzanie odświeżaniem metadanych

Zawsze upewnij się, że biblioteka weryfikacji tokenu skutecznie zarządza wymaganymi metadanymi. W takim przypadku metadane są kluczami publicznymi, parą kluczy prywatnych, których firma Microsoft używa do podpisywania tokenów firmy Microsoft Entra. Gdy biblioteki zweryfikują te tokeny, otrzymają opublikowaną listę publicznych kluczy podpisywania z dobrze znanego adresu internetowego. Upewnij się, że środowisko hostingu ma odpowiedni czas, aby pobrać te klucze.

Na przykład starsze biblioteki były czasami zakodowane na sztywno, aby aktualizować te publiczne klucze podpisywania co 24 godziny. Rozważ, gdy identyfikator Entra firmy Microsoft musi szybko obrócić te klucze i pobrane klucze nie zawierały nowych obróconych kluczy. Twój interfejs API może być niedostępny przez jeden dzień, czekając na cykl odświeżania metadanych. Zapoznaj się z konkretnymi wskazówkami dotyczącymi odświeżania metadanych , aby upewnić się, że metadane są prawidłowo uzyskiwane. Jeśli używasz biblioteki, upewnij się, że traktuje te metadane w rozsądnym czasie.

Wymuszanie zakresów i ról

Po zweryfikowaniu tokenu Twój interfejs API analizuje jego oświadczenia, aby określić, jak powinien funkcjonować.

W przypadku tokenów uprawnień delegowanych należy sprawdzić zakres (scp) oświadczenia interfejsu API, aby zobaczyć, co aplikacja ma zgodę na wykonywanie. Sprawdź ID obiektu (oid) lub oświadczenia klucza podmiotu (sub), aby zobaczyć użytkownika, w którego imieniu aplikacja reprezentuje.

Następnie sprawdź interfejs API, aby upewnić się, że użytkownik ma również dostęp do żądanej operacji. Jeśli interfejs API definiuje role do przypisywania do użytkowników i grup, upewnij się, że interfejs API sprawdza oświadczenia ról w tokenie i zachowuje się odpowiednio. Tokeny uprawnień aplikacji nie mają oświadczenia zakresu (scp). Zamiast tego należy sprawdzić oświadczenie ról w interfejsie API, aby określić, które uprawnienia aplikacji otrzymało obciążenie.

Gdy interfejs API zweryfikuje token i zakresy oraz przetworzy identyfikator obiektu (oid), klucz podmiotu (sub) i oświadczenia ról, interfejs API może zwrócić wyniki.

Następne kroki

  • Last updated on