Segurança e autenticação

Cada API tem um modo de autenticação, escolhido na política de segurança e aplicado na publicação. Os modos são mutuamente exclusivos: PUBLIC, API_KEY e JWT_OIDC.

Resumo

Modo	Quem chama	O que o gateway verifica	Credencial
PUBLIC	qualquer um	nada (mas cabeçalho de identidade forjado é removido)	nenhuma
API_KEY	aplicações autorizadas	chave válida e consumidor autorizado naquela API	x-api-key ou Ocp-Apim-Subscription-Key (só o que a política escolheu)
JWT_OIDC	portadores de token do seu provedor de identidade	assinatura RSA, iss, exp, aud, nbf e escopos	Authorization: Bearer <JWT>

No modo JWT_OIDC, o provedor de identidade é sempre o do cliente — nunca o IAM da NNumbers.

PUBLIC

Nenhuma credencial é exigida. Mas o modo não é "sem proteção nenhuma": o gateway remove, antes de encaminhar ao seu backend, qualquer cabeçalho de identidade enviado pelo cliente — X-Consumer-*, X-Credential-Identifier, X-NNumbers-*, Forwarded, X-Forwarded-* e X-Real-IP.

Sem isso, um cliente poderia "afirmar" ser outro para o seu backend.

Use PUBLIC apenas para conteúdo realmente público: qualquer pessoa pode consumir, e o seu backend não deve confiar no IP de origem sem considerar proxies.

API_KEY

Como funciona:

1. O cliente manda a chave no cabeçalho escolhido pela política: x-api-key ou Ocp-Apim-Subscription-Key. O gateway remove o outro cabeçalho antes de autenticar — o modo é exclusivo, não aditivo — e nunca deixa a chave chegar ao seu backend.
2. O gateway valida a chave e identifica o consumidor.
3. O gateway confere se aquele consumidor está autorizado naquela API. Se não estiver: 403.
4. A chave nunca chega ao seu backend.

Detalhes que costumam surpreender:

• Só o cabeçalho configurado autentica. Se a API está em Ocp-Apim-Subscription-Key, um x-api-key enviado pelo cliente é removido antes da autenticação e a resposta é 401; o inverso também vale. Escolha o cabeçalho na política e documente-o para quem consome.
• Chave na query string não funciona. O gateway remove o argumento reservado __nn_key — e qualquer parâmetro com esse nome — antes de autenticar. Credencial na URL vaza em histórico de navegador, log de proxy e cabeçalho Referer.
• A chave é um segredo de alto valor: 32 bytes aleatórios. Guarde em cofre, não em código, não em log.
• Duas chaves ativas no mesmo consumidor funcionam ao mesmo tempo — é o que permite rotação sem queda.
• Chave de outra API, ou de outra organização, recebe 403 (não 401): a chave é válida, a autorização é que falta.

JWT_OIDC

O cliente apresenta um token do provedor de identidade dele. Configuração:

Campo	Regra
jwt.issuer	https, sem credencial embutida na URL; precisa bater exatamente com o iss do token
jwt.discovery_url	https, o documento de descoberta OIDC (/.well-known/openid-configuration)
jwt.audiences	pelo menos uma; o token precisa conter uma delas
jwt.required_scopes	opcional; lista de escopos exigidos
jwt.allowed_algorithms	exatamente um entre RS256, RS384 e RS512
jwt.clock_skew_seconds	0 a 120 (padrão 30)

issuer e discovery_url são validados também contra a política de destino na publicação: o host precisa resolver só para endereços públicos e não pode ser um nome interno. É o data plane que busca o documento de descoberta e as chaves, então o mesmo cuidado aplicado ao backend vale aqui (422 publish_validation_failed com jwt_idp_not_allowed:*).

O que é validado — e o que não é

Verificação	Quem faz	Observação
Assinatura (RSA)	gateway	chaves buscadas no JWKS do issuer, com cache de 1 h
iss	gateway	comparação exata com o issuer configurado
exp	gateway	com a tolerância configurada
aud	gateway	o token precisa conter uma das audiências da API
nbf	gateway	token "do futuro" → 401
scope/scp	gateway	scope como string separada por espaço, ou scp como string ou lista
Revogação por jti	não é feita	um token válido vale até expirar

Limitação declarada: só RSA

Apenas RS256, RS384 e RS512 são aceitos. Tokens assinados com ES256, ES384, ES512 ou PS* não são verificáveis pelo componente de autenticação do gateway nesta versão; o produto recusa a configuração em vez de aceitar e falhar em produção.

Se o seu provedor de identidade só emite ECDSA, o modo JWT_OIDC não é utilizável hoje — use API_KEY.

Detalhe técnico que vale saber

A validação é dividida em duas etapas: a primeira cuida de assinatura, iss e exp; a segunda (aud, nbf, escopos) roda logo depois, na mesma requisição. As duas são sempre geradas juntas. Não é possível montar uma API com apenas uma das duas.

JWT e chave de API juntas

Não está disponível nesta versão. É tecnicamente viável, mas não é anunciada até existir teste ponta a ponta. Não conte com isso.

Erros que o cliente vê

Resposta	Corpo (exemplo)	Quando
401	{"error":"invalid_token"}	token ausente, assinatura inválida, iss errado, exp vencido, nbf no futuro
401	corpo do componente de chave (não é contrato do produto)	chave ausente, inválida ou revogada, ou enviada no cabeçalho que a política não escolheu
403	{"error":"insufficient_scope"}	token válido sem os escopos exigidos
403	vazio	consumidor não autorizado naquela API (chave de outra API ou organização)
403	{"error":"api_suspended"}	organização suspensa

O contrato do produto não fixa o corpo do 401 no modo API_KEY: trate pelo status, não pelo corpo.

Escolhendo o modo

• Conteúdo aberto, sem custo por uso → PUBLIC.
• Serviço a serviço, parceiros, aplicações suas → API_KEY (mais simples de operar, rotação sem queda, autorização por API).
• Você já tem provedor OIDC com tokens RSA e quer que o gateway valide identidade de usuário final → JWT_OIDC.

Na dúvida, comece com API_KEY: é o modo com o ciclo de vida mais previsível.

Próximos passos

• Consumidores: quem é autorizado em cada API.
• Chaves de API: emissão, rotação e revogação.
• Como chamar uma API publicada: o cabeçalho certo em cada modo.