Autenticação

O TunnelHub suporta diferentes estratégias de autenticação para APIs, incluindo chaves de API e fluxos baseados em OAuth com Cognito.

Visão geral

As duas camadas mais comuns são:

• Chave de API + plano de uso para identificação e controle de consumo;
• OAuth com escopos para autenticação e autorização mais robustas.

Essas camadas podem coexistir, mas cumprem papéis diferentes. A chave de API ajuda a identificar e governar consumo; OAuth ajuda a autenticar e autorizar acesso a recursos protegidos.

Quando usar cada uma

Use apenas chave de API quando o cenário pede principalmente governança de consumo e o risco é menor.

Use OAuth quando:

• a API expõe dados sensíveis;
• existe necessidade de escopos finos;
• há múltiplos clientes com acessos diferentes;
• governança e auditoria são importantes.

Em cenários corporativos, o mais comum é combinar controle de consumo com autenticação forte.

Servidores de recursos

Servidores de recursos agrupam os escopos OAuth que protegem seus endpoints.

Cada servidor de recursos normalmente define:

• nome amigável;
• identificador único;
• lista de escopos com descrição.

Esses escopos podem ser associados a endpoints protegidos.

Clientes

Clientes representam aplicações consumidoras autenticadas. Eles são usados para cenários machine-to-machine e outros fluxos controlados pela plataforma.

Ao criar um cliente, você normalmente define:

• identificação do cliente;
• expiração de tokens;
• escopos autorizados.

Dependendo do caso, o fluxo também envolve rotação de segredo do cliente, ativação ou inativação e outros controles operacionais.

Fluxo prático mínimo

Um fluxo típico para uma API protegida costuma ser:

1. definir a API e seus endpoints;
2. decidir quais rotas exigem OAuth;
3. criar ou revisar o servidor de recursos;
4. criar o cliente consumidor;
5. autorizar os escopos corretos;
6. validar a obtenção de token e a chamada autenticada.

Geração de token

Dependendo do fluxo configurado, a aplicação consumidora troca suas credenciais por um access token e usa esse token para chamar endpoints protegidos.

Na prática, a documentação da API e a configuração do cliente devem deixar claro:

• endpoint de token;
• grant esperado;
• escopos permitidos;
• formato de envio das credenciais.

Boas práticas

• modele escopos com granularidade suficiente para refletir o negócio;
• evite compartilhar o mesmo cliente entre consumidores distintos;
• documente claramente quais rotas exigem escopos e quais usam apenas governança por chave;
• revise expiração de tokens conforme criticidade e perfil de integração;
• rotacione segredos de clientes sempre que houver suspeita de exposição.