Configurar autenticação Bearer no servidor MCP

Com a especificação MCP mais recente, seu servidor MCP atua como um Servidor de Recursos que valida tokens de acesso para recursos protegidos. O MCP Auth oferece várias formas de configurar a autorização Bearer:

• Modo JWT (JSON Web Token): Um método de autorização integrado que verifica JWTs com afirmações de reivindicações.
• Modo personalizado: Permite implementar sua própria lógica de autorização.

O middleware de autenticação Bearer agora exige a especificação de qual recurso o endpoint pertence, permitindo a validação adequada do token em relação aos servidores de autorização configurados.

Configurar autenticação Bearer com modo JWT

Se seu provedor OAuth / OIDC emite JWTs para autorização, você pode usar o modo JWT integrado no MCP Auth. Ele verifica a assinatura do JWT, expiração e outras reivindicações que você especificar; em seguida, preenche as informações de autenticação no contexto da requisição para processamento posterior em sua implementação MCP.

Validação de escopo e público (Scope and audience validation)

Validação de público (Audience Validation)

O parâmetro audience é obrigatório pela especificação OAuth 2.0 para validação segura de tokens. No entanto, atualmente é opcional para manter a compatibilidade com servidores de autorização que ainda não suportam identificadores de recursos. Por motivos de segurança, sempre inclua o parâmetro audience quando possível. Versões futuras tornarão a validação de público obrigatória para cumprir totalmente a especificação.

Sempre valide os escopos

No OAuth 2.0, os escopos (Scopes) são o principal mecanismo de controle de permissões. Um token válido com o audience correto NÃO garante que o usuário tenha permissão para realizar uma ação — servidores de autorização podem emitir tokens com escopo vazio ou limitado.

Sempre use requiredScopes para garantir que o token contenha as permissões necessárias para cada operação. Nunca assuma que um token válido implica acesso total.

Aqui está um exemplo da validação básica de escopo e público:

import express from 'express';
import { MCPAuth } from 'mcp-auth';

const app = express();
const mcpAuth = new MCPAuth({
  /* ... */
});
const bearerAuth = mcpAuth.bearerAuth('jwt', {
  resource: 'https://api.example.com', // Especifique a qual recurso este endpoint pertence
  audience: 'https://api.example.com', // Habilite a validação de público para segurança
  requiredScopes: ['read', 'write'],
});

app.use('/mcp', bearerAuth, (req, res) => {
  // Agora `req.auth` contém as informações de autenticação
  console.log(req.auth);
});

No exemplo acima:

• O parâmetro audience valida a reivindicação aud no JWT para garantir que o token foi emitido especificamente para o recurso do seu servidor MCP. O valor do público geralmente deve corresponder ao identificador do seu recurso.
• O parâmetro requiredScopes especifica que o JWT requer os escopos read e write. Se o token não contiver todos esses escopos, um erro será lançado.

Fornecer opções personalizadas para a verificação do JWT

Você também pode fornecer opções personalizadas para a biblioteca de verificação JWT subjacente. No SDK Node.js, usamos a biblioteca jose para verificação de JWT. Você pode fornecer as seguintes opções:

• jwtVerify: Opções para o processo de verificação do JWT (função jwtVerify do jose).
• remoteJwtSet: Opções para buscar o conjunto remoto de JWT (função createRemoteJWKSet do jose).

const bearerAuth = mcpAuth.bearerAuth('jwt', {
  resource: 'https://api.example.com',
  audience: 'https://api.example.com',
  requiredScopes: ['read', 'write'],
  jwtVerify: {
    clockTolerance: 60, // Permite uma diferença de relógio de 60 segundos
  },
  remoteJwtSet: {
    timeoutDuration: 10 * 1000, // Timeout de 10 segundos para busca do conjunto remoto de JWT
  },
});

Configurar autenticação Bearer com verificação personalizada

Se seu provedor OAuth / OIDC não emite JWTs, ou se você deseja implementar sua própria lógica de autorização, o MCP Auth permite criar uma função de verificação personalizada:

info

Como o middleware de autenticação Bearer verificará o emissor (iss), público (aud) e escopos necessários (scope) com o resultado da verificação fornecido, não há necessidade de implementar essas verificações em sua função de verificação personalizada. Você pode focar em verificar a validade do token (por exemplo, assinatura, expiração, etc.) e retornar o objeto de informações de autenticação.

const bearerAuth = mcpAuth.bearerAuth(
  async (token) => {
    // Implemente sua lógica personalizada de verificação aqui
    const info = await verifyToken(token);
    if (!info) {
      throw new MCPAuthJwtVerificationError('jwt_verification_failed');
    }
    return info; // Retorne o objeto de informações de autenticação
  },
  {
    resource: 'https://api.example.com',
    audience: 'https://api.example.com', // Habilite a validação de público para segurança
    requiredScopes: ['read', 'write']
  }
);

Aplicar autenticação Bearer em seu servidor MCP

Para proteger seu servidor MCP com autenticação Bearer, você precisa aplicar o middleware de autenticação Bearer à sua instância do servidor MCP.

const app = express();
app.use(mcpAuth.bearerAuth('jwt', {
  resource: 'https://api.example.com',
  audience: 'https://api.example.com', // Habilite a validação de público para segurança
  requiredScopes: ['read', 'write']
}));

Isso garantirá que todas as requisições recebidas sejam autenticadas e autorizadas de acordo com as configurações de autenticação Bearer, e as informações de autenticação estarão disponíveis no contexto da requisição.

Você pode então acessar as informações em sua implementação do servidor MCP:

// `authInfo` será carregado a partir do objeto `req.auth`
server.registerTool(
  'whoami',
  {
    description: 'Retorna as informações do usuário atual',
    inputSchema: {},
  },
  ({ authInfo }) => {
    console.log(`Usuário autenticado: ${authInfo.subject}`);
    return { subject: authInfo.subject };
  }
);