Procurando a documentação anterior?Acesse v1.docs.pluggy.ai
PluggyDocs

Lista de IPs permitidos

Restringir quais endereços IP podem chamar a Referência da API do Pluggy com as credenciais de uma aplicação, para que um client secret ou chave da API vazados não possam ser usados de qualquer outro lugar. Como funciona, como configurá-lo no Dashboard, o que cobre e como solucionar um 403 CLIENT_IP_NOT_ALLOWED.

Ver como Markdown

Um segredo de cliente ou uma chave de API que vaza pode ser usado por qualquer pessoa que a possua, de qualquer lugar. Uma lista de IPs permitidos restringe isso: você lista os endereços IP dos quais seus servidores chamam o Pluggy, e a API recusa as credenciais dessa aplicação de qualquer outro endereço.

A lista de permitidos é opcional e desativada por padrão. Uma aplicação sem uma aceita solicitações de qualquer IP, como sempre fez.

Um tour de 30 segundos sobre IPs Permitidos no Dashboard. O texto na tela está em português.

Como funciona#

Cada aplicação tem sua própria lista. Quando a lista não está vazia, a API verifica o IP público de cada solicitação:

  • POST /auth, que troca o ID do cliente e o segredo do cliente por uma chave de API, é aceito apenas de um IP listado.
  • Cada solicitação autenticada com uma chave de API dessa aplicação (X-API-KEY) é aceita apenas de um IP listado. Isso inclui a criação de um Connect Token com POST /connect_token.

Uma solicitação de qualquer outro IP é recusada com 403 e CLIENT_IP_NOT_ALLOWED (veja O erro). A mudança entra em vigor assim que você a salva.

Solicitações autenticadas com um Connect Token não são verificadas. O Pluggy Connect roda nos navegadores e telefones dos seus usuários, cujos IPs você não pode conhecer, então o widget continua funcionando onde quer que seus usuários estejam.

O que é e o que não é restrito#

SolicitaçãoRestrito pela lista de permitidos
POST /auth com o ID do cliente e o segredo do cliente da aplicaçãoSim
Qualquer solicitação com uma chave de API da aplicação em X-API-KEYSim
POST /connect_token (é chamado com uma chave de API)Sim
Solicitações feitas com um Connect Token, incluindo Pluggy ConnectNão
Um Connect Token que já foi emitidoNão: continua funcionando até expirar
O DashboardNão: você pode sempre editar ou remover a lista lá

Configure#

Apenas OWNERs e ADMINs de uma equipe podem editar a lista. MEMBERs a veem como somente leitura (veja Acesso à equipe).

  1. Abra o Dashboard, vá para Aplicações e abra a aplicação.
  2. Encontre o cartão IPs Permitidos, entre as credenciais e os webhooks. Ele está disponível para cada aplicação, em desenvolvimento e em produção.
  3. Adicione os IPs públicos dos quais seus servidores chamam o Pluggy: endereços únicos ou intervalos CIDR, IPv4 ou IPv6. Você pode colar vários de uma vez, separados por vírgulas, espaços ou novas linhas.
  4. Salve e confirme. A lista se aplica imediatamente, então certifique-se de que todos os servidores que usam as credenciais dessa aplicação estejam nela antes de confirmar.

Para desativar a restrição, use Remover restrição no mesmo cartão. A lista é limpa e a aplicação aceita qualquer IP novamente.

O que você pode listar#

RegraDetalhe
FormatosEndereços IPv4 ou IPv6, ou intervalos CIDR: 203.0.113.10, 198.51.100.0/24, 2001:db8::/32.
TamanhoAté 50 entradas por aplicação.
Não aceitoIntervalos /0 (0.0.0.0/0, ::/0): eles permitiriam todos os endereços.
DuplicatasEliminadas.
NormalizaçãoA lista armazenada é normalizada: um intervalo escrito com bits de host definidos é salvo como seu endereço de rede, então 10.0.0.5/8 é armazenado como 10.0.0.0/8.

Cada alteração na lista é registrada no log de atividades da sua equipe, com quem a fez.

Qual IP listar#

