Skip to main content
Dane uwierzytelniające klienta OAuth należy stosować, gdy integracja backendowa wymaga krótkotrwałych tokenów dostępu lub gdy wymaga tego polityka bezpieczeństwa. Każdy klient należy do jednego konta usługi i jednej organizacji. OAuth jest opcjonalny: klucz API o ograniczonym zakresie uprawnień wystarczy w przypadku prywatnej integracji serwerowej, która potrafi bezpiecznie przechowywać klucz i go rotować. Informacje o wyborze między tymi dwiema metodami oraz o roli kont usług znajdziesz w artykule Uwierzytelnianie.
Dostęp do OAuth musi być włączony dla Państwa organizacji. W ramach konfiguracji otrzymają Państwo regionalny punkt końcowy tokenów, wystawcę, odbiorców oraz metodę uwierzytelniania klienta. Jeśli potrzebują Państwo tych ustawień lub nie mają dostępu do zarządzania klientami, prosimy o kontakt z pomocą techniczną Living Security.
Przyznanie typu client credentials reprezentuje Państwa konto usługi. Nie loguje ono żadnej osoby ani nie prosi klienta o autoryzację aplikacji. Autoryzacja delegowana przez przeglądarkę to odrębna funkcja OAuth i nie jest oferowana przez te operacje.

Zanim zaczniesz

  • Utwórz konto usługi wyłącznie z uprawnieniami potrzebnymi integracji.
  • Użyj poświadczenia zarządzania z service_account:manage oraz każdym uprawnieniem, które chcesz przyznać nowemu klientowi. Konto docelowe musi również posiadać te uprawnienia. Klient nie może rozszerzyć uprawnień żadnego z tych kont.
  • Wybierz region organizacji. Dane uwierzytelniające API i tokeny dostępu OAuth należą do odpowiadającego im regionalnego hosta API.
  • Przechowuj sekret klienta i tokeny w serwerowym magazynie sekretów. Nigdy nie umieszczaj ich w kodzie przeglądarki, aplikacjach mobilnych, systemie kontroli wersji ani dziennikach żądań.

Tworzenie klienta

POST /v1/oauth_clients wymaga service_account_id, niepustej listy jawnych scopes oraz Idempotency-Key. Symbole wieloznaczne nie są akceptowane. Klient obsługuje do 100 zakresów o łącznej długości co najwyżej 4096 znaków. Każde konto usługi może mieć co najwyżej 20 klientów lub nierozstrzygniętych operacji tworzenia/czyszczenia. Unieważnienie natychmiast odbiera dostęp do API. Klient lub niepewne utworzenie po stronie dostawcy nadal wlicza się do limitu, dopóki nie zostanie potwierdzone zdalne czyszczenie. Porzucona rezerwacja lub operacja tworzenia, co do której udowodniono, że zakończyła się niepowodzeniem, zanim rozpoczęły się działania po stronie dostawcy, może bezpiecznie zwolnić swoje miejsce. Jej klucz ponowienia nadal należy do pierwotnej próby; odzyskaj to potwierdzenie, zanim zdecydujesz, czy utworzyć zastępnika. Wybierz jeden klucz ponowienia dla tej próby utworzenia i zapisz go trwale przed wysłaniem żądania. Użyj od 1 do 255 widocznych znaków ASCII, bez spacji. Użyj go ponownie z tym samym kontem, zakresami, podmiotem zarządzającym, regionem i wersją API po utracie odpowiedzi. Rotacja poświadczenia zarządzania w ramach tego samego konta usługi nie tworzy nowej tożsamości ponowienia. Zainstaluj pakiet requests dla Pythona. Wczytaj poniższe wartości środowiskowe za pomocą standardowego zarządzania sekretami i konfiguracją:
Python
Przykład wysyła jedno żądanie i przechowuje wynik w pamięci. Przed uruchomieniem w środowisku produkcyjnym dodaj w oznaczonym miejscu operację zapisu do swojego menedżera sekretów. Przykład celowo wymaga podjęcia decyzji po niepewnym wyniku, zamiast po cichu tworzyć kolejnego klienta. Wyjątki sieciowe również wymagają wykonania poniższych kroków odzyskiwania. Odpowiedzi na utworzenie i potwierdzenia używają 201 i zawierają zasób oauth_client z polami id, service_account_id, client_id, scopes, status, created_at i client_secret. Odpowiedzi są oznaczone jako Cache-Control: no-store.
  • id identyfikuje zasób platformy. Zapisz go na potrzeby pobierania i unieważniania.
  • client_id identyfikuje klienta podczas wymiany tokenów. Nie jest to identyfikator zasobu platformy. Może mieć wartość null, gdy tworzenie jest w toku.
  • client_secret jest zwracany tylko w odpowiedzi na żądanie, które kończy tworzenie. Każde powtórzone żądanie utworzenia zwraca null, także ponowienie po utraconej odpowiedzi o powodzeniu. Pobieranie nigdy nie zwraca sekretu.

Odzyskiwanie po utraconej lub przerwanej odpowiedzi

Powtórz to samo żądanie utworzenia z zapisanym kluczem ponowienia, aby odzyskać potwierdzenie zasobu. Potwierdzenie odzwierciedla bieżący stan, więc unieważniony klient pozostaje unieważniony. Ta operacja nie korzysta z ogólnego mechanizmu ponownego odtwarzania odpowiedzi z pamięci podręcznej przez 24 godziny i nie zwraca nagłówka Idempotent-Replayed. Informacje o identyfikatorach żądań i szczegóły odzyskiwania znajdziesz w sekcji błędy. Nigdy nie przesyłaj sekretu klienta ani tokenu dostępu w zgłoszeniu do pomocy technicznej.

Sprawdzanie i unieważnianie

Użyj swojego poświadczenia zarządzania i id zasobu platformy: Unieważnienie blokuje kolejne żądania API klienta, w tym żądania z użyciem już wydanych tokenów. Nie anuluje pracy już zaakceptowanej przez API. Zdalne czyszczenie poświadczeń może zakończyć się później. Powtórzenie unieważnienia jest bezpieczne i nie wymaga klucza ponowienia. Jeśli unieważniany klient sam jest wywołującym API, nadal używaj poświadczenia zarządzania.

Rotacja bez utraty dostępu

Utwórz drugiego klienta z wymaganym maksymalnym zakresem uprawnień. Zapisz jego sekret, uzyskaj token za pomocą swojego regionalnego punktu końcowego tokenów i sprawdź, czy integracja działa z tym tokenem. Przełącz integrację na klienta zastępczego, a następnie unieważnij stary zasób. Zachowaj niezależne poświadczenie zarządzania, aby móc odzyskać dostęp po nieudanym wdrożeniu. Tokeny dostępu nie mogą przyznawać więcej uprawnień niż zakresy klienta i bieżące uprawnienia konta usługi. Usunięcie uprawnień konta lub unieważnienie klienta ma pierwszeństwo przed pozostałym czasem ważności tokenu. Nie traktuj tokenu z pamięci podręcznej jako dowodu, że autoryzacja nadal jest ważna. Uzyskaj nowy token dostępu przed wygaśnięciem, ponownie uwierzytelniając klienta; to przyznanie nie korzysta z tokenów odświeżania.