Skip to content

如何在OpenAPI中记录API认证

本指南展示了如何为您的LangGraph平台API文档自定义OpenAPI安全模式。一个记录良好的安全模式有助于API使用者了解如何与您的API进行身份验证，甚至可以启用自动客户端生成。有关LangGraph认证系统的更多细节，请参阅认证与访问控制概念指南。

实现与文档

本指南仅涵盖如何在OpenAPI中记录您的安全需求。要实现实际的身份验证逻辑，请参阅如何添加自定义认证。

本指南适用于所有LangGraph平台部署（云、自带运行环境和自托管）。如果您不使用LangGraph平台，则本指南不适用于使用LangGraph开源库的情况。

默认安全方案

默认的安全方案因部署类型而异：

默认情况下，LangGraph Cloud要求在x-api-key头中提供LangSmith API密钥：

components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
security:
  - apiKeyAuth: []

当使用LangGraph SDK之一时，可以通过环境变量推断出该密钥。

默认情况下，自托管部署没有任何安全方案。这意味着它们只能部署在受保护的网络或带有身份验证的环境中。要添加自定义身份验证，请参见如何添加自定义身份验证。

自定义安全方案

为了在您的OpenAPI文档中自定义安全方案，请在langgraph.json中的auth配置中添加一个openapi字段。请注意，这仅更新API文档，您还必须实现相应的身份验证逻辑，如在如何添加自定义身份验证中所示。

请注意，LangGraph平台不提供身份验证端点，您需要在客户端应用程序中处理用户身份验证，并将结果凭证传递给LangGraph API。

{
  "auth": {
    "path": "./auth.py:my_auth",  // 在此处实现身份验证逻辑
    "openapi": {
      "securitySchemes": {
        "OAuth2": {
          "type": "oauth2",
          "flows": {
            "implicit": {
              "authorizationUrl": "https://your-auth-server.com/oauth/authorize",
              "scopes": {
                "me": "读取当前用户的信息",
                "threads": "访问创建和管理线程"
              }
            }
          }
        }
      },
      "security": [
        {"OAuth2": ["me", "threads"]}
      ]
    }
  }
}

{
  "auth": {
    "path": "./auth.py:my_auth",  // 在此处实现身份验证逻辑
    "openapi": {
      "securitySchemes": {
        "apiKeyAuth": {
          "type": "apiKey",
          "in": "header",
          "name": "X-API-Key"
        }
      },
      "security": [
        {"apiKeyAuth": []}
      ]
    }
  }
}

测试

更新配置后：

  1. 部署你的应用程序
  2. 访问 /docs 查看更新后的 OpenAPI 文档
  3. 使用身份验证服务器的凭证尝试端点（确保你已经实现了身份验证逻辑）

Comments