Skip to main content
Přihlašovací údaje klienta OAuth použijte v případě, že vaše backendová integrace potřebuje krátkodobé přístupové tokeny nebo je vyžaduje vaše bezpečnostní politika. Každý klient patří k jednomu servisnímu účtu a jedné organizaci. OAuth je volitelný: pro soukromou serverovou integraci, která dokáže bezpečně ukládat a rotovat klíč, postačuje klíč API s omezeným rozsahem. V části Ověřování najdete, jak si mezi oběma metodami vybrat a jak do nich zapadají servisní účty.
Přístup OAuth musí být pro vaši organizaci povolen. Součástí vašeho nastavení jsou regionální koncový bod tokenů, vydavatel (issuer), cílová skupina (audience) a metoda ověřování klienta. Pokud tato nastavení potřebujete nebo nemáte přístup ke správě klientů, obraťte se na podporu Living Security.
Udělení přihlašovacích údajů klienta (client credentials grant) představuje váš servisní účet. Nepřihlašuje osobu ani nevyžaduje, aby zákazník autorizoval aplikaci. Delegovaná autorizace prostřednictvím prohlížeče je samostatná funkce OAuth a tyto operace ji nenabízejí.

Než začnete

  • Vytvořte servisní účet pouze s oprávněními, která integrace potřebuje.
  • Použijte přihlašovací údaje pro správu s oprávněním service_account:manage a s každým oprávněním, které chcete novému klientovi udělit. Cílový účet musí tato oprávnění mít také. Klient nemůže rozšířit pravomoci žádného z obou účtů.
  • Vyberte region své organizace. Přihlašovací údaje API a přístupové tokeny OAuth patří na odpovídající regionální hostitel API.
  • Tajný klíč klienta a tokeny uchovávejte v úložišti tajných údajů na straně serveru. Nikdy je nevkládejte do kódu prohlížeče, mobilních aplikací, správy zdrojového kódu ani do protokolů požadavků.

Vytvoření klienta

POST /v1/oauth_clients vyžaduje service_account_id, neprázdný seznam explicitních scopes a Idempotency-Key. Zástupné znaky (wildcards) nejsou povoleny. Klient podporuje až 100 oborů (scopes) s celkovou délkou nejvýše 4 096 znaků. Každý servisní účet může mít nejvýše 20 klientů nebo nevyřešených operací vytvoření či vyčištění. Odvolání okamžitě zamezí přístupu k API. Klient nebo nejistě provedené vytvoření u poskytovatele se do limitu počítá i nadále, dokud není potvrzeno vzdálené vyčištění. Opuštěná rezervace nebo vytvoření, u něhož je prokázáno, že selhalo dříve, než práce u poskytovatele začala, může svůj slot bezpečně uvolnit. Jeho klíč pro opakování však stále patří původnímu pokusu; než se rozhodnete, zda vytvořit náhradu, obnovte tuto potvrzenku. Pro tento pokus o vytvoření zvolte jeden klíč pro opakování a uložte jej před odesláním požadavku. Použijte 1–255 viditelných znaků ASCII bez mezer. Použijte jej znovu se stejným účtem, obory, principálem správy, regionem a verzí API po ztrátě odpovědi. Rotace přihlašovacích údajů pro správu v rámci stejného servisního účtu nevytváří novou identitu opakování. Nainstalujte balíček requests pro Python. Následující hodnoty prostředí načtěte pomocí svého běžného řešení pro správu tajných údajů a konfigurace:
Python
Příklad odešle jeden požadavek a uchová výsledek v paměti. Před spuštěním v produkci přidejte na označeném místě operaci zápisu do svého správce tajných údajů. Příklad záměrně vyžaduje rozhodnutí po nejistém výsledku, místo aby bez upozornění vytvořil dalšího klienta. Síťové výjimky rovněž vyžadují postup obnovy popsaný níže. Odpovědi na vytvoření a potvrzenku používají 201 a obsahují prostředek oauth_client s poli id, service_account_id, client_id, scopes, status, created_at a client_secret. Odpovědi jsou označeny Cache-Control: no-store.
  • id identifikuje prostředek platformy. Uložte jej pro načtení a odvolání.
  • client_id identifikuje klienta při výměně tokenu. Nejde o ID prostředku platformy. Během čekajícího vytvoření může mít hodnotu null.
  • client_secret je vrácen pouze požadavku, který vytvoření dokončí. Každý opakovaný požadavek na vytvoření vrací null, včetně opakování po ztracené odpovědi o úspěchu. Načtení tajný klíč nikdy nevrací.

Obnova po ztracené nebo přerušené odpovědi

Zopakujte stejný požadavek na vytvoření s uloženým klíčem pro opakování, abyste obnovili potvrzenku prostředku. Potvrzenka odráží aktuální stav, takže odvolaný klient zůstává odvolaný. Tato operace nepoužívá obecný model opakování z mezipaměti s platností 24 hodin a nevrací hlavičku Idempotent-Replayed. ID požadavků a podrobnosti o obnově najdete v části chyby. Tajný klíč klienta ani přístupový token nikdy neposílejte spolu s požadavkem na podporu.

Kontrola a odvolání

Použijte své přihlašovací údaje pro správu a id prostředku platformy: Odvolání blokuje následné požadavky API tohoto klienta, včetně požadavků s již vydanými tokeny. Neruší práci, kterou API již přijalo. Vzdálené vyčištění přihlašovacích údajů může skončit později. Opakované odvolání je bezpečné a nevyžaduje klíč pro opakování. Pokud je odvolávaný klient sám volajícím API, používejte dále přihlašovací údaje pro správu.

Rotace bez ztráty přístupu

Vytvořte druhého klienta s požadovaným stropem oborů. Uložte jeho tajný klíč, získejte token pomocí svého regionálního koncového bodu tokenů a ověřte, že integrace s ním funguje. Přepněte integraci na náhradního klienta a poté odvolejte starý prostředek. Ponechte si nezávislé přihlašovací údaje pro správu, abyste se mohli zotavit z nezdařeného nasazení. Přístupové tokeny nemohou udělit více, než umožňují obory klienta a aktuální oprávnění servisního účtu. Odebrání oprávnění účtu nebo odvolání klienta má přednost před zbývající platností tokenu. Neberte token v mezipaměti jako důkaz, že autorizace stále platí. Nový přístupový token získejte před vypršením platnosti opětovným ověřením klienta; toto udělení nepoužívá obnovovací tokeny (refresh tokens).