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 as exigir. Cada cliente pertence a uma conta de serviço e a uma organização. O OAuth é opcional: uma chave de API com escopo restrito é suficiente para uma integração de servidor privada 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 inicial 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 precisa.
  • 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ções.

Criar um cliente

POST /v1/oauth_clients exige service_account_id, uma lista não vazia de scopes explícitos e um(a) Idempotency-Key. Curingas não são aceitos. Um cliente oferece suporte a até 100 escopos, com comprimento total 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 contando para o limite até que a limpeza remota seja confirmada. Uma reserva abandonada ou uma criação comprovadamente malsucedida antes de o trabalho no provedor começar pode liberar sua vaga com segurança. A chave de nova tentativa ainda pertence à tentativa original; recupere esse recibo antes de decidir se deve criar um substituto. Escolha uma chave de nova tentativa para esta tentativa de criação e persista-a 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 seguintes valores de ambiente por meio do seu gerenciamento habitual de segredos e configurações:
Python
O exemplo faz uma 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. Ele não é o ID do recurso da plataforma. Pode ser null enquanto a criação estiver pendente.
  • client_secret é retornado apenas para a 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 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 reprodução de resposta 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 token de acesso em uma solicitação de suporte.

Inspecionar e revogar

Use a sua credencial de gerenciamento e o recurso da plataforma id: 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 das credenciais pode ser concluída posteriormente. Repetir a revogação é seguro e não exige 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 seu endpoint de token regional e verifique se a integração funciona com ele. Mude a integração para o substituto e, em seguida, revogue o recurso antigo. Mantenha uma credencial de gerenciamento independente para que você possa 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 de expirar autenticando o cliente novamente; esta concessão não usa tokens de atualização.