Gerenciar a lista de IPs permitidos pela API

Duas operações da API do Identity gerenciam a lista de IPs permitidos: uma a lê, outra a substitui. Use-as quando você gerencia as configurações de segurança pelas suas próprias ferramentas em vez do Console.

As páginas de referência dessas duas operações ainda não estão na referência da API. O pai delas é APIs do Identity. Esta página é o contrato até as páginas de referência chegarem.

As duas operações

Operação	O que ela faz	Permissão
`GET /v1/security/ip-allowlist`	Retorna as entradas guardadas e as superfícies em que a lista se aplica.	`security` / `get`
`PUT /v1/security/ip-allowlist`	Substitui a lista inteira e, opcionalmente, as superfícies.	`security` / `put`

As duas operações ficam na URL base da API do Identity e precisam de um bearer token. A plataforma resolve o seu workspace a partir do token. Não existe identificador de organização no caminho nem no corpo.

O corpo

O corpo de requisição do PUT e o corpo de resposta das duas operações têm o mesmo formato:

{
  "entries": ["203.0.113.0/24", "198.51.100.7"],
  "scopes": ["console", "api"]
}

Campo	Obrigatório	Significado
`entries`	Sim	A lista completa de endereços e faixas CIDR. O que você envia substitui o que está guardado.
`scopes`	Não	Onde a lista se aplica: `console`, `api` ou os dois.

Regras que valem para os campos:

entries é uma substituição completa. Para acrescentar um endereço, envie a lista atual mais o novo endereço.
A resposta devolve as entradas como a plataforma as guardou. Um endereço único volta com o prefixo dele: 198.51.100.7 vira 198.51.100.7/32.
entries: [] desativa a lista. A operação retorna 200.
Uma lista guardada vazia é serializada como [], nunca como null.
Quando você omite scopes, os escopos guardados ficam como estão.
scopes: [] mantém as entradas mas para a aplicação da lista em todo lugar.
Quando você omite entries, a operação retorna 400 com o código IDE-0001 e nada muda.

Exemplos

Troque os espaços reservados pela URL base da sua API do Identity e por um bearer token que tenha a permissão security.

IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"

curl -sS "${IDENTITY_BASE_URL}/v1/security/ip-allowlist" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}"

IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"

curl -sS -X PUT "${IDENTITY_BASE_URL}/v1/security/ip-allowlist" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": ["203.0.113.0/24", "198.51.100.7"],
    "scopes": ["console"]
  }'

IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"

curl -sS -X PUT "${IDENTITY_BASE_URL}/v1/security/ip-allowlist" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": ["203.0.113.0/24", "198.51.100.7", "192.0.2.10"],
    "scopes": ["console", "api"]
  }'

IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"

curl -sS -X PUT "${IDENTITY_BASE_URL}/v1/security/ip-allowlist" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "entries": [] }'

Um PUT bem-sucedido retorna 200 com a lista guardada:

{
  "entries": ["203.0.113.0/24", "198.51.100.7/32"],
  "scopes": ["console"]
}

Ordem recomendada

Cadastre os endereços apenas com o escopo console

Envie a lista completa com "scopes": ["console"]. Inclua o endereço de onde você chama.

Confirme que você ainda consegue entrar

Entre no Console a partir de um endereço listado. Depois tente a partir de um endereço não listado e espere uma recusa.

Liste o endereço de saída de cada integração

Reúna o endereço de onde cada ERP, disparador de webhook, job agendado e application chama. Acrescente cada um a entries.

Acrescente o escopo api

Envie a lista completa de novo com "scopes": ["console", "api"]. Acompanhe as suas integrações em busca de respostas 403.

Erros

Cada erro usa o envelope do Access Manager com os campos code, title e message.

Status	`code`	`title`	`message`
400	`IDE-0001`	Missing Fields in Request	Your request is missing one or more required fields.
400	`IDE-0035`	IP Allowlist Too Large	The IP allowlist is too large: the combined, comma-separated entries must not exceed 200 characters. Please remove some entries and try again.
400	`IDE-0036`	Invalid IP Allowlist Entry	The IP allowlist entry `{value}` is not a valid IP address or CIDR block. Please correct it and try again.
400	`IDE-0037`	Invalid IP Allowlist Scope	The IP allowlist enforcement scope `{value}` is not supported. Please use console, api, or both, and try again.
401	`IDE-0008`	Token Missing	A valid token must be provided in the request header. Please include a token and try again.
401	`IDE-0009`	Invalid Token	The provided token is expired, invalid or malformed. Please provide a valid token and try again.
403	`AUT-0021`	IP Not Allowed	Access from your network is not allowed for this workspace. Contact your administrator.

Olhe o campo code, não apenas o status. Um 403 com o código AUT-0021 pode voltar de qualquer endpoint protegido, inclusive dessas duas operações, quando o seu próprio endereço está fora de uma lista ativa. Nesse caso a lista não mudou e você deve chamar a partir de um endereço listado.

Primeiros passos

Funcionalidades

Deploy e operações

Arquitetura

Provedor de identidade (Caradhras)

Gerenciar a lista de IPs permitidos pela API

As duas operações

O corpo

Exemplos

Ordem recomendada

Erros

Páginas relacionadas

Lista de IPs permitidos

Lista de erros do Access Manager

​As duas operações

​O corpo

​Exemplos

​Ordem recomendada

​Erros

​Páginas relacionadas

Lista de IPs permitidos

Lista de erros do Access Manager

As duas operações

O corpo

Exemplos

Ordem recomendada

Erros

Páginas relacionadas