Skip to content

设置自定义身份验证（第 1 部分/共 3 部分）

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

  1. 基本身份验证（您正在阅读此部分） - 控制谁可以访问您的机器人
  2. 资源授权 - 让用户进行私密对话
  3. 生产环境身份验证 - 添加真实用户账户并使用 OAuth2 进行验证

先决条件

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

仅支持 Python

目前，我们仅支持在使用 langgraph-api>=0.0.11 的 Python 部署中进行自定义身份验证和授权。很快将添加对 LangGraph.JS 的支持。

按部署类型提供的支持

托管的 LangGraph 云**中的所有部署以及 **企业版 自托管计划均支持自定义身份验证。精简版 自托管计划不支持。

在本教程中，我们将构建一个仅允许特定用户访问的聊天机器人。我们将从 LangGraph 模板开始，逐步添加基于令牌的安全机制。最后，您将拥有一个在允许访问之前会检查有效令牌的可运行聊天机器人。

搭建我们的项目

首先，让我们使用 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
如果一切正常，服务器应该会启动并在你的浏览器中打开工作室。

这个内存服务器是为开发和测试而设计的。 对于生产环境，请使用 LangGraph 云服务。

图表应该会运行，如果你要将其在公共互联网上进行自托管，任何人都可以访问它！

无身份验证

既然我们已经了解了基本的 LangGraph 应用程序，让我们为它添加身份验证功能吧！

占位令牌

在第一部分，为了便于说明，我们将从一个硬编码的令牌开始。 在掌握基础知识后，我们将在第三部分实现一个“适用于生产环境”的身份验证方案。

添加身份验证

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:
    """检查用户的令牌是否有效。"""
    assert authorization
    scheme, token = authorization.split()
    assert scheme.lower() == "bearer"
    # 检查令牌是否有效
    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. 检查请求的授权标头中是否提供了有效的令牌
  2. 返回用户的身份

现在，通过在 langgraph.json 配置中添加以下内容，告诉 LangGraph 使用我们的身份验证：

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

测试我们的“安全”机器人

让我们再次启动服务器来测试所有功能！

langgraph dev --no-browser
工作室中的自定义身份验证

如果你没有添加 --no-browser 参数，工作室用户界面将在浏览器中打开。你可能会想，工作室是如何仍然能够连接到我们的服务器的呢？默认情况下，即使使用自定义身份验证，我们也允许来自 LangGraph 工作室的访问。这使得在工作室中开发和测试你的机器人更加容易。你可以通过在身份验证配置中设置 disable_studio_auth: "true" 来移除这个替代身份验证选项： 

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

现在让我们尝试与我们的机器人聊天。如果我们正确实现了身份验证，那么只有在请求头中提供有效令牌时，我们才能访问该机器人。然而，在本教程的下一部分添加资源授权处理程序之前，用户仍然能够访问彼此的资源。

身份验证，无授权处理程序

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

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. 继续本教程，前往让对话私密化（第 2 部分/共 3 部分），了解资源授权相关内容。
  2. 进一步阅读认证概念。
  3. 查看API 参考文档，获取更多认证细节。

Comments