Ochrona interfejsów API

  • Artykuł

Gdy jako deweloper chronisz interfejs API, koncentrujesz się na autoryzacji. Aby wywołać interfejs API zasobu, aplikacje muszą uzyskać autoryzację aplikacji. Sam zasób musi wymuszać autoryzację. W tym artykule poznasz najlepsze rozwiązania dotyczące ochrony interfejsu API za pomocą rejestracji, definiowania uprawnień i zgody oraz wymuszania dostępu w celu osiągnięcia celów zero trust .

Rejestrowanie chronionego interfejsu API

Aby chronić interfejs API przy użyciu identyfikatora Entra firmy Microsoft (Microsoft Entra ID), najpierw zarejestrujesz swój interfejs API, po czym będzie można 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żna uzyskać dostęp innej aplikacji. W centrum administracyjnym firmy Microsoft Entra deweloper tożsamości firmy Microsoft Rejestracje aplikacji to interfejsy API, które znajdują się w dzierżawie jako interfejsy API biznesowe lub usługi od dostawców SaaS, którzy mają interfejsy API chronione przez identyfikator Entra firmy Microsoft.

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

Zwykle interfejs API nie wykonuje uwierzytelniania ani bezpośrednio prosi o autoryzację. Interfejs API zweryfikuje token prezentowany przez aplikację wywołującą. Interfejsy API nie będą miały logowania interakcyjnego, więc nie trzeba rejestrować ustawień, takich jak identyfikator URI przekierowania lub typ aplikacji. Interfejsy API pobierają swoje tokeny z aplikacji wywołujących te interfejsy API, a nie przez interakcję z identyfikatorem Entra firmy Microsoft. 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. Usuniesz to uprawnienie dla większości internetowych interfejsów API. Identyfikator Entra firmy Microsoft wymaga uprawnień interfejsu API tylko wtedy, gdy interfejs API wywołuje inny interfejs API. Jeśli interfejs API nie wywołuje innego interfejsu API, usuń uprawnienie podczas rejestrowania interfejsu User.Read API.

Będziesz potrzebować unikatowego identyfikatora interfejsu API, znanego jako identyfikator URI identyfikatora aplikacji, że aplikacje klienckie, które muszą uzyskać dostęp do interfejsu API, będą prosić o pozwolenie na wywołanie interfejsu API. Identyfikator URI identyfikatora aplikacji musi być unikatowy we wszystkich dzierżawach firmy Microsoft Entra. Możesz użyć api://<clientId> (domyślna sugestia w portalu), gdzie <clientId> to identyfikator aplikacji zarejestrowanego interfejsu API.

Aby udostępnić deweloperom wywołującym interfejs API bardziej przyjazną nazwę, możesz użyć adresu interfejsu API jako identyfikatora URI identyfikatora aplikacji. Możesz na przykład użyć https://API.yourdomain.com lokalizacji, w której yourdomain.com musi być skonfigurowana domena wydawcy w dzierżawie firmy 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ć wszędzie tam, gdzie chcesz, ale dobrym rozwiązaniem jest użycie adresu HTTPS interfejsu API jako identyfikatora URI identyfikatora aplikacji.

Definiowanie uprawnień delegowanych z najniższymi uprawnieniami

Jeśli interfejs API będzie wywoływany przez aplikacje, które mają użytkowników, musisz zdefiniować 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ę osób atakujących, 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 wchodzą w wzorzec używania jednego uprawnienia, takiego jak "dostęp jako użytkownik" lub "personifikacja użytkownika" (co jest typowym wyrażeniem, chociaż technicznie niedokładne). Pojedyncze uprawnienia, takie jak te, zezwalają tylko na 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 obszarze Uprawnienia interfejsu 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 poufnymi danymi rozważ "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 dostępu "pełne" (na przykład Resource.ReadFull), które zwraca właściwości i informacje poufne.

