本指南将向您展示如何为您的 LangSmith 应用程序添加自定义身份验证。本页的步骤适用于云部署和自托管部署。这不适用于在您自己的自定义服务器中独立使用 LangGraph 开源库。

为您的部署添加自定义身份验证

为了在您的部署中利用自定义身份验证并访问用户级别的元数据，请设置自定义身份验证，通过自定义身份验证处理器自动填充 config["configurable"]["langgraph_auth_user"] 对象。然后，您可以在您的图中使用 langgraph_auth_user 键访问此对象，以允许代理代表用户执行经过身份验证的操作。

1. 实现身份验证：

如果没有自定义的 @auth.authenticate 处理器，LangGraph 只能看到 API 密钥的所有者（通常是开发者），因此请求不会限定到单个最终用户。要传播自定义令牌，您必须实现自己的处理器。

from langgraph_sdk import Auth
import requests

auth = Auth()

def is_valid_key(api_key: str) -> bool:
    is_valid = # 您的 API 密钥验证逻辑
    return is_valid

@auth.authenticate # (1)!
async def authenticate(headers: dict) -> Auth.types.MinimalUserDict:
    api_key = headers.get(b"x-api-key")
    if not api_key or not is_valid_key(api_key):
        raise Auth.exceptions.HTTPException(status_code=401, detail="Invalid API key")

    # 从您的密钥存储中获取用户特定的令牌
    user_tokens = await fetch_user_tokens(api_key)

    return { # (2)!
        "identity": api_key,  #  从 LangSmith 获取用户 ID
        "github_token" : user_tokens.github_token
        "jira_token" : user_tokens.jira_token
        # ... 自定义字段/密钥放在这里
    }

• 此处理器接收请求（请求头等），验证用户，并返回一个至少包含 identity 字段的字典。
• 您可以添加任何您想要的自定义字段（例如，OAuth 令牌、角色、组织 ID 等）。

2. 在您的 langgraph.json 中，添加您的身份验证文件的路径：

{
    "dependencies": ["."],
    "graphs": {
    "agent": "./agent.py:graph"
    },
    "env": ".env",
    "auth": {
        "path": "./auth.py:my_auth"
    }
}

3. 在您的服务器中设置好身份验证后，请求必须包含基于您所选方案的所需授权信息。假设您使用的是 JWT 令牌身份验证，您可以使用以下任一方法访问您的部署：

Python Client

Python RemoteGraph

JavaScript Client

JavaScript RemoteGraph

CURL

from langgraph_sdk import get_client

my_token = "your-token" # 实践中，您将使用您的身份验证提供者生成一个签名令牌
client = get_client(
    url="http://localhost:2024",
    headers={"Authorization": f"Bearer {my_token}"}
)
threads = await client.threads.search()

有关 RemoteGraph 的更多详细信息，请参阅 使用 RemoteGraph 指南。

启用代理身份验证

在身份验证之后，平台会创建一个特殊的配置对象 (config)，该对象会传递给 LangSmith 部署。此对象包含有关当前用户的信息，包括您从 @auth.authenticate 处理器返回的任何自定义字段。

要允许代理代表用户执行经过身份验证的操作，请在您的图中使用 langgraph_auth_user 键访问此对象：

def my_node(state, config):
    user_config = config["configurable"].get("langgraph_auth_user")
    # 令牌在 @auth.authenticate 函数期间已解析
    token = user_config.get("github_token","")
    ...

请从安全的密钥存储中获取用户凭据。不建议将密钥存储在图状态中。

为 Studio 授权用户

默认情况下，如果您在资源上添加自定义授权，这也将适用于从 Studio 进行的交互。如果需要，您可以通过检查 is_studio_user() 来区别处理已登录的 Studio 用户。

is_studio_user 是在 langgraph-sdk 的 0.1.73 版本中添加的。如果您使用的是旧版本，仍然可以通过检查 isinstance(ctx.user, StudioUser) 来判断。

from langgraph_sdk.auth import is_studio_user, Auth
auth = Auth()

# ... 设置身份验证等。

@auth.on
async def add_owner(
    ctx: Auth.types.AuthContext,
    value: dict  # 发送到此访问方法的有效负载
) -> dict:  # 返回一个限制资源访问的过滤器字典
    if is_studio_user(ctx.user):
        return {}

    filters = {"owner": ctx.user.identity}
    metadata = value.setdefault("metadata", {})
    metadata.update(filters)
    return filters

仅当您希望允许开发者访问托管在 LangSmith SaaS 上的图时，才使用此方法。

了解更多

• 身份验证与访问控制
• 设置自定义身份验证教程