设置自定义身份验证

在本教程中，我们将构建一个只允许特定用户访问的聊天机器人。我们将从 LangGraph 模板开始，逐步添加基于令牌的安全功能。最终，你将拥有一个在允许访问前会检查有效令牌的可工作聊天机器人。这是我们身份验证系列教程的第一部分：

设置自定义身份验证（你正在阅读此处） - 控制谁可以访问你的机器人
使对话私有化 - 让用户拥有私人对话
连接身份验证提供者 - 为生产环境添加真实用户账户并使用 OAuth2 进行验证

本指南假定你基本熟悉以下概念：

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

1. 创建你的应用

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

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

uv add "langgraph-cli[inmem]"
langgraph new --template=new-langgraph-project-python custom-auth
cd custom-auth

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

pip install -e .
langgraph dev

uv add .
langgraph dev

npx @langchain/langgraph-cli 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
>
> 此内存服务器设计用于开发和测试。
> 生产环境请使用 LangSmith。

如果你将其部署在公共互联网上，任何人都可以访问它。未启用身份验证：开发服务器可公开访问，如果暴露在互联网上，任何人都可以访问该机器人。

2. 添加身份验证

现在你有了一个基础的 LangGraph 应用，让我们为其添加身份验证功能。

在本教程中，为示例目的，你将从一个硬编码的令牌开始。你将在第三篇教程中获得一个“生产就绪”的身份验证方案。

Auth 对象允许你注册一个身份验证函数，LangSmith 部署将在每个请求上运行此函数。该函数接收每个请求并决定是接受还是拒绝。创建一个新文件 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"],
    }

请注意，你的 Auth.authenticate 处理器做了两件重要的事情：

检查请求的 Authorization 头中是否提供了有效的令牌。
返回用户的 MinimalUserDict。

现在，通过将以下内容添加到 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 的访问。这使得在 Studio 中开发和测试你的机器人更加容易。你可以通过在身份验证配置中设置 disable_studio_auth: true 来移除此备用身份验证选项：

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

4. 与你的机器人聊天

现在，只有当你在请求头中提供有效的令牌时，才能访问该机器人。然而，在你在下一节教程中添加资源授权处理器之前，用户仍然能够访问彼此的资源。身份验证门通过了带有有效令牌的请求，但尚未应用针对特定资源的过滤器——因此在下一步添加授权处理器之前，用户共享可见性。

在文件或 Notebook 中运行以下代码：

import asyncio

from langgraph_sdk import get_client


async def main():
    # 尝试不带令牌（应该失败）
    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": "你好！"}]},
    )
    print("✅ 机器人响应：")
    print(response)


if __name__ == "__main__":
    asyncio.run(main())

你应该会看到：

没有有效的令牌，我们无法访问该机器人。
有了有效的令牌，我们可以创建线程并进行对话。

恭喜！你已经构建了一个只允许“已认证”用户访问的聊天机器人。虽然这个系统尚未实现一个生产就绪的安全方案，但我们已经学习了如何控制对机器人访问的基本机制。在下一个教程中，我们将学习如何为每个用户提供他们自己的私人对话。

后续步骤

既然你可以控制谁访问你的机器人了，你可能想要：

继续本教程，前往使对话私有化以了解资源授权。
阅读更多关于身份验证概念。
查看 Auth、Auth.authenticate 和 MinimalUserDict 的 API 参考，了解更多身份验证细节。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Develop your application

Capabilities

How to build

Auth & access control

Server customization

1. 创建你的应用

2. 添加身份验证

3. 测试你的机器人

4. 与你的机器人聊天

后续步骤

​1. 创建你的应用

​2. 添加身份验证

​3. 测试你的机器人

​4. 与你的机器人聊天

​后续步骤

1. 创建你的应用

2. 添加身份验证

3. 测试你的机器人

4. 与你的机器人聊天

后续步骤