身份验证

在使用 HTTP 传输模式时，Neo4j MCP 服务器支持两种身份验证方法，以适应不同的部署场景

Bearer 令牌身份验证

Bearer 令牌身份验证可以与使用单点登录 (SSO)/OAuth/OIDC 进行身份管理的 Neo4j Enterprise Edition 和 Neo4j Aura 环境实现无缝集成。此方法非常适用于

  • 企业部署，使用集中式身份提供者（Okta、Azure AD 等）

  • Neo4j Aura 数据库已配置 SSO

  • 组织需要符合 OAuth 2.0 标准

  • 多因素身份验证 场景

Bearer 令牌从您的身份提供者获取后传递给 Neo4j 进行身份验证。MCP 服务器充当中转，将令牌转发至 Neo4j 的身份验证系统。

基本身份验证

传统的用户名/密码身份验证，适用于

  • Neo4j 社区版

  • 开发和测试 环境

  • 直接的数据库凭证（无 SSO）

我应该使用哪种身份验证方法？

使用 Bearer Token 时

  • 您使用的是已配置 SSO/OIDC/OAuth 的 Neo4j Enterprise Edition 或 Aura

  • 您希望与组织的身份提供者集成

  • 您需要支持 OAuth 2.0 流程

使用 Basic Auth 时

  • 您使用传统的用户名/密码身份验证

  • 您使用 Neo4j Community Edition

  • 您拥有直接的数据库凭证

身份验证故障排除

Bearer 令牌问题

401 未授权 - 令牌未被接受

  • 确认您的 Neo4j 实例是已配置 OAuth/SSO 的 Enterprise Edition 或 Aura

  • Community Edition 不支持 Bearer 令牌身份验证 - 请改用 Basic Auth

  • 确认令牌未过期 - Bearer 令牌通常寿命较短（15-60 分钟）

  • 向您的身份提供者确认令牌有效

令牌格式无效

  • 确保请求头格式正好为：Authorization: Bearer YOUR_TOKEN

  • “Bearer” 前后不能有多余空格

  • 令牌不应进行 base64 编码（不同于 Basic Auth）

Neo4j 拒绝有效令牌

  • 确认您的 Neo4j 实例已配置为接受来自身份提供者的令牌

  • 检查 Neo4j 服务器日志，寻找具体的身份验证错误

  • 确认令牌发行者与 Neo4j 的 OAuth 配置相匹配

Basic Auth 问题

401 未授权 - 凭证未被接受

  • 确认用户名和密码正确

  • 检查凭证是否正确进行 base64 编码：echo -n "user:pass" | base64

  • 确保授权头格式为：Authorization: Basic BASE64_STRING

空凭证错误

  • 用户名和密码均不能为空

  • base64 字符串必须解码为 username:password 格式，并且两部分都必须存在

常见问题

未提供身份验证头

  • HTTP 模式下每个请求都需要身份验证

  • 确保您的 MCP 客户端配置包含 Authorization 头

连接被拒绝 / 无法到达服务器

  • 确认 Neo4j MCP 服务器已在 HTTP 模式下运行

  • 检查服务器是否在正确的 host:port 上监听

  • 确认防火墙规则允许连接至 MCP 服务器端口