이 튜토리얼에서는 특정 사용자만 접근할 수 있는 챗봇을 구축합니다. LangGraph 템플릿으로 시작하여 단계별로 토큰 기반 보안을 추가합니다. 마지막에는 접근을 허용하기 전에 유효한 토큰을 확인하는 작동하는 챗봇을 갖게 됩니다.
이것은 인증 시리즈의 1부입니다:
- 커스텀 인증 설정하기 (현재 위치) - 봇에 접근할 수 있는 사용자 제어
- 대화를 비공개로 만들기 - 사용자가 비공개 대화를 할 수 있도록 하기
- 인증 제공자 연결하기 - 실제 사용자 계정 추가 및 프로덕션용 OAuth2를 사용한 검증
이 가이드는 다음 개념에 대한 기본적인 이해를 전제로 합니다:
커스텀 인증은 LangSmith SaaS 배포 또는 Enterprise Self-Hosted 배포에서만 사용할 수 있습니다.
1. 앱 생성하기
LangGraph starter 템플릿을 사용하여 새 챗봇을 생성합니다:
pip install -U "langgraph-cli[inmem]"
langgraph new --template=new-langgraph-project-python custom-auth
cd custom-auth
pip install -e .
langgraph dev
> - 🚀 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
>
> This in-memory server is designed for development and testing.
> For production use, please use LangSmith.
2. 인증 추가하기
이제 기본 LangGraph 앱이 있으므로 인증을 추가합니다.
이 튜토리얼에서는 예제 목적으로 하드코딩된 토큰으로 시작합니다. 세 번째 튜토리얼에서 “프로덕션 준비” 인증 체계를 다룹니다.
Auth 객체를 사용하면 LangSmith 배포가 모든 요청에서 실행할 인증 함수를 등록할 수 있습니다. 이 함수는 각 요청을 받아 수락 또는 거부를 결정합니다.
새 파일 src/security/auth.py를 생성합니다. 이곳에 사용자가 봇에 접근할 수 있는지 확인하는 코드가 위치합니다:
from langgraph_sdk import Auth
# This is our toy user database. Do not do this in production
VALID_TOKENS = {
"user1-token": {"id": "user1", "name": "Alice"},
"user2-token": {"id": "user2", "name": "Bob"},
}
# The "Auth" object is a container that LangGraph will use to mark our authentication function
auth = Auth()
# The `authenticate` decorator tells LangGraph to call this function as middleware
# for every request. This will determine whether the request is allowed or not
@auth.authenticate
async def get_current_user(authorization: str | None) -> Auth.types.MinimalUserDict:
"""Check if the user's token is valid."""
assert authorization
scheme, token = authorization.split()
assert scheme.lower() == "bearer"
# Check if token is valid
if token not in VALID_TOKENS:
raise Auth.exceptions.HTTPException(status_code=401, detail="Invalid token")
# Return user info if valid
user_data = VALID_TOKENS[token]
return {
"identity": user_data["id"],
}
- 요청의 Authorization header에 유효한 토큰이 제공되었는지 확인
- 사용자의 identity 반환
이제 langgraph.json 설정에 다음을 추가하여 LangGraph가 인증을 사용하도록 지시합니다:
{
"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. 봇과 대화하기
이제 요청 헤더에 유효한 토큰을 제공하는 경우에만 봇에 접근할 수 있어야 합니다. 그러나 튜토리얼의 다음 섹션에서 resource authorization handlers를 추가할 때까지 사용자는 여전히 서로의 리소스에 접근할 수 있습니다.
파일이나 노트북에서 다음 코드를 실행합니다:
from langgraph_sdk import get_client
# Try without a token (should fail)
client = get_client(url="http://localhost:2024")
try:
thread = await client.threads.create()
print("❌ Should have failed without token!")
except Exception as e:
print("✅ Correctly blocked access:", e)
# Try with a valid token
client = get_client(
url="http://localhost:2024", headers={"Authorization": "Bearer user1-token"}
)
# Create a thread and chat
thread = await client.threads.create()
print(f"✅ Created thread as Alice: {thread['thread_id']}")
response = await client.runs.create(
thread_id=thread["thread_id"],
assistant_id="agent",
input={"messages": [{"role": "user", "content": "Hello!"}]},
)
print("✅ Bot responded:")
print(response)
- 유효한 토큰 없이는 봇에 접근할 수 없습니다
- 유효한 토큰이 있으면 thread를 생성하고 대화할 수 있습니다
축하합니다! “인증된” 사용자만 접근할 수 있는 챗봇을 구축했습니다. 이 시스템은 (아직) 프로덕션 준비 보안 체계를 구현하지 않지만, 봇에 대한 접근을 제어하는 방법의 기본 메커니즘을 배웠습니다. 다음 튜토리얼에서는 각 사용자에게 자신만의 비공개 대화를 제공하는 방법을 배웁니다.
다음 단계
이제 봇에 접근하는 사용자를 제어할 수 있으므로 다음을 원할 수 있습니다:
- 대화를 비공개로 만들기로 이동하여 리소스 권한 부여에 대해 알아보며 튜토리얼을 계속합니다.
- 인증 개념에 대해 자세히 읽어보세요.
- 더 많은 인증 세부 정보는 API reference를 확인하세요.