A API vê o IP público do qual sua solicitação chega ao Pluggy, não o endereço da máquina que a fez.

  • Se seus servidores saem para a internet através de um gateway NAT, um proxy ou a saída do seu provedor de nuvem, liste os IPs de saída (por exemplo, um IP estático ou elástico do gateway NAT).
  • Endereços privados (10.x, 172.16.x–172.31.x, 192.168.x) nunca chegam ao Pluggy, então listá-los não tem efeito.
  • Se seus servidores não têm um IP público fixo, configure um antes de ativar a lista de permitidos. Com um endereço que muda, a próxima alteração bloqueia seus servidores.

Para encontrar o IP de saída, chame um serviço de eco de IP do próprio servidor ou verifique os IPs estáticos do seu gateway NAT ou proxy no console do seu provedor de nuvem.

O erro#

Uma solicitação de um IP que não está na lista recebe:

json
{
  "code": 403,
  "codeDescription": "CLIENT_IP_NOT_ALLOWED",
  "message": "O endereço IP da solicitação não está na lista de IPs permitidos configurados para esta aplicação."
}

Baseie-se em codeDescription, não em message. Tentar novamente do mesmo IP retorna o mesmo erro: a solução é chamar de um IP listado ou adicionar o IP à lista. Veja também Códigos de erroAPI.

Boa prática#

  • Use IPs de saída estáticos. Uma lista de permitidos é tão estável quanto os endereços nela.
  • Adicione o novo IP antes de migrar. Quando você se mudar para uma nova região, conta de nuvem ou gateway NAT, adicione seus IPs primeiro, implemente e remova os antigos apenas depois que o tráfego tiver mudado.
  • Uma aplicação por ambiente, uma lista por aplicação. Seus servidores de CI ou staging usam sua própria aplicação com sua própria lista, então a lista de produção permanece curta. Veja Credenciais e chaves de API.
  • Combine com as outras camadas. Uma lista de permitidos limita onde uma credencial vazada funciona; não substitui manter segredos fora do código e rotacioná-los (Rotacionar o segredo do cliente), nem verificar seus webhooks (Segurança do webhook).

Solução de problemas#

Estou recebendo 403 CLIENT_IP_NOT_ALLOWED#

A aplicação tem uma lista de permitidos e a solicitação veio de um IP que não está nela. Encontre o IP público do qual o servidor realmente sai (veja Qual IP listar), e peça a um OWNER ou ADMIN para adicioná-lo no cartão IPs Permitidos. As causas usuais são um novo servidor, uma mudança de gateway NAT ou região, uma implantação em uma plataforma sem IPs de saída fixos, ou um script executado de um laptop.

Qual IP eu listarei?#

O IP público do qual seus servidores alcançam o Pluggy: o IP de saída do seu gateway NAT, proxy ou rede de nuvem, não um endereço privado. Veja Qual IP listar.

Isso afeta o widget Connect?#

Não. Solicitações feitas com um Connect Token não são restritas, então o Pluggy Connect continua funcionando de qualquer dispositivo do usuário. Criar o Connect Token é restrito: seu backend chama POST /connect_token com uma chave de API, então precisa ser executado de um IP listado.

Eu me bloqueei#

O Dashboard nunca é bloqueado pela lista de permitidos. Um OWNER ou ADMIN pode abrir a aplicação, adicionar o IP ausente ou usar Remover restrição, e a mudança se aplica imediatamente.

Isso é o mesmo que permitir os IPs do webhook do Pluggy?#

Não, é a direção oposta. Esta página restringe quem pode chamar a API do Pluggy com suas credenciais. Para aceitar notificações de webhook apenas do Pluggy, veja Permitir apenas os IPs de origem do Pluggy.

Não protege contra#

  • Uma credencial usada de um dos seus próprios servidores listados: se um atacante controla uma máquina na lista, a lista de permitidos não os impede.
  • Um Connect Token que vaza: Connect Tokens não são restritos por IP. Eles têm vida curta e escopo limitado, veja Connect Tokens.

Próximo: Connect Tokens.

Esta página foi útil?