Skip to Content

APIs

Ochrona APIs jako zasobów OAuth: definiowanie scopes, kontrola dostępu machine-to-machine i użytkowników, format i czas życia tokenów.

API reprezentuje chroniony zasób, do którego aplikacje uzyskują access tokens. Rejestracja API przekazuje platformie identyfikator zasobu (jego audience), udostępniane przez niego scopes (uprawnienia), aplikacje, które mogą go wywoływać, oraz sposób kształtowania i podpisywania wydawanych dla niego access tokens.

APIs zarządza się w Admin Console w Integracje → API.

Czym jest API

Każde API ma:

  • nazwę: etykietę dla administratorów, oraz
  • identyfikator: wartość audience pojawiającą się w tokenach wydawanych dla tego API (na przykład https://api.example.com).

W przypadku własnego API można też wskazać Kontakty, czyli pracowników, do których należy kierować pytania na jego temat. Mają one charakter wyłącznie informacyjny i nie otrzymują żadnych uprawnień.

Istnieją dwa rodzaje:

  • System API: własne API zarządzania platformy. Jego nazwa, identyfikator i scopes są stałe i nie można ich edytować.
  • Custom API: API rejestrowane i zarządzane samodzielnie: definiuje się jego scopes, kto może je wywoływać, oraz ustawienia tokenów.

Scopes (uprawnienia)

Scope to pojedyncze uprawnienie, które może zawierać token, na przykład read:documents lub orders.write.

  • System API udostępnia stały katalog scopes zarządzania (na przykład users.read, users.write, groups.read, roles.write, logs.read). Te scopes nadaje się aplikacjom wywołującym własne API zarządzania platformy.
  • Custom API udostępnia scopes zdefiniowane przez administratora. Na karcie uprawnień API należy dodać każdy scope z nazwą i opisem. Kilku zarezerwowanych scopes OpenID Connect (takich jak openid, profile, email, offline_access) nie można zdefiniować ponownie.

Niektóre scopes zarządzania celowo występują obok swojego scope bazowego, zamiast być przez niego obejmowane. Najważniejszy z nich to users.mfa.read, obejmujący rejestracje MFA użytkownika (które drugie składniki są zarejestrowane i kiedy każdy był ostatnio użyty). Jest on wymagany na każdym endpoincie zwracającym użytkownika, w tym w odpowiedziach na utworzenie, aktualizację, usunięcie oraz wywołania dezaktywacji i aktywacji. Token zawierający tylko users.read lub users.write otrzymuje użytkownika bez listy rejestracji, dlatego tam, gdzie integracja jej potrzebuje, należy dodatkowo nadać users.mfa.read.

Kto może wywoływać API

Dostęp kontrolują dwie niezależne polityki, po jednej dla każdego rodzaju wywołującego:

Dostęp delegowany przez użytkownika

Gdy interaktywna aplikacja żąda tokenu w imieniu zalogowanego użytkownika, o tym, czy jest to dozwolone, decyduje user policy API:

  • Allow all: każda interaktywna aplikacja może żądać tokenów dla tego API.
  • Require grant: tokenów mogą żądać tylko aplikacje, którym jawnie nadano uprawnienie, i tylko dla nadanych im scopes.
  • Deny all: żadna interaktywna aplikacja nie może żądać tokenów.

Dostęp machine-to-machine

Gdy aplikacja uwierzytelnia się we własnym imieniu za pomocą grantu client credentials (bez udziału użytkownika), o tym, czy jest to dozwolone, decyduje client policy API:

  • Require grant: tokenów mogą żądać tylko aplikacje, którym jawnie nadano uprawnienie, w granicach nadanych scopes.
  • Deny all: żadna aplikacja machine-to-machine nie może żądać tokenów.

Nadawanie uprawnień aplikacji

Jeśli polityka ma wartość require grant, aplikację autoryzuje się na karcie Dostęp do aplikacji API:

  1. Wybrać Dodaj aplikację w sekcji dostępu delegowanego przez użytkownika lub w sekcji klienta (machine-to-machine).
  2. Wybrać aplikację.
  3. Wybrać scopes do nadania albo opcję grant all permissions, aby automatycznie objąć bieżące i przyszłe scopes.
  4. Zapisać. Tokeny wydawane przez platformę tej aplikacji dla tego API zawierają odtąd nadane scopes.

Aplikacja machine-to-machine ma zwykle typ aplikacji machine-to-machine, zobacz Aplikacje.

Lista API w Admin Console

Testowanie tokenu API

Gdy dla API autoryzowano co najmniej jedną aplikację machine-to-machine (z grantem client credentials), karta Test API pozwala wypróbować token od początku do końca bez pisania kodu:

  1. Wybrać jedną z autoryzowanych aplikacji machine-to-machine.
  2. Strona pokazuje gotowe do uruchomienia przykładowe żądanie tokenu do endpointu tokenów, z client ID i sekretem tej aplikacji oraz identyfikatorem tego API jako audience.
  3. Pokazuje odpowiedź tokenu i dekoduje wydany access token na nagłówek, payload i podpis, aby można było potwierdzić, że audience i nadane scopes są zgodne z oczekiwaniami.
  4. Pokazuje przykładowe wywołanie API, które wysyła token jako nagłówek Bearer.

Polecenia można skopiować i uruchomić we własnym terminalu. Jeśli karta Test informuje, że najpierw trzeba autoryzować aplikację, należy nadać uprawnienie aplikacji machine-to-machine na karcie Dostęp do aplikacji i odświeżyć stronę.

Resource indicators i tokeny

Każdy access token wydawany przez platformę dla API zawiera identyfikator tego API jako audience, dzięki czemu zasób może zweryfikować, że token był przeznaczony dla niego. Aplikacje wybierają API, dla którego chcą otrzymać token, za pomocą resource indicator, co pozwala jednej aplikacji przechowywać oddzielne tokeny z własnym audience dla kilku APIs.

Na karcie ustawień API określa się kształt tych tokenów:

  • Algorytm podpisywania: algorytm asymetryczny (RS256, RS384, RS512 lub PS256) używany do podpisywania tokenów. Dla API wywoływanego przez aplikację z profilem bezpieczeństwa Financial-grade API należy wybrać PS256: ten profil podpisuje własne tokeny aplikacji algorytmem PS256 i odradza RS256. To ustawienie jest niezależne od profilu, więc trzeba je zmienić także tutaj.
  • Access token lifetime: jak długo token jest ważny (domyślnie jeden dzień).
  • Implicit access token lifetime: krótszy czas życia stosowany do tokenów wydawanych w przeglądarkowych przepływach implicit (domyślnie dwie godziny).

Jedno API czy wiele?

Access token zawsze ma dokładnie jedno audience. Tokeny z wieloma audience nie są wydawane: token wydany dla jednego API nie jest akceptowany przez inne (zobacz API jako weryfikowalny kontrakt). Jeśli backend składa się z zestawu mikroserwisów, wymaga to decyzji projektowej:

Jedno logiczne API dla jednej domeny zaufania. Należy zarejestrować jedno API, którego identyfikator reprezentuje cały backend (na przykład https://api.example.com), i nadać każdemu serwisowi własną przestrzeń nazw scopes (orders.read, inventory.write i tak dalej). Każdy serwis weryfikuje to samo audience i egzekwuje tylko własne scopes; klient przechowuje jeden token dla całego backendu, a nowy serwis dołącza przez dodanie scopes zamiast nowej rejestracji. To rozwiązanie sprawdza się, gdy serwisy są tworzone i obsługiwane wspólnie, zwykle za jednym gatewayem. Należy pamiętać o kompromisie: w ramach wspólnego audience serwisy nie izolują się już nawzajem przez kontrolę audience (każdy z nich zaakceptuje token wysłany do serwisu siostrzanego), a jedynie przez scopes.

Jedno API na granicę zaufania. Oddzielne APIs należy rejestrować, gdy zasoby mają różne poziomy zaufania lub różnych właścicieli albo gdy zaangażowane są podmioty trzecie. Klient żąda wtedy osobnego tokenu dla każdego API przez resource indicator (zobacz Resource indicators i tokeny), a serwis backendowy może wymienić posiadany już token przez Token Exchange. Na granicy kontrola audience zachowuje znaczenie: token przechwycony w jednym API jest bezwartościowy w drugim.

Często łączy się oba podejścia: jedno logiczne API dla spójnego rdzenia i oddzielne APIs dla części wymagających silniejszej izolacji.

Jak daleko przekazywać token użytkownika. Access token użytkownika należy traktować jako dane uwierzytelniające, a nie kontekst żądania. Należy przekazywać go najwyżej o jeden przeskok, od klienta do krawędzi API (gatewaya lub pierwszego serwisu). Serwisy położone głębiej w łańcuchu wywołań powinny albo znajdować się za wspólnym audience logicznego API, albo otrzymywać węższy token wydany przez Token Exchange; każdy dodatkowy przeskok oryginalnego tokenu poszerza obszar, w którym wyciekły token może zostać ponownie użyty.

Token Exchange

Endpoint tokenów obsługuje OAuth 2.0 Token Exchange (RFC 8693), dzięki czemu serwis może wywołać API niższego poziomu w imieniu zalogowanego użytkownika bez przekazywania oryginalnego tokenu: aplikacja wymienia posiadany już access token użytkownika na nowy, węższy token przeznaczony dla innego API.

Grant jest celowo ograniczony do zawężania zakresu (downscoping):

  • Może go używać tylko aplikacja typu web (confidential) i tylko wtedy, gdy wśród jej typów grantów włączono Token Exchange (zobacz Aplikacje).
  • Token podmiotu musi być nadal ważnym access tokenem użytkownika wydanym tej samej aplikacji, która wykonuje wymianę. Wymiana tokenów innej aplikacji, tokenów bez użytkownika oraz delegacja z actor_token nie są obsługiwane.
  • Żądanie wskazuje przez resource dokładnie jedno docelowe API. Polityka dostępu delegowanego przez użytkownika docelowego API dotyczy wymieniającej aplikacji tak jak przy każdym innym żądaniu tokenu.
  • Wydany token nigdy nie jest szerszy niż token podmiotu: jego scopes są częścią wspólną żądanych scopes, scopes tokenu podmiotu, scopes docelowego API i tego, do czego użytkownik jest uprawniony.
  • Nowy token pozostaje powiązany z tym samym użytkownikiem i sesją i podlega ustawieniom czasu życia tokenów docelowego API.

Przykładowe żądanie do endpointu tokenów (aplikacja uwierzytelnia się jak zwykle, na przykład swoim client secret):

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<the user access token>
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&resource=https://inventory.example.com
&scope=inventory.read

Odpowiedź zawiera nowy access_token wraz z expires_in oraz faktycznie nadanym scope.

Scopes a uprawnienia

Zdefiniowanie scope w API sprawia jedynie, że można go zażądać; nikomu nie nadaje dostępu. O tym, co faktycznie trafia do tokenu, decyduje się oddzielnie:

  • W tokenach machine-to-machine token zawiera dokładnie te scopes, które autoryzuje client grant aplikacji (zobacz Nadawanie uprawnień aplikacji). Klient maszynowy nie ma użytkownika ani ról, więc przypisanie roli aplikacji machine-to-machine nie ma żadnego skutku; jej scopes pochodzą wyłącznie z grantu.
  • W tokenach z użytkownikiem (wydawanych, gdy interaktywna aplikacja żąda tokenu w imieniu zalogowanego użytkownika) o tym, do których scopes użytkownik jest uprawniony, decyduje kontrola dostępu oparta na rolach. Scopes, które ostatecznie trafiają do tokenu, są częścią wspólną tego, czego zażądała aplikacja, i tego, do czego uprawniony jest użytkownik.

To typowa odpowiedź na pytanie „dlaczego żądany scope bez żadnego komunikatu nie pojawił się w tokenie?": scope został zażądany, ale wywołujący nie był do niego uprawniony, więc został pominięty, a nie odrzucony.

Obrona w głąb: scope obecny w tokenie jest nadaniem, a nie gwarancją. API powinno nadal egzekwować własne kontrole na poziomie obiektów (czy ten użytkownik jest właścicielem tego rekordu?); ważny token z szerokim scope nie zastępuje autoryzacji na samym zasobie.

Kontrola dostępu oparta na rolach

Uwaga dotycząca planu: Kontrola dostępu oparta na rolach jest dostępna od planu Advanced (oraz w wersji Trial).

Custom API może włączyć RBAC, dzięki czemu platforma osadza role i uprawnienia użytkownika bezpośrednio w tokenach wydawanych dla tego API. Na karcie ustawień API:

  • Dołącz role i uprawnienia (RBAC) włącza tę funkcję dla API.
  • Dołącz claim permissions dodaje nadane użytkownikowi scopes dla tego API jako claim permissions.
  • Dołącz claim roles dodaje nazwy ról użytkownika jako claim roles.

Te claims są dodawane tylko do tokenów z użytkownikiem. Aplikacja podejmuje następnie decyzje autoryzacyjne na ich podstawie. Definiowanie ról i przypisywanie ich użytkownikom i grupom opisano w Role.

Miejscem na te decyzje jest access token. Claim roles trafia także do ID token, gdy aplikacja zażąda scope roles, ale służy on wyłącznie do prezentacji, zobacz Egzekwowanie w access token, a nie w ID token.

API jako weryfikowalny kontrakt

Zarejestrowane API jest w praktyce kontraktem między administratorem a serwerem zasobów:

  • Jego identyfikator jest stały i staje się audience każdego tokenu wydanego dla tego API.
  • Platforma podpisuje każdy token swoim kluczem podpisującym (zobacz Klucze podpisujące).
  • Serwer zasobów weryfikuje token, zanim zaufa jakiemukolwiek scope: sprawdza podpis, czy issuer to ta platforma i czy audience odpowiada jego własnemu identyfikatorowi, a dopiero potem odczytuje scopes.

Jeśli którakolwiek z tych kontroli się nie powiedzie, serwer zasobów powinien od razu odrzucić żądanie.

Wywoływanie API zarządzania (szybki start machine-to-machine)

Aby skrypt lub serwis backendowy mógł wywoływać własne API zarządzania platformy:

  1. Utworzyć aplikację machine-to-machine, zobacz Aplikacje.
  2. Na karcie dostępu do aplikacji w System API nadać tej aplikacji potrzebne scopes zarządzania (na przykład users.read, groups.write). Należy nadawać tylko scopes, których integracja faktycznie używa.
  3. Z poziomu serwisu zażądać tokenu z grantem client credentials od endpointu tokenów, używając identyfikatora System API jako audience.
  4. Wywoływać endpointy zarządzania pod /api/v1/... ze zwróconym tokenem w nagłówku Authorization: Bearer.

Karta Test w System API generuje dokładnie te dwa polecenia, wstępnie wypełnione danymi prawdziwej aplikacji; można je skopiować jako punkt wyjścia.

Token przestaje działać przed wygaśnięciem, gdy tylko aplikacja utraci dostęp w System API, jej client secret zostanie zrotowany lub aplikacja zostanie usunięta. Usługa otrzymuje wtedy HTTP 401 i musi zażądać nowego tokenu.

Limity tokenów machine-to-machine

Do tokenów wydawanych przez grant client credentials mają zastosowanie dwa limity. Oba są widoczne w przeglądzie Integracje → API. Żaden z nich nigdy nie dotyczy tokenów dla interaktywnych logowań użytkowników.

Żądania tokenów na minutę na klienta: limit przepustowości. Żądania ponad limit otrzymują odpowiedź HTTP 429 z nagłówkiem Retry-After; klient może ponowić próbę po upływie podanego w nagłówku czasu.

PlanŻądania tokenów na minutę
Trial30
Free60
Essential1200
Advanced6000
Pro30 000

Tokeny na miesiąc, dla całego tenanta: budżet wolumenu istniejący tylko w planach podstawowych. Obejmuje łącznie wszystkie aplikacje machine-to-machine i wszystkie APIs i jest resetowany pierwszego dnia każdego miesiąca. Po jego wyczerpaniu kolejne żądania client credentials otrzymują odpowiedź access_denied do początku następnego miesiąca.

PlanTokeny na miesiąc
Trial / Free1000
Essential i wyższeBez limitu

Klient, który buforuje access token przez cały czas jego życia, potrzebuje około 720 tokenów miesięcznie i pozostaje daleko poniżej obu limitów, więc zwykle osiąga je tylko klient żądający nowego tokenu przy każdym pojedynczym wywołaniu API. Token należy buforować w wywołującym serwisie i używać go ponownie do chwili tuż przed wygaśnięciem; czas życia tokenu konfiguruje się dla każdego API na jego karcie ustawień.

Dokumentacja dla deweloperów / API

Platforma udostępnia interaktywną, wbudowaną w produkt dokumentację API pod adresem /admin/api-docs. Wymienia ona każdy endpoint zarządzania wraz z parametrami i pozwala wypróbować wywołania w przeglądarce; z tej samej strony można pobrać czytelną maszynowo definicję OpenAPI.

API zarządzania obejmuje administrację użytkownikami, grupami, organizacjami, aplikacjami, rolami, logami i urządzeniami. Jako miarodajne źródło informacji o endpointach należy traktować /admin/api-docs, a nie statyczną listę w tym miejscu.

Informacje referencyjne

TerminZnaczenie
Identyfikator (audience)Wartość identyfikująca API; pojawia się w tokenach wydawanych dla niego.
Scope / uprawnieniePojedyncza możliwość, którą może zawierać token.
User policyCzy interaktywne aplikacje mogą uzyskiwać tokeny w imieniu użytkownika.
Client policyCzy aplikacje mogą uzyskiwać tokeny dla siebie (machine-to-machine).
GrantJawna autoryzacja jednej aplikacji do wywoływania tego API z określonymi scopes.
RBACOsadzanie ról i uprawnień użytkownika w tokenach API.
Token ExchangeWymiana access tokenu użytkownika na węższy token przeznaczony dla innego API (RFC 8693).

Rozwiązywanie problemów

  • Żądanie tokenu jest odrzucane z powodu nieprawidłowego scope. Aplikacja może żądać tylko scopes, które nadano jej w API. Należy dodać scope do grantu aplikacji dla tego API, a następnie zażądać nowego tokenu.
  • Wywołania zwracają błąd niewystarczającego scope, mimo że token został wydany. Żądanie kończy się powodzeniem tylko wtedy, gdy token faktycznie zawiera scope wymagany przez endpoint. Należy zdekodować token i potwierdzić, że nadane scopes go obejmują; scopes, których aplikacji nie nadano, są bez komunikatu pomijane w tokenie.
  • Token ma niewłaściwe audience. Token musi zostać zażądany dla identyfikatora (audience) tego API. Token wydany dla innego API lub bez audience nie jest tutaj akceptowany.
  • Test tokenu nic nie zwraca lub zwraca błąd. Test wydaje token dla wybranej aplikacji i scopes. Należy upewnić się, że aplikacja ma aktywny grant w tym API i że wybrano co najmniej jeden scope.
  • Token Exchange jest odrzucany. Token podmiotu musi być nadal ważnym access tokenem z użytkownikiem, wydanym tej samej aplikacji, która wykonuje wymianę; aplikacja musi mieć włączony grant token exchange, a żądanie musi wskazywać przez resource dokładnie jedno docelowe API. Tokenów machine-to-machine (bez użytkownika) nie można wymieniać.

Zobacz także słownik.

Na tej stronie