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
:
token
simple-http
oauth2-client_credentials
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
:
token
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
:
username
password
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
:
client_id
client_secret
token_url
refresh_offset
14400
(quatro horas) por padrão.options
(Opcional) Especifica opções adicionais para a integração OAuth:
scope
: uma cadeia de caracteres que representa o escopo do OAuth 2.0 para as credenciais.audience
: uma cadeia de caracteres que representa um token de acesso Auth0.
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:
expires_in
é maior que28800
(oito horas).refresh_offset
é menor que o valor deexpires_in
menos14400
(quatro horas). Por exemplo, seexpires_in
for36000
(dez horas), erefresh_offset
for28800
(oito horas), a troca será considerada com falha porque28800
é maior que36000
-14400
(21600
).
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:
expires_at
é a hora UTC atual mais o valor deexpires_in
.refresh_at
é a hora UTC atual mais o valor deexpires_in
, menos o valor derefresh_offset
. Por exemplo, seexpires_in
for43200
(doze horas) erefresh_offset
for14400
(quatro horas), a propriedaderefresh_at
será definida como28800
(oito horas) após a hora UTC atual.
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
:
scopes
Lista os escopos de produto do Google para autenticação. Os seguintes escopos são compatíveis:
- Anúncios do Google:
https://www.googleapis.com/auth/adwords
- Pub/Sub Do Google:
https://www.googleapis.com/auth/pubsub
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.
succeeded
associado ao ambiente no qual a biblioteca está sendo criada. Por exemplo, se uma biblioteca tiver um elemento de dados secreto que não tenha um segredo succeeded
configurado para a seção Segredo de Preparo, tentar criar essa biblioteca no ambiente de preparo resultará em um erro.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.