Skip to main content
Use as credenciais de cliente OAuth quando a sua integração de backend precisar de tokens de acesso de curta duração ou quando a sua política de segurança os exigir. Cada cliente pertence a uma conta de serviço e a uma organização. O OAuth é opcional: uma chave de API com escopo definido é suficiente para uma integração privada de servidor que consiga armazenar e rotacionar uma chave com segurança. Consulte Autenticação para escolher entre os dois métodos e entender como as contas de serviço se encaixam.
O acesso OAuth deve estar habilitado para a sua organização. A sua configuração fornece o endpoint de token regional, o emissor, o público-alvo (audience) e o método de autenticação do cliente. Se precisar dessas configurações ou não conseguir acessar o gerenciamento de clientes, entre em contato com o Suporte da Living Security.
A concessão de credenciais de cliente representa a sua conta de serviço. Ela não autentica uma pessoa nem solicita que um cliente autorize um aplicativo. A autorização delegada por meio de um navegador é um recurso OAuth distinto e não é oferecida por estas operações.

Antes de começar

  • Crie uma conta de serviço com apenas as permissões de que a integração necessita.
  • Use uma credencial de gerenciamento com service_account:manage e cada permissão que você deseja conceder ao novo cliente. A conta de destino também deve possuir essas permissões. Um cliente não pode ampliar a autoridade de nenhuma das contas.
  • Escolha a região da organização. As credenciais de API e os tokens de acesso OAuth pertencem ao host de API regional correspondente.
  • Mantenha o segredo do cliente e os tokens no armazenamento de segredos do seu servidor. Nunca os coloque em código de navegador, aplicativos móveis, controle de versão ou logs de solicitação.

Criar um cliente

POST /v1/oauth_clients requer service_account_id, uma lista não vazia de scopes explícitos e um Idempotency-Key. Curingas não são aceitos. Um cliente oferece suporte a até 100 escopos, com um comprimento combinado de no máximo 4.096 caracteres. Cada conta de serviço pode ter no máximo 20 clientes ou operações de criação/limpeza não resolvidas. A revogação nega imediatamente o acesso à API. Um cliente ou uma criação incerta no provedor continua a contar para o limite até que a limpeza remota seja confirmada. Uma reserva abandonada ou uma criação comprovadamente falha antes de o trabalho no provedor ter começado pode liberar sua vaga com segurança. A chave de nova tentativa dela ainda pertence à tentativa original; recupere esse recibo antes de decidir se deve criar uma substituição. Escolha uma chave de nova tentativa para esta tentativa de criação e a persista antes de enviar a solicitação. Use de 1 a 255 caracteres ASCII visíveis, sem espaços. Reutilize-a com a mesma conta, os mesmos escopos, a mesma entidade de gerenciamento, a mesma região e a mesma versão da API após uma resposta perdida. Rotacionar a credencial de gerenciamento na mesma conta de serviço não cria uma nova identidade de nova tentativa. Instale o pacote requests do Python. Carregue os valores de ambiente a seguir por meio do seu gerenciamento normal de segredos e configuração:
Python
O exemplo faz uma única solicitação e mantém o resultado na memória. Adicione a operação de gravação do seu gerenciador de segredos no ponto indicado antes de executá-lo em produção. Ele exige deliberadamente uma decisão após um resultado incerto, em vez de criar silenciosamente outro cliente. Exceções de rede também exigem as etapas de recuperação abaixo. As respostas de criação e de recibo usam 201 e contêm um recurso oauth_client com id, service_account_id, client_id, scopes, status, created_at e client_secret. As respostas são marcadas como Cache-Control: no-store.
  • id identifica o recurso da plataforma. Salve-o para consulta e revogação.
  • client_id identifica o cliente durante a troca de tokens. Não é o ID do recurso da plataforma. Pode ser null enquanto a criação está pendente.
  • client_secret é retornado somente à solicitação que conclui a criação. Toda solicitação de criação repetida retorna null, inclusive uma nova tentativa após uma resposta de sucesso perdida. A consulta nunca retorna um segredo.

Recuperar-se de uma resposta perdida ou interrompida

Repita a mesma solicitação de criação com a chave de nova tentativa salva para recuperar o recibo do recurso. O recibo reflete o estado atual, portanto um cliente revogado permanece revogado. Esta operação não usa o contrato geral de repetição de respostas em cache de 24 horas e não retorna um cabeçalho Idempotent-Replayed. Consulte erros para obter IDs de solicitação e detalhes de recuperação. Nunca envie um segredo de cliente ou um token de acesso com uma solicitação de suporte.

Inspecionar e revogar

Use a sua credencial de gerenciamento e o id do recurso da plataforma: A revogação bloqueia as solicitações de API subsequentes do cliente, inclusive as solicitações com tokens já emitidos. Ela não cancela o trabalho já aceito pela API. A limpeza remota de credenciais pode ser concluída posteriormente. Repetir a revogação é seguro e não requer chave de nova tentativa. Continue usando a credencial de gerenciamento se o cliente que está sendo revogado for ele próprio um chamador da API.

Rotacionar sem perder o acesso

Crie um segundo cliente com o limite de escopo necessário. Salve o segredo dele, obtenha um token usando o endpoint de token regional e verifique se a integração funciona com ele. Altere a integração para a substituição e, em seguida, revogue o recurso antigo. Mantenha uma credencial de gerenciamento independente para poder se recuperar de uma implantação malsucedida. Os tokens de acesso não podem conceder mais do que os escopos do cliente e as permissões atuais da conta de serviço. A remoção de permissões da conta ou a revogação de um cliente têm precedência sobre o tempo de vida restante de um token. Não trate um token em cache como prova de que a autorização ainda é válida. Obtenha um novo token de acesso antes da expiração autenticando o cliente novamente; esta concessão não usa tokens de atualização.