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 autenticação em outro sistema para troca de dados segura. Portanto, os segredos só podem ser criados nas propriedades de encaminhamento de eventos (propriedades cujas platform está definido como edge).

No momento, há três tipos secretos compatíveis indicados na variável type_of atributo:

Tipo de segredo Descrição
token Uma única string de caracteres representando um valor de token de autenticação conhecido e compreendido por ambos os sistemas.
simple-http Contém dois atributos de string para um nome de usuário e senha, respectivamente.
oauth2 Contém vários atributos para suportar a variável OAuth especificação de autenticação. O encaminhamento de eventos solicita as informações necessárias e, em seguida, lida com a renovação desses tokens para você em um intervalo especificado.

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

Credenciais

Cada segredo contém um credentials que mantém seus respectivos valores de credencial. Cada tipo de segredo tem atributos obrigatórios diferentes, conforme mostrado nas seções abaixo.

token

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

Atributo de credencial Tipo de dados Descrição
token String Um token secreto que é entendido pelo sistema de destino.

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

simple-http

Segredos com uma type_of valor de simple-http requerem os seguintes atributos em credentials:

Atributo de credencial Tipo de dados Descrição
username String Um nome de usuário.
password String Uma senha. Esse valor não está incluído na resposta da API.

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

oauth2

OBSERVAÇÃO

Atualmente, somente o Tipo de concessão de Credenciais do Cliente é compatível com segredos OAuth.

Segredos com uma type_of valor de oauth2 requerem os seguintes atributos em credentials:

Atributo de credencial Tipo de dados Descrição
client_id String A ID do cliente para a integração OAuth.
client_secret String O segredo do cliente para a integração OAuth. Esse valor não está incluído na resposta da API.
authorization_url String O URL de autorização da integração OAuth.
refresh_offset Número inteiro (Opcional) O valor, em segundos, para deslocar a operação de atualização. Se este atributo for omitido ao criar o segredo, o valor será definido como 14400 (quatro horas) por padrão.
options Objeto (Opcional) Especifica opções adicionais para a integração OAuth:

Quando uma oauth2 O segredo é criado ou atualizado, a variável client_id e client_secret e eventualmente options) são trocadas em uma solicitação de POST para authorization_url, de acordo com o fluxo de Credenciais do Cliente do protocolo OAuth.

OBSERVAÇÃO

Espera-se que o organismo de resposta do serviço de autorização seja compatível com o protocolo OAuth.

Se o serviço de autorização responder com 200 OK e um corpo de resposta JSON, o corpo é analisado e o access_token é enviado para o ambiente de borda e expires_in é usada para calcular a variável expires_at e refresh_at atributos para o segredo. Se não houver associação de ambiente no segredo, access_token é descartado.

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

  • expires_in é maior que 28800 (oito horas).
  • refresh_offset é menor que o valor de expires_in minus 14400 (quatro horas). Por exemplo, se expires_in é 36000 (dez horas) e a variável refresh_offset é 28800 (oito horas), a troca é considerada uma falha porque 28800 é maior que 36000 - 14400 (21600).

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

  • expires_at é a hora UTC atual mais o valor de expires_in.
  • refresh_at é a hora UTC atual mais o valor de expires_in, menos o valor de refresh_offset. Por exemplo, se expires_in é 43200 (doze horas) e a refresh_offset é 14400 (quatro horas), a variável refresh_at propriedade seria definida como 28800 (oito horas) após a hora UTC atual.

Se a troca falhar por algum motivo, a variável status_details no meta atualizações de objeto com informações relevantes.

Atualizar um oauth2 segredo

Se uma oauth2 O segredo foi atribuído a um ambiente e seu status é succeeded (as credenciais foram trocadas com êxito), uma nova troca é executada automaticamente em refresh_at.

Se a troca for bem-sucedida, a variável refresh_status no meta objeto definido como succeeded while expires_at, refresh_ate activated_at são atualizadas adequadamente.

Se a troca falhar, a operação será tentada mais três vezes com a última tentativa, não mais do que duas horas antes do token de acesso expirar. Se todas as tentativas falharem, a variável refresh_status_details do meta atualizações de objeto com detalhes relevantes.

Relação ambiente

Ao criar um segredo, você deve especificar a variável ambiente em que existirá. Os 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.

OBSERVAÇÃO

A única exceção a essa regra é se o ambiente em questão for excluído. Nesse caso, o relacionamento é limpo e o segredo pode ser atribuído a um ambiente diferente.

Depois que as credenciais de um segredo tiverem sido trocadas com sucesso, para que um segredo seja associado a um ambiente, o artefato exchange (a sequência de token de token, a string codificada em Base64 para simple-httpou o token de acesso para oauth2) é salva com segurança no ambiente .

Depois que o artefato de troca for salvo com sucesso no ambiente, o segredo activated_at está 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 como fazer referência a segredos.

Fazendo referência a segredos

Para fazer referência a um segredo, você deve criar um elemento de dados do tipo "Segredo" (fornecido pelo Núcleo extensão) em uma propriedade de encaminhamento de evento. 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.

Elemento de dados secreto

OBSERVAÇÃO

Para adicionar um elemento de dados secreto a uma biblioteca, você deve ter pelo menos um succeeded segredo associado ao ambiente no qual a biblioteca está sendo criada. Por exemplo, se uma biblioteca tiver um elemento de dados secreto que não tem um succeeded segredo configurado para o Segredo de armazenamento temporário , tentar criar essa biblioteca no ambiente de preparo resultará em um erro.

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

Próximas etapas

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

Nesta página