Arcade MCP: Mecanismos de Segurança OAuth 2.1 e Proteção com Tokens JWT

No cenário atual de integração de ferramentas de IA, a segurança do Arcade MCP oferece aos desenvolvedores soluções de autenticação e autorização de nível empresarial. Como um framework de servidor MCP de código aberto, o Arcade MCP implementa uma arquitetura de segurança de protocolo duplo, suportando tanto a validação padrão OAuth 2.1 quanto a proteção específica de tokens JWT para o Arcade Engine.

Arquitetura de Segurança de Protocolo Duplo

O design de segurança central do Arcade MCP baseia-se em uma estratégia de defesa em camadas, fornecendo mecanismos de proteção direcionados para diferentes cenários de uso:

Camada de Protocolo MCP: Validação do Servidor de Recursos OAuth 2.1

Ao utilizar o modo de transporte HTTP, o Arcade MCP suporta a validação do servidor de recursos OAuth 2.1, um padrão de segurança de API moderno. Através da classe ResourceServerAuth, você pode configurar múltiplos servidores de autorização, permitindo a autenticação multi-tenant e um modelo de segurança de confiança zero.

Configuração Central do Exemplo


from arcade_mcp_server.resource_server import ResourceServerAuth, AuthorizationServerEntry

resource_server_auth = ResourceServerAuth(
    canonical_url="https://mcp.example.com/mcp",
    authorization_servers=[
        AuthorizationServerEntry(
            authorization_server_url="https://auth.example.com",
            issuer="https://auth.example.com",
            jwks_uri="https://auth.example.com/.well-known/jwks.json",
            algorithm="RS256",
            expected_audiences=["client-id"],
        )
    ],
    scopes_supported=["mcp", "offline_access"],
    default_challenge_scopes=["mcp", "offline_access"],
)

Camada de Protocolo Arcade Worker: Validação de Token JWT HS256

