クロスドメイン認証

Agents をデプロイしたあとは、セキュリティのためクライアントからトークンを送り、サーバーで検証します。このガイドでは、エージェントへの WebSocket 接続の認証パターンを扱います。

WebSocket 認証

WebSocket は HTTP ではないため、クロスドメイン接続ではハンドシェイクに制限があります。

送れないもの:

アップグレード時のカスタムヘッダー
接続時の Authorization: Bearer ...

できること:

署名済みの短命トークンを、クエリパラメーターとして接続 URL に入れる
サーバーの接続パスでトークンを検証する

同一オリジン

クライアントとサーバーがオリジンを共有する場合、ブラウザーは WebSocket ハンドシェイク時に Cookie を送ります。ここではセッションベースの認証が使えます。HTTP-only Cookie を推奨します。

クロスオリジン

クロスオリジンの Cookie 動作は、Cookie のドメインと SameSite 属性、2 つのオリジンが same-site かどうか、ブラウザーのサードパーティ Cookie ポリシーに依存します。Cookie に頼れないときは、短命の資格情報を URL クエリに渡し、サーバーで検証します。

使用例

静的認証

import { useAgent } from "agents/react";

function ChatComponent() {
	const agent = useAgent({
		agent: "my-agent",
		query: {
			token: "demo-token-123",
			userId: "demo-user",
		},
	});

	// Use agent to make calls, access state, etc.
}

import { useAgent } from "agents/react";

function ChatComponent() {
	const agent = useAgent({
		agent: "my-agent",
		query: {
			token: "demo-token-123",
			userId: "demo-user",
		},
	});

	// Use agent to make calls, access state, etc.
}

非同期認証

接続直前にクエリ値を組み立てます。非同期の準備には Suspense を使います。

import { useAgent } from "agents/react";
import { Suspense, useCallback } from "react";

function ChatComponent() {
	const asyncQuery = useCallback(async () => {
		const [token, user] = await Promise.all([getAuthToken(), getCurrentUser()]);
		return {
			token,
			userId: user.id,
			timestamp: Date.now().toString(),
		};
	}, []);

	const agent = useAgent({
		agent: "my-agent",
		query: asyncQuery,
	});

	// Use agent to make calls, access state, etc.
}

function App() {
	return (
		<Suspense fallback={<div>Authenticating...</div>}>
			<ChatComponent />
		</Suspense>
	);
}

import { useAgent } from "agents/react";
import { Suspense, useCallback } from "react";

function ChatComponent() {
	const asyncQuery = useCallback(async () => {
		const [token, user] = await Promise.all([getAuthToken(), getCurrentUser()]);
		return {
			token,
			userId: user.id,
			timestamp: Date.now().toString(),
		};
	}, []);

	const agent = useAgent({
		agent: "my-agent",
		query: asyncQuery,
	});

	// Use agent to make calls, access state, etc.
}

function App() {
	return (
		<Suspense fallback={<div>Authenticating...</div>}>
			<ChatComponent />
		</Suspense>
	);
}

JWT のリフレッシュパターン

useAgent は接続前に非同期クエリを解決し、再接続時に再評価します。毎回、新しい短命のアプリケーショントークンを返します。

import { useAgent } from "agents/react";
import { useCallback } from "react";

function useJWTAgent(agentName) {
	const asyncQuery = useCallback(async () => {
		return { token: await getShortLivedAccessToken() };
	}, []);

	return useAgent({
		agent: agentName,
		query: asyncQuery,
	});
}

import { useAgent } from "agents/react";
import { useCallback } from "react";

declare function getShortLivedAccessToken(): Promise<string>;

function useJWTAgent(agentName: string) {
	const asyncQuery = useCallback(async () => {
		return { token: await getShortLivedAccessToken() };
	}, []);

	return useAgent({
		agent: agentName,
		query: asyncQuery,
	});
}