Skip to main content
Utilizați credențialele client OAuth atunci când integrarea dvs. de backend necesită jetoane de acces cu durată scurtă de viață sau când politica dvs. de securitate le impune. Fiecare client aparține unui singur cont de serviciu și unei singure organizații. OAuth este opțional: o cheie API cu permisiuni limitate este suficientă pentru o integrare privată pe server care poate stoca și roti în siguranță o cheie. Consultați Autentificare pentru a alege între cele două metode și pentru a înțelege rolul conturilor de serviciu.
Accesul OAuth trebuie să fie activat pentru organizația dvs. Configurarea furnizează punctul final regional pentru jetoane, emitentul, audiența și metoda de autentificare a clientului. Dacă aveți nevoie de aceste setări sau nu puteți accesa gestionarea clienților, contactați asistența Living Security.
Fluxul de acordare a credențialelor client reprezintă contul dvs. de serviciu. Nu autentifică o persoană și nu îi solicită unui client să autorizeze o aplicație. Autorizarea delegată prin browser este o capabilitate OAuth distinctă și nu este oferită de aceste operațiuni.

Înainte de a începe

  • Creați un cont de serviciu care să aibă doar permisiunile de care are nevoie integrarea.
  • Utilizați o credențială de gestionare cu service_account:manage și cu fiecare permisiune pe care doriți să o acordați noului client. Contul țintă trebuie să dețină, de asemenea, aceste permisiuni. Un client nu poate extinde autoritatea niciunuia dintre conturi.
  • Alegeți regiunea organizației. Credențialele API și jetoanele de acces OAuth aparțin gazdei API regionale corespunzătoare.
  • Păstrați secretul clientului și jetoanele în spațiul de stocare a secretelor de pe server. Nu le introduceți niciodată în codul din browser, în aplicații mobile, în controlul versiunilor sau în jurnalele cererilor.

Crearea unui client

POST /v1/oauth_clients necesită service_account_id, o listă nevidă de scopes explicite și un Idempotency-Key. Caracterele wildcard nu sunt acceptate. Un client acceptă până la 100 de domenii de acces (scopes), cu o lungime totală de cel mult 4.096 de caractere. Fiecare cont de serviciu poate avea cel mult 20 de clienți sau operațiuni de creare/curățare nerezolvate. Revocarea refuză imediat accesul API. Un client sau o creare incertă la furnizor continuă să se numere în limită până când curățarea de la distanță este confirmată. O rezervare abandonată sau o creare despre care s-a dovedit că a eșuat înainte de începerea lucrului la furnizor poate elibera în siguranță locul respectiv. Cheia sa de reîncercare aparține în continuare încercării inițiale; recuperați acea confirmare de primire înainte de a decide dacă creați un înlocuitor. Alegeți o cheie de reîncercare pentru această încercare de creare și salvați-o înainte de a trimite cererea. Utilizați 1–255 de caractere ASCII vizibile, fără spații. Reutilizați-o cu același cont, aceleași domenii de acces, același principal de gestionare, aceeași regiune și aceeași versiune API după un răspuns pierdut. Rotirea credențialei de gestionare pentru același cont de serviciu nu creează o nouă identitate de reîncercare. Instalați pachetul requests din Python. Încărcați următoarele valori de mediu prin instrumentele dvs. obișnuite de gestionare a secretelor și a configurației:
Python
Exemplul efectuează o singură cerere și păstrează rezultatul în memorie. Adăugați operațiunea de scriere a managerului dvs. de secrete la punctul marcat înainte de a-l rula în producție. Exemplul impune în mod deliberat o decizie după un rezultat incert, în loc să creeze în tăcere un alt client. Excepțiile de rețea necesită, de asemenea, pașii de recuperare de mai jos. Răspunsurile de creare și de confirmare de primire utilizează 201 și conțin o resursă oauth_client cu id, service_account_id, client_id, scopes, status, created_at și client_secret. Răspunsurile sunt marcate cu Cache-Control: no-store.
  • id identifică resursa platformei. Salvați-l pentru regăsire și revocare.
  • client_id identifică clientul în timpul schimbului de jetoane. Nu este ID-ul resursei platformei. Poate fi null cât timp crearea este în așteptare.
  • client_secret este returnat doar cererii care finalizează crearea. Fiecare cerere de creare repetată returnează null, inclusiv o reîncercare după un răspuns de succes pierdut. Regăsirea nu returnează niciodată un secret.

Recuperarea după un răspuns pierdut sau întrerupt

Repetați aceeași cerere de creare cu cheia de reîncercare salvată pentru a recupera confirmarea de primire a resursei. Confirmarea de primire reflectă starea curentă, astfel că un client revocat rămâne revocat. Această operațiune nu utilizează contractul general de reluare a răspunsurilor din cache pe durata a 24 de ore și nu returnează un antet Idempotent-Replayed. Consultați erori pentru ID-urile cererilor și detalii despre recuperare. Nu trimiteți niciodată un secret de client sau un jeton de acces împreună cu o solicitare către asistență.

Verificare și revocare

Utilizați credențiala dvs. de gestionare și resursa platformei id: Revocarea blochează cererile API ulterioare ale clientului, inclusiv cererile cu jetoane deja emise. Nu anulează lucrările deja acceptate de API. Curățarea de la distanță a credențialelor se poate finaliza mai târziu. Repetarea revocării este sigură și nu necesită o cheie de reîncercare. Continuați să utilizați credențiala de gestionare dacă clientul care este revocat este el însuși un apelant API.

Rotirea fără pierderea accesului

Creați un al doilea client cu limita de domenii de acces necesară. Salvați secretul acestuia, obțineți un jeton utilizând punctul final regional pentru jetoane și verificați că integrarea funcționează cu acesta. Comutați integrarea la înlocuitor, apoi revocați resursa veche. Păstrați o credențială de gestionare independentă pentru a vă putea recupera după o implementare eșuată. Jetoanele de acces nu pot acorda mai mult decât domeniile de acces ale clientului și permisiunile curente ale contului de serviciu. Eliminarea permisiunilor contului sau revocarea unui client are prioritate față de durata de viață rămasă a unui jeton. Nu considerați un jeton din cache drept dovadă că autorizarea este încă validă. Obțineți un nou jeton de acces înainte de expirare autentificând din nou clientul; acest flux nu utilizează jetoane de reîmprospătare.