← Создание агентов на Cloudflare / agents / runtime / operations

Аутентификация между доменами

После развёртывания агентов для безопасности отправляйте токен с клиента и проверяйте его на сервере. В этом руководстве описаны шаблоны аутентификации для WebSocket-соединений с агентами.

Аутентификация WebSocket

WebSockets не являются HTTP, поэтому handshake ограничен при установлении междоменных соединений.

Вы не можете отправлять:

Пользовательские заголовки во время апгрейда
Authorization: Bearer ... при подключении

Вы можете:

Размещение подписанного недолговечного токена в URL подключения в виде параметров запроса
Проверьте токен на пути подключения вашего сервера

Тот же источник

Если клиент и сервер имеют общий origin, браузер будет отправлять cookies во время handshake WebSocket. Здесь может работать аутентификация на основе сессии. Отдавайте предпочтение cookies с флагом HTTP-only.

Между источниками

Поведение файлов cookie между источниками зависит от домена cookie и SameSite атрибутов, от того, являются ли два источника 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,
	});
}