Quando a variável de ambiente ARCADE_WORKER_SECRET é definida, o Arcade MCP habilita automaticamente o endpoint do protocolo Worker (/worker/*), utilizando tokens JWT com o algoritmo HS256 para autenticação. Este mecanismo é projetado para comunicação interna do Arcade Engine, oferecendo uma forma de autenticação leve e segura.

Fluxo de Validação do Worker JWT

  1. Geração do Token: O Arcade Engine assina o JWT com uma chave secreta compartilhada.
  2. Validação do Token: O servidor verifica a assinatura, o público e a versão.
  3. Controle de Acesso: Acesso ao endpoint do Worker é concedido após a validação bem-sucedida.

Configuração Segura de Variáveis de Ambiente

A configuração de segurança do Arcade MCP depende fortemente de variáveis de ambiente, garantindo que informações sensíveis não sejam codificadas diretamente no código:

Variáveis de Ambiente de Segurança Chave

Nome da Variável Uso Nível de Segurança
ARCADE_WORKER_SECRET Chave secreta para assinatura do Worker JWT Segredo Máximo
MCP_RESOURCE_SERVER_CANONICAL_URL URL canônica do servidor de recursos OAuth Sensível
MCP_RESOURCE_SERVER_AUTHORIZATION_SERVERS Configuração do servidor de autorização Sensível
ARCADE_API_KEY Chave de API do Arcade Cloud Segredo Máximo

Melhores Práticas de Segurança

  1. Utilize arquivos .env: Armazene configurações sensíveis em um arquivo .env e use find_env_file() para descoberta automática.
  2. Rotação de Chaves: Atualize periodicamente o ARCADE_WORKER_SECRET para implementar uma estratégia de rotação de chaves.
  3. Princípio do Menor Privilégio: Utilize chaves e configurações distintas para diferentes ambientes.

Análise Detalhada da Validação OAuth 2.1

Validação de URL Canônica

O Arcade MCP impõe uma validação rigorosa em canonical_url, garantindo a conformidade com o RFC 9728:

  • Requisito HTTPS: HTTPS deve ser usado em ambientes de produção.
  • Exceção de Loopback: Apenas 127.0.0.1, ::1, e localhost podem usar HTTP.
  • Regra Sem Fragmento: Componentes de fragmento de URL (RFC 8707) são proibidos.

Estratégia de Gerenciamento de Escopos

O Arcade MCP implementa gerenciamento de escopos em dois níveis, em conformidade com a especificação MCP 2025-11-25:

Nível de Escopo Campo de Configuração Uso
Escopo de Anúncio PRM scopes_supported Metadados de recursos protegidos RFC 9728
Escopo de Desafio de Entrada default_challenge_scopes Cabeçalho WWW-Authenticate RFC 6750

Configuração Recomendada: Use o mesmo conjunto mínimo de escopos em ambos os níveis, seguindo o princípio da minimização de escopos. Quando uma ferramenta necessita de permissões adicionais, a autorização incremental 403 é acionada via InsufficientScopeError.

Suporte a Múltiplos Servidores de Autorização

O Arcade MCP suporta a configuração simultânea de múltiplos servidores de autorização, aplicável para:

  • Janelas de Migração: Sistemas de autenticação antigos e novos operando em paralelo.
  • Ambientes Multi-Tenant: Clientes diferentes utilizando IdPs distintos.
  • Alta Disponibilidade: Alternância entre servidores de autenticação primários e secundários.

# Exemplo de configuração multi-IdP
resource_server_auth = ResourceServerAuth(
    canonical_url="https://mcp.example.com/mcp",
    authorization_servers=[
        AuthorizationServerEntry(  # AS Intermediário Arcade
            authorization_server_url="https://cloud.arcade.dev/oauth2",
            issuer="https://cloud.arcade.dev/oauth2",
            jwks_uri="https://cloud.arcade.dev/.well-known/jwks/oauth2",
            algorithm="Ed25519",
            expected_audiences=["urn:arcade:mcp", canonical_url],
        ),
        AuthorizationServerEntry(  # WorkOS Authkit
            authorization_server_url="https://your-workos.authkit.app",
            issuer="https://your-workos.authkit.app",
            jwks_uri="https://your-workos.authkit.app/oauth2/jwks",
            expected_audiences=["your-authkit-client-id"],
        ),
        AuthorizationServerEntry(  # Keycloak
            authorization_server_url="http://localhost:8080/realms/mcp-test",
            issuer="http://localhost:8080/realms/mcp-test",
            jwks_uri="http://localhost:8080/realms/mcp-test/protocol/openid-connect/certs",
            algorithm="RS256",
            expected_audiences=["your-keycloak-client-id"],
        )
    ],
)

Autenticação em Nível de Ferramenta e Gerenciamento de Segredos

Autenticação de Ferramenta OAuth

O Arcade MCP possui 22 provedores OAuth pré-configurados para simplificar a autenticação de ferramentas:


from arcade_mcp_server.auth import GitHub, Google, Microsoft

@app.tool(requires_auth=GitHub(scopes=["repo"]))
async def list_repos(context: Context) -> list[str]:
    """Lista os repositórios GitHub do usuário."""
    token = context.get_auth_token_or_empty()
    # Chamar a API do GitHub usando o token

@app.tool(requires_auth=Google(scopes=["gmail.readonly"]))
async def read_emails(context: Context) -> list[dict]:
    """Lê os e-mails do Gmail."""
    token = context.get_auth_token_or_empty()
    # Chamar a API do Gmail usando o token

Mecanismo de Injeção de Segredos

As ferramentas declaram os segredos necessários através de requires_secrets, e o Arcade MCP os injeta de forma segura em tempo de execução:


@app.tool(requires_secrets=["API_KEY", "DATABASE_PASSWORD"])
def process_data(context: Context) -> str:
    """Processa dados usando a chave da API e a senha do banco de dados."""
    api_key = context.get_secret("API_KEY")
    db_password = context.get_secret("DATABASE_PASSWORD")
    # Utiliza os segredos de forma segura

Recursos de Segurança Importantes: ARCADE_WORKER_SECRET e ARCADE_API_KEY são segredos reservados e nunca são injetados no contexto da ferramenta, prevenindo ataques de escalonamento de privilégios.

Cadeia de Middleware de Segurança

O Arcade MCP constrói múltiplas camadas de middleware de segurança para proteger cada estágio do processamento de requisições:

1. Middleware do Servidor de Recursos

ResourceServerMiddleware lida com a validação do token Bearer OAuth 2.1:

  • Validação de Token: Verifica a assinatura, emissor, público e validade.
  • Validação de Escopo: Garante que o token contenha os escopos necessários.
  • Tratamento de Erros: Retorna os códigos de status HTTP 401/403 apropriados.

2. Middleware de Autenticação do Worker

Quando ARCADE_WORKER_SECRET é definido, a proteção do endpoint do Worker é habilitada automaticamente:

  • Validação JWT: Usa o algoritmo HS256 para verificar a assinatura.
  • Verificação de Versão: Garante a compatibilidade da versão do token (atualmente "1").
  • Validação de Público: Verifica a declaração audience="worker".

3. Middleware de Rastreamento de Tarefas

TaskTrackerMiddleware garante desligamento gracioso e cancelamento de requisições:

  • Tratamento Duplo de SIGINT: Primeiro desligamento gracioso, segundo encerramento forçado.
  • Rastreamento de Requisições Ativas: Cancela todas as requisições em andamenot.
  • Limpeza de Recursos: Garante a ausência de vazamentos de memória.

Monitoramento e Depuração de Segurança

Flags de Depuração (Ambiente de Desenvolvimento Apenas)

O Arcade MCP oferece flags de depuração para auxiliar os desenvolvedores na depuração de problemas de segurança localmente:

Variável de Ambiente Uso Aviso de Segurança
ARCADE_DEBUG_EXPOSE_DEVELOPER_MESSAGE_IN_TOOL_ERROR_RESPONSES Inclui mensagens do desenvolvedor em respostas de erro de ferramenta. ⚠️ Pode vazar informações internas.
ARCADE_DEBUG_EXPOSE_STACKTRACE_IN_TOOL_ERROR_RESPONSES Inclui rastreamentos de pilha em respostas de erro de ferramenta. ⚠️ Pode vazar informações internas.

Importante: Essas flags devem ser definidas com o valor exato yes-i-accept-leaking-internals-to-the-agent e nunca devem ser usadas em ambientes de produção.

Registro em Log

O Arcade MCP fornece registro em log detalhado para ajudar a diagnosticar problemas de segurança:

  • Falha na Validação do Token: Registra assinaturas inválidas, tokens expirados, etc.
  • Erros de Escopo Insuficiente: Registra eventos de autorização incremental 403.
  • Problemas de Configuração: Registra configurações de segurança ausentes ou inválidas.

Guia de Implantação em Produção

1. Imposição de HTTPS


# HTTPS deve ser usado em ambientes de produção
canonical_url = "https://mcp.yourcompany.com/mcp"

2. Gerenciamento de Chaves

  • Use um Serviço de Gerenciamento de Chaves: Como AWS KMS, Azure Key Vault, Google KMS.
  • Injeção de Variáveis de Ambiente: Injete segredos através da plataforma de orquestração de contêineres.
  • Rotação Periódica: Implemente uma estratégia de rotação de chaves automatizada.

3. Isolamento de Rede

  • Rede Privada: Implante o servidor MCP em uma sub-rede privada.
  • Gateway de API: Exponha endpoints através de um gateway de API para rate limiting e WAF.
  • Endpoints VPC: Use endpoints VPC para evitar exposição à rede pública.

4. Monitoramento e Alertas

  • Monitoramento de Uso de Token: Rastreie tentativas de autenticação bem-sucedidas/falhas.
  • Detecção de Anomalias: Detecte padrões de acesso incomuns.
  • Logs de Eventos de Segurança: Centralize e analise logs de segurança.

Testes e Verificação de Segurança

Cobertura de Teste Unitário

O Arcade MCP inclui testes de segurança abrangentes:

  • Testes de Validação de Token: Manipulação de tokens válidos/inválidos/expirados.
  • Testes de Validação de Escopo: Cenários de autorização incremental.
  • Testes de Validação de Configuração: Verificação de formato de URL, sintaxe de escopo.

Estratégia de Teste de Integração

  1. Testes de Ponta a Ponta: Simule o fluxo OAuth completo.
  2. Testes Negativos: Teste cenários como tokens inválidos, escopos ausentes, etc.
  3. Testes de Limite: Teste condições de limite como expiração de token, desvios de relógio.

Compensações entre Desempenho e Segurança

O Arcade MCP alcança um equilíbrio cuidadoso entre segurança e desempenho:

Estratégia de Cache

  • Cache JWKS: TTL padrão de 3600 segundos para reduzir consultas ao servidor de autorização.
  • Cache de Validação de Token: Cache de curto prazo para tokens já validados.
  • Cache de Configuração: Evita a aálise repetida de variáveeis de ambiente.

Processamento Assíncrono

Todas as operações de segurança são projetadas para serem não bloqueantes e assíncronas, garantindo desempenho em cenários de alta concorrência:

  • Validação Assíncrona de Token: Não bloqueia o loop de eventos.
  • Consultas Paralelas a Servidores de Autorização: Suporta validação simultânea de múltiplos IdPs.
  • Tratamento de Erros em Streaming: Falha rápida, reduzindo o consumo de recursos.

Resumo: Melhores Práticas para Construir Servidores de Ferramentas de IA Seguros

O Arcade MCP fornece um framework de segurança de nível empresarial, permitindo que os desenvolvedores se concentrem na lógica da ferramenta em vez da infraestrutura de segurança. Ao seguir as melhores práticas a seguir, você pode construir servidores MCP seguros e de alto desempenho:

  1. Sempre use HTTPS: Desabilite HTTP em ambientes de produção.
  2. Implemente o Princípio do Menor Privilégio: As ferramentas devem solicitar apenas os escopos OAuth necessários.
  3. Habilite Autenticação Dupla: Suporte simultâneo a OAuth MCP e JWT do Worker.
  4. Realize Auditorias de Segurança Regulares: Revise o uso de tokens e padrões de acesso.
  5. Estabeleça Monitoramento e Alertas: Crie monitoramento de segurança proativo.

Com a arquitetura de segurança em camadas e as opções de configuração flexíveis do Arcade MCP, você pode facilmente construir uma plataforma de integração de ferramentas de IA que atenda aos padrões de segurança corporativos, mantendo a eficiência de desenvolvimento e a flexibilidade de implantação.

A segurança é um processo, não um destino. À medida que o Arcade MCP evolui, seus recursos de segurança continuarão a se desenvolver, fornecendo proteção mais robusta para a integração de ferramentas de IA. Comece a usar o Arcade MCP hoje para construir uma linha de defesa impenetrável para suas aplicações de IA!

Tags: OAuth 2.1 jwt segurança de API microserviços autenticacao

Publicado em 8-23 13:28

Tags em Destaque

©2026 Doido Dev