Segredos na API do Reator

Na API do Reator, um segredo é um recurso que representa uma credencial de autenticação. Segredos são usados no encaminhamento de eventos para autenticar em outro sistema para troca segura de dados. Portanto, segredos só podem ser criados nas propriedades de encaminhamento de eventos (propriedades cujo atributo platform está definido como edge).

Atualmente, há três tipos de segredos com suporte indicados no atributo type_of:

Este guia fornece uma visão geral de alto nível sobre como configurar segredos para usar no encaminhamento de eventos. Para obter orientação detalhada sobre como gerenciar segredos na API do Reator, incluindo o exemplo JSON da estrutura de um segredo, consulte o manual de endpoint de segredos.

Credenciais

Cada segredo contém um atributo credentials que contém seus respectivos valores de credencial. Ao criar um segredo na API, cada tipo de segredo tem atributos obrigatórios diferentes, conforme mostrado nas seções abaixo:

token token

Segredos com um valor type_of de token exigem apenas um único atributo em credentials:

O token é armazenado como um valor estático e, portanto, as propriedades expires_at e refresh_at do segredo são definidas como null quando o segredo é criado.

simple-http simple-http

Segredos com um valor type_of de simple-http exigem os seguintes atributos em credentials:

Quando o segredo é criado, os dois atributos são trocados com uma codificação BASE64 de username:password. Após a troca, as propriedades expires_at e refresh_at do segredo serão definidas como null.

oauth2-client_credentials oauth2-client_credentials

Segredos com um valor type_of de oauth2-client_credentials exigem os seguintes atributos em credentials:

Quando um segredo oauth2-client_credentials é criado ou atualizado, o client_id e o client_secret (e possivelmente o options) são trocados em uma solicitação POST para o token_url, de acordo com o fluxo Credenciais de Cliente do protocolo OAuth.

Se o serviço de autorização responder com 200 OK e um corpo de resposta JSON, o corpo será analisado e access_token será enviado por push para o ambiente de borda e expires_in será usado para calcular os atributos expires_at e refresh_at do segredo. Se não houver associação de ambiente no segredo, access_token será descartado.

Uma troca de credenciais é considerada bem-sucedida sob as seguintes condições:

Se a troca for bem-sucedida, o atributo de status do segredo é definido como succeeded e os valores para expires_at e refresh_at são definidos:

Se a troca falhar por algum motivo, o atributo status_details no objeto meta será atualizado com informações relevantes.

Atualizando um segredo oauth2-client_credentials

Se um segredo oauth2-client_credentials tiver sido atribuído a um ambiente e seu status for succeeded (as credenciais foram trocadas com êxito), uma nova troca será executada automaticamente em refresh_at.

Se a troca for bem-sucedida, o atributo refresh_status no objeto meta será definido como succeeded enquanto expires_at, refresh_at e activated_at forem devidamente atualizados.

Se houver falha na troca, haverá mais três tentativas com a última tentativa até não mais do que duas horas antes de o token de acesso expirar. Se todas as tentativas falharem, o atributo refresh_status_details do objeto meta será atualizado com detalhes relevantes.

oauth2-google oauth2-google

Segredos com um valor type_of de oauth2-google exigem o seguinte atributo em credentials:

Depois de criar o segredo oauth2-google, a resposta inclui uma propriedade meta.authorization_url. Você deve copiar e colar esse URL em um navegador para concluir o fluxo de autenticação do Google.

Reautorizar um segredo de oauth2-google

A URL de autorização para um segredo oauth2-google expira uma hora após a criação do segredo (conforme indicado por meta.authorization_url_expires_at). Após esse período, o segredo deverá ser reautorizado para renovar o processo de autenticação.

Consulte o manual de endpoint de segredos para obter detalhes sobre como reautorizar um segredo oauth2-google fazendo uma solicitação PATCH para a API do Reator.

Relacionamento de ambiente

Ao criar um segredo, você deve especificar o ambiente no qual ele existirá. Segredos são imediatamente implantados no ambiente em que são criados.

Um segredo só pode ser associado a um ambiente. Uma vez estabelecida a relação entre um segredo e um ambiente, o segredo não pode ser apagado do ambiente e o segredo não pode ser associado a um ambiente diferente.

Depois que as credenciais de um segredo forem trocadas com êxito, para que um segredo seja associado a um ambiente, o artefato de troca (a cadeia de caracteres do token para token, a cadeia de caracteres codificada em Base64 para simple-http ou o token de acesso para oauth2-client_credentials) será salvo com segurança no ambiente.

Depois que o artefato do Exchange é salvo com êxito no ambiente, o atributo activated_at do segredo é definido como a hora UTC atual e agora pode ser referenciado usando um elemento de dados. Consulte a próxima seção para obter mais informações sobre segredos de referência.

Referência de segredos referencing-secrets

Para referenciar um segredo, você deve criar um elemento de dados do tipo "Segredo" (fornecido pela Extensão ​) em uma propriedade de encaminhamento de eventos. Ao configurar esse elemento de dados, você será solicitado a indicar qual segredo usar para cada ambiente. Em seguida, você pode criar regras que fazem referência a um elemento de dados secreto, como no cabeçalho de uma chamada HTTP.

No tempo de execução, o elemento de dados secreto é substituído pelo artefato de troca secreta correspondente salvo no ambiente.

Próximas etapas

Este guia abordou os fundamentos do trabalho com segredos na API do Reator. Para obter detalhes sobre como gerenciar segredos usando chamadas de API, consulte o manual de endpoint de segredos.