Skip to content

设置自定义身份验证

在本教程中，我们将构建一个只能让特定用户访问的聊天机器人。我们将从 LangGraph 模板开始，并逐步添加基于令牌的安全性。最终，您将获得一个可以检查有效令牌后再允许访问的聊天机器人。

这是我们的身份验证系列的第一部分：

  1. 设置自定义身份验证（您当前所在位置） - 控制谁可以访问您的机器人
  2. 使对话私有 - 让用户拥有私有对话
  3. 连接身份验证提供者 - 为生产环境添加真实用户账户并使用 OAuth2 进行验证

本指南假定您对以下概念有基本的了解：

Note

自定义身份验证仅适用于 LangGraph 平台 SaaS 部署或企业自托管部署。

1. 创建你的应用

使用 LangGraph 启动模板创建一个新的聊天机器人：

pip install -U "langgraph-cli[inmem]"
langgraph new --template=new-langgraph-project-python custom-auth
cd custom-auth

该模板为我们提供了一个占位符 LangGraph 应用。通过安装本地依赖并运行开发服务器来试用它：

pip install -e .
langgraph dev

服务器将启动并在浏览器中打开 studio 界面：

> - 🚀 API: http://127.0.0.1:2024
> - 🎨 Studio UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
> - 📚 API Docs: http://127.0.0.1:2024/docs
> 
> 此内存服务器是为开发和测试设计的。
> 如需生产环境使用，请使用 LangGraph 平台。

如果你在公共互联网上自行托管此服务，任何人都可以访问它！

无认证

2. 添加认证

现在你已经有了一个基础的 LangGraph 应用，接下来为其添加认证功能。

Note

在本教程中，你将使用一个硬编码的 token 作为示例。在第三个教程中，你将实现一个“生产就绪”的认证方案。

Auth 对象允许你注册一个认证函数，LangGraph 平台将在每次请求时运行该函数。这个函数接收每个请求，并决定是否接受或拒绝。

创建一个新文件 src/security/auth.py。这将是你的代码所在的位置，用于检查用户是否有权限访问你的机器人：

src/security/auth.py
from langgraph_sdk import Auth

# 这是一个玩具用户数据库。不要在生产环境中这样做
VALID_TOKENS = {
    "user1-token": {"id": "user1", "name": "Alice"},
    "user2-token": {"id": "user2", "name": "Bob"},
}

# "Auth" 对象是 LangGraph 用来标记我们认证函数的容器
auth = Auth()


# `authenticate` 装饰器告诉 LangGraph 将此函数作为中间件
# 用于每个请求。这将决定请求是否被允许
@auth.authenticate
async def get_current_user(authorization: str | None) -> Auth.types.MinimalUserDict:
    """检查用户的 token 是否有效。"""
    assert authorization
    scheme, token = authorization.split()
    assert scheme.lower() == "bearer"
    # 检查 token 是否有效
    if token not in VALID_TOKENS:
        raise Auth.exceptions.HTTPException(status_code=401, detail="Invalid token")

    # 如果有效，返回用户信息
    user_data = VALID_TOKENS[token]
    return {
        "identity": user_data["id"],
    }

请注意，你的 认证 处理程序做了两件重要的事情：

  1. 检查请求中的 Authorization header 是否提供了有效的 token
  2. 返回用户的 身份

现在通过向 langgraph.json 配置文件中添加以下内容，告诉 LangGraph 使用认证：

langgraph.json
{
  "dependencies": ["."],
  "graphs": {
    "agent": "./src/agent/graph.py:graph"
  },
  "env": ".env",
  "auth": {
    "path": "src/security/auth.py:auth"
  }
}

3. 测试你的机器人

再次启动服务器以测试所有内容：

langgraph dev --no-browser

如果你没有添加 --no-browser，那么 studio UI 将会在浏览器中打开。你可能会疑惑，为什么 studio 仍然能够连接到我们的服务器？默认情况下，即使使用自定义身份验证，我们也允许来自 LangGraph studio 的访问。这使得在 studio 中开发和测试你的机器人更加方便。你可以通过在身份验证配置中设置 disable_studio_auth: "true" 来移除这个替代的身份验证选项：

{
    "auth": {
        "path": "src/security/auth.py:auth",
        "disable_studio_auth": "true"
    }
}

4. 与你的机器人聊天

你现在只有在请求头中提供有效的令牌时，才能访问机器人。然而，用户仍然可以访问彼此的资源，直到你在教程的下一部分添加资源授权处理程序。

认证，没有授权处理程序

在文件或笔记本中运行以下代码：

from langgraph_sdk import get_client

# 不带令牌尝试（应该失败）
client = get_client(url="http://localhost:2024")
try:
    thread = await client.threads.create()
    print("❌ 没有令牌时应该失败！")
except Exception as e:
    print("✅ 正确阻止了访问:", e)

# 带有效令牌尝试
client = get_client(
    url="http://localhost:2024", headers={"Authorization": "Bearer user1-token"}
)

# 创建线程并聊天
thread = await client.threads.create()
print(f"✅ 以Alice身份创建线程: {thread['thread_id']}")

response = await client.runs.create(
    thread_id=thread["thread_id"],
    assistant_id="agent",
    input={"messages": [{"role": "user", "content": "Hello!"}]},
)
print("✅ 机器人已响应:")
print(response)

你应该看到：

  1. 没有有效令牌时，无法访问机器人
  2. 有有效令牌时，可以创建线程并聊天

恭喜！你已经构建了一个只允许“已认证”用户访问的聊天机器人。虽然这个系统目前还没有实现生产级的安全方案，但我们已经学习了如何控制对机器人访问的基本机制。在下一个教程中，我们将学习如何让每个用户拥有自己的私密对话。

下一步

现在你已经可以控制谁可以访问你的机器人，你可能想要：

  1. 继续教程，前往 Make conversations private 了解资源授权的相关知识。
  2. 阅读更多关于 认证概念 的内容。
  3. 查看 API 参考 以获取更多认证细节。