Zawsze oceniaj uprawnienia, które żądasz, aby upewnić się, że szukasz bezwzględnie najmniej uprzywilejowanego zestawu, 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żawy mogą skonfigurować dzierżawę, aby wszystkie uprawnienia wymagały zgody administratora. Jeśli zdefiniujesz zakres jako wymagający zgody administratora, uprawnienie będzie zawsze wymagać zgody administratora.

Podczas podejmowania decyzji o wyrażaniu zgody użytkownika lub administratora masz dwa podstawowe zagadnienia:

  1. 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, może być odpowiednia zgoda użytkownika. Na przykład użytkownik może wyrazić zgodę na wybór preferowanej aplikacji na potrzeby poczty e-mail. Jeśli jednak operacje za 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.

  2. 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.

Błędy po stronie konserwatywnej i wymagają zgody administratora, jeśli masz wątpliwości. Jasno i zwięzłie opisz konsekwencje zgody w ciągach 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 semantyka uprawnień. Przeciążenie istniejących uprawnień osłabia rozumowanie, na podstawie którego klienci wcześniej udzielali zgody.

Definiowanie uprawnień aplikacji

Podczas tworzenia aplikacji innych niż użytkownicy nie masz użytkownika, którego nie możesz wyświetlić monitu o podanie nazwy użytkownika i hasła lub uwierzytelniania wieloskładnikowego (MFA). Jeśli interfejs API będzie wywoływany przez aplikacje bez użytkowników (takich jak obciążenia, usługi i demony), musisz zdefiniować uprawnienia aplikacji dla interfejsu API. Podczas definiowania uprawnień aplikacji użyjesz roli aplikacji zamiast używać zakresów.

Podobnie jak w przypadku uprawnień delegowanych, zapewnisz 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.

Obciążenia uwierzytelniają się przy użyciu poświadczeń klienta i żądają tokenu.defaultprzy użyciu zakresu, 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 aplikację udostępniają jako tokeny elementu nośnego w nagłówku autoryzacji żądania HTTPS. Dostęp można wymusić, sprawdzając tokeny, zarządzając odświeżaniem metadanych i wymuszając zakresy i role, zgodnie z opisem w poniższych sekcjach.

Weryfikowanie tokenów

Po odebraniu tokenu przez interfejs API musi on zweryfikować token. Walidacja gwarantuje, że token pochodzi z odpowiedniego wystawcy jako niezmodyfikowany i niezmodyfikowany. Sprawdź podpis, ponieważ token nie jest pobierany bezpośrednio z identyfikatora Entra firmy Microsoft, tak jak w przypadku tokenów identyfikatorów. Zweryfikuj podpis po odebraniu tokenu 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 lub Passport, jeśli tworzysz węzeł), należy wykonać odpowiednie kroki i wyeliminować 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 uzyskać token. azp Użyj oświadczeń iappid, aby filtrować aplikacje, które mogą wywoływać interfejs 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 od czasu do czasu trudne do zaktualizowania tych publicznych kluczy 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. Interfejs API może być w trybie offline przez dzień, gdy czeka 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 interfejs API sprawdzi oświadczenia w tokenie, aby określić, jak powinien działać.

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

Następnie sprawdź interfejs API, aby upewnić się, że użytkownik ma również dostęp do żądanej operacji. Jeśli interfejs API ma zdefiniowane role do przypisywania do użytkowników i grup, sprawdź, czy interfejs API nie zawiera oświadczeń ról w tokenie i zachowuje się odpowiednio. W przypadku tokenów uprawnień aplikacji nie będzie oświadczenia zakresu (scp). Zamiast tego interfejs API określ, jakie uprawnienia aplikacji otrzymał obciążenie, sprawdzając oświadczenie ról.

Po zweryfikowaniu tokenu i zakresów przez interfejs API oraz przetworzeniu identyfikatora obiektu (), klucza podmiotu (oidsub) i oświadczeń ról interfejs API może zwrócić wyniki.

Następne kroki