Skip to main content
Feu servir les credencials de client OAuth quan la vostra integració de backend necessiti tokens d’accés de curta durada o quan la vostra política de seguretat ho requereixi. Cada client pertany a un sol compte de servei i a una sola organització. OAuth és opcional: una clau d’API amb abast limitat és suficient per a una integració privada de servidor que pugui emmagatzemar i rotar una clau de manera segura. Consulteu Authentication per triar entre els dos mètodes i entendre com encaixen els comptes de servei.
L’accés a OAuth ha d’estar habilitat per a la vostra organització. La vostra configuració proporciona el punt final de tokens regional, l’emissor, l’audiència i el mètode d’autenticació del client. Si necessiteu aquests paràmetres o no podeu accedir a la gestió de clients, contacteu amb el Suport de Living Security.
La concessió de credencials de client representa el vostre compte de servei. No inicia la sessió d’una persona ni demana a un client que autoritzi una aplicació. L’autorització delegada mitjançant un navegador és una funcionalitat d’OAuth diferent i no s’ofereix amb aquestes operacions.

Abans de començar

  • Creeu un compte de servei amb només els permisos que necessita la integració.
  • Feu servir una credencial de gestió amb service_account:manage i cada permís que vulgueu concedir al nou client. El compte de destinació també ha de tenir aquests permisos. Un client no pot ampliar l’autoritat de cap dels dos comptes.
  • Trieu la regió de l’organització. Les credencials d’API i els tokens d’accés OAuth pertanyen al host d’API regional corresponent.
  • Conserveu el secret del client i els tokens a l’emmagatzematge de secrets del vostre servidor. No els poseu mai en codi de navegador, aplicacions mòbils, control de versions ni registres de sol·licituds.

Creació d’un client

POST /v1/oauth_clients requereix service_account_id, una llista no buida de scopes explícits i un Idempotency-Key. No s’accepten comodins. Un client admet fins a 100 scopes, amb una longitud combinada de com a màxim 4.096 caràcters. Cada compte de servei pot tenir com a màxim 20 clients o operacions de creació/neteja no resoltes. La revocació denega immediatament l’accés a l’API. Un client o una creació incerta al proveïdor continua comptant per al límit fins que es confirmi la neteja remota. Una reserva abandonada o una creació que s’hagi demostrat que ha fallat abans que comencés la feina al proveïdor pot alliberar la seva plaça de manera segura. La seva clau de reintent continua pertanyent a l’intent original; recupereu aquest rebut abans de decidir si cal crear un substitut. Trieu una clau de reintent per a aquest intent de creació i deseu-la abans d’enviar la sol·licitud. Feu servir entre 1 i 255 caràcters ASCII visibles, sense espais. Reutilitzeu-la amb el mateix compte, els mateixos scopes, el mateix principal de gestió, la mateixa regió i la mateixa versió d’API després d’una resposta perduda. Rotar la credencial de gestió sota el mateix compte de servei no crea una nova identitat de reintent. Instal·leu el paquet requests de Python. Carregueu els valors d’entorn següents mitjançant la vostra gestió habitual de secrets i configuració:
Python
L’exemple fa una sola sol·licitud i conserva el resultat a la memòria. Afegiu l’operació d’escriptura del vostre gestor de secrets al punt marcat abans d’executar-lo en producció. Exigeix deliberadament una decisió després d’un resultat incert en lloc de crear silenciosament un altre client. Les excepcions de xarxa també requereixen els passos de recuperació següents. Les respostes de creació i de rebut fan servir 201 i contenen un recurs oauth_client amb id, service_account_id, client_id, scopes, status, created_at i client_secret. Les respostes es marquen amb Cache-Control: no-store.
  • id identifica el recurs de la plataforma. Deseu-lo per a la consulta i la revocació.
  • client_id identifica el client durant l’intercanvi de tokens. No és l’ID del recurs de la plataforma. Pot ser null mentre la creació està pendent.
  • client_secret només es retorna a la sol·licitud que completa la creació. Cada sol·licitud de creació repetida retorna null, inclòs un reintent després d’una resposta d’èxit perduda. La consulta mai no retorna un secret.

Recuperació d’una resposta perduda o interrompuda

Repetiu la mateixa sol·licitud de creació amb la clau de reintent desada per recuperar el rebut del recurs. El rebut reflecteix l’estat actual, de manera que un client revocat continua revocat. Aquesta operació no fa servir el contracte general de reproducció de respostes en memòria cau de 24 hores i no retorna cap capçalera Idempotent-Replayed. Consulteu errors per als ID de sol·licitud i els detalls de recuperació. No envieu mai un secret de client ni un token d’accés amb una sol·licitud de suport.

Inspecció i revocació

Feu servir la vostra credencial de gestió i el id del recurs de la plataforma: La revocació bloqueja les sol·licituds d’API posteriors del client, incloses les sol·licituds amb tokens ja emesos. No cancel·la la feina que l’API ja ha acceptat. La neteja remota de credencials pot completar-se més tard. Repetir la revocació és segur i no requereix cap clau de reintent. Continueu fent servir la credencial de gestió si el client que es revoca és alhora un emissor de crides a l’API.

Rotació sense perdre l’accés

Creeu un segon client amb el límit d’scopes necessari. Deseu-ne el secret, obteniu un token mitjançant el vostre punt final de tokens regional i verifiqueu que la integració funciona amb aquest. Canvieu la integració al substitut i, a continuació, reviqueu el recurs antic. Conserveu una credencial de gestió independent per poder recuperar-vos d’un desplegament incorrecte. Els tokens d’accés no poden concedir més del que permeten els scopes del client i els permisos actuals del compte de servei. Eliminar permisos del compte o revocar un client preval sobre la vida restant d’un token. No considereu un token en memòria cau com a prova que l’autorització continua sent vàlida. Obteniu un nou token d’accés abans que caduqui tornant a autenticar el client; aquesta concessió no fa servir tokens d’actualització.