Cách bảo mật quyền truy cập vào các agent đàm thoại trong ElevenAgents

Tổng quan

Khi xây dựng các agent đàm thoại (conversational agent), bạn có thể cần hạn chế quyền truy cập vào một số agent hoặc cuộc hội thoại nhất định. ElevenLabs cung cấp nhiều cơ chế xác thực để đảm bảo rằng chỉ những người dùng được ủy quyền mới có thể tương tác với các agent của bạn.

Các phương thức xác thực

ElevenLabs cung cấp hai phương thức chính để bảo mật các agent đàm thoại của bạn:

URL được xác nhận (Signed URL)

Tạo các URL tạm thời đã được xác thực để thiết lập kết nối an toàn từ phía client mà không làm lộ API key.

Danh sách cho phép (Allowlist)

Hạn chế quyền truy cập bằng cách chỉ cho phép các domain hoặc hostname cụ thể được kết nối với agent của bạn.

Sử dụng URL được xác nhận

URL được xác nhận là phương thức được khuyến nghị cho các ứng dụng phía client. Phương thức này cho phép bạn xác thực người dùng mà không cần tiết lộ API key của mình.

Cách thức hoạt động của URL được xác nhận

1. Server gửi yêu cầu lấy URL được xác nhận tới ElevenLabs bằng cách sử dụng API key của bạn.
2. ElevenLabs tạo một token tạm thời và trả về một URL WebSocket đã được xác nhận.
3. Ứng dụng client của bạn sử dụng URL được xác nhận này để thiết lập kết nối WebSocket.
4. URL được xác nhận sẽ hết hạn sau 15 phút.

Tạo URL được xác nhận thông qua API

Để lấy URL được xác nhận, hãy gửi yêu cầu tới endpoint get_signed_url kèm theo ID agent của bạn:

Python

# Server-side code using the Python SDK
from elevenlabs.client import ElevenLabs
async def get_signed_url():
    try:
        elevenlabs = ElevenLabs(api_key="your-api-key")
        response = await elevenlabs.conversational_ai.conversations.get_signed_url(agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6")
        return response.signed_url
    except Exception as error:
        print(f"Error getting signed URL: {error}")
        raise

JavaScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

// Server-side code using the JavaScript SDK
const elevenlabs = new ElevenLabsClient({ apiKey: "your-api-key" });
async function getSignedUrl() {
  try {
    const response = await elevenlabs.conversationalAi.conversations.getSignedUrl({
      agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
    });

    return response.signed_url;
  } catch (error) {
    console.error("Error getting signed URL:", error);
    throw error;
  }
}

Bash

curl -X GET "https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6" \
-H "xi-api-key: your-api-key"

Phản hồi từ curl có định dạng như sau:

{
  "signed_url": "wss://api.elevenlabs.io/v1/convai/conversation?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&conversation_signature=your-token"
}

Kết nối với agent của bạn bằng URL đã xác nhận

Lấy URL đã xác nhận do server tạo ra từ client và sử dụng URL đã xác nhận đó để kết nối với websocket.

Python

# Client-side code using the Python SDK
from elevenlabs.conversational_ai.conversation import (
    Conversation,
    AudioInterface,
    ClientTools,
    ConversationInitiationData
)
import os
from elevenlabs.client import ElevenLabs
api_key = os.getenv("ELEVENLABS_API_KEY")

elevenlabs = ElevenLabs(api_key=api_key)

conversation = Conversation(
  client=elevenlabs,
  agent_id=os.getenv("AGENT_ID"),
  requires_auth=True,
  audio_interface=AudioInterface(),
  config=ConversationInitiationData()
)

async def start_conversation():
  try:
    signed_url = await get_signed_url()
    conversation = Conversation(
      client=elevenlabs,
      url=signed_url,
    )

    conversation.start_session()
  except Exception as error:
    print(f"Failed to start conversation: {error}")

JavaScript

// Client-side code using the JavaScript SDK
import { Conversation } from "@elevenlabs/client";

async function startConversation() {
  try {
    const signedUrl = await getSignedUrl();
    const conversation = await Conversation.startSession({
      signedUrl,
    });

    return conversation;
  } catch (error) {
    console.error("Failed to start conversation:", error);
    throw error;
  }
}

Thời hạn của URL được xác nhận

Các URL được xác nhận có hiệu lực trong vòng 15 phút. Phiên hội thoại có thể kéo dài hơn, nhưng hội thoại phải được bắt đầu trong khoảng thời gian 15 phút đó.

Sử dụng danh sách cho phép (Allowlist)

Danh sách cho phép cung cấp phương thức hạn chế quyền truy cập vào các agent đàm thoại (conversational agent) của bạn dựa trên domain gốc. Điều này đảm bảo rằng chỉ các yêu cầu từ những domain đã được phê duyệt mới có thể kết nối với agent của bạn.

Cách thức hoạt động của danh sách cho phép

1. Bạn thiết lập một danh sách các hostname được phê duyệt cho agent của mình.
2. Khi một ứng dụng client cố gắng kết nối, ElevenLabs sẽ kiểm tra xem domain gốc của yêu cầu đó có khớp với tên server nằm trong danh sách cho phép hay không.
3. Nếu domain gốc nằm trong danh sách, kết nối sẽ được chấp nhận; ngược lại, kết nối sẽ bị từ chối.

Cấu hình danh sách cho phép

Danh sách cho phép được thiết lập trong phần cài đặt xác thực của agent. Bạn có thể chỉ định tối đa 10 tên server duy nhất được phép kết nối với agent của mình.

Ví dụ: Thiết lập danh sách cho phép

Cấu hình qua dashboard

Mở agent của bạn trong dashboard và chuyển đến tab Security. Thêm từng tên server được phê duyệt (ví dụ: example.com, app.example.com, localhost:3000) vào danh sách cho phép.

Cấu hình qua giao diện dòng lệnh (CLI)

1. Tải xuống agent của bạn

elevenlabs agents pull --agent "<agent-name>"

2. Chỉnh sửa cấu hình agent

Trong file agent_configs/<agent-name>.json, hãy thiết lập platform_settings.auth:

{
  "platform_settings": {
    "auth": {
      "enable_auth": false,
      "allowlist": [
        { "hostname": "example.com" },
        { "hostname": "app.example.com" },
        { "hostname": "localhost:3000" }
      ]
    }
  }
}

3. Đẩy các thay đổi lên

elevenlabs agents push --agent "<agent-name>"

Cấu hình qua API

Python

from elevenlabs.client import ElevenLabs
import os
from elevenlabs.types import *

api_key = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(api_key=api_key)

agent = elevenlabs.conversational_ai.agents.create(
  conversation_config=ConversationalConfig(
    agent=AgentConfig(
      first_message="Hi. I'm an authenticated agent.",
    )
  ),
  platform_settings=AgentPlatformSettingsRequestModel(
  auth=AuthSettings(
    enable_auth=False,
    allowlist=[
      AllowlistItem(hostname="example.com"),
      AllowlistItem(hostname="app.example.com"),
      AllowlistItem(hostname="localhost:3000")
      ]
    )
  )
)

JavaScript

async function createAuthenticatedAgent(client) {
  try {
    const agent = await elevenlabs.conversationalAi.agents.create({
      conversationConfig: {
        agent: {
          firstMessage: "Hi. I'm an authenticated agent.",
        },
      },
      platformSettings: {
        auth: {
          enableAuth: false,
          allowlist: [
            { hostname: 'example.com' },
            { hostname: 'app.example.com' },
            { hostname: 'localhost:3000' },
          ],
        },
      },
    });

    return agent;
  } catch (error) {
    console.error('Error creating agent:', error);
    throw error;
  }
}

Chọn phương thức xác thực

Bạn chỉ nên cấu hình một phương thức xác thực cho mỗi agent:

1. Sử dụng URL được xác nhận (enable_auth) cho các phiên kết nối ứng dụng client đã được xác thực.
2. Sử dụng danh sách cho phép (allowlist) để kiểm soát quyền truy cập dựa trên tên server.

Không nên cấu hình cả URL được xác nhận và danh sách cho phép trên cùng một agent. Hãy chọn phương thức phù hợp với mô hình triển khai của bạn.

Ví dụ: Chỉ sử dụng URL được xác nhận

Sử dụng enable_auth mà không kèm theo allowlist:

Python

from elevenlabs.client import ElevenLabs
import os
from elevenlabs.types import *

api_key = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(api_key=api_key)

agent = elevenlabs.conversational_ai.agents.create(
  conversation_config=ConversationalConfig(
    agent=AgentConfig(
      first_message="Hi. I require a signed URL.",
    )
  ),
  platform_settings=AgentPlatformSettingsRequestModel(
    auth=AuthSettings(
      enable_auth=True
    )
  )
)

JavaScript

async function createSignedUrlAgent(client) {
  try {
    const agent = await client.conversationalAi.agents.create({
      conversationConfig: {
        agent: {
          firstMessage: "Hi. I require a signed URL.",
        },
      },
      platformSettings: {
        auth: {
          enableAuth: true,
        },
      },
    });

    return agent;
  } catch (error) {
    console.error("Error creating agent:", error);
    throw error;
  }
}

Ví dụ: Chỉ sử dụng danh sách cho phép (allowlist)

Sử dụng allowlist mà không cần bật tính năng URL được xác nhận (signed URL):

Python

from elevenlabs.client import ElevenLabs
import os
from elevenlabs.types import *

api_key = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(api_key=api_key)

agent = elevenlabs.conversational_ai.agents.create(
  conversation_config=ConversationalConfig(
    agent=AgentConfig(
      first_message="Hi. I only accept approved hostnames.",
    )
  ),
  platform_settings=AgentPlatformSettingsRequestModel(
    auth=AuthSettings(
      allowlist=[
        AllowlistItem(hostname="example.com"),
        AllowlistItem(hostname="app.example.com"),
      ]
    )
  )
)

JavaScript

async function createAllowlistAgent(client) {
  try {
    const agent = await client.conversationalAi.agents.create({
      conversationConfig: {
        agent: {
          firstMessage: "Hi. I only accept approved hostnames.",
        },
      },
      platformSettings: {
        auth: {
          allowlist: [{ hostname: "example.com" }, { hostname: "app.example.com" }],
        },
      },
    });

    return agent;
  } catch (error) {
    console.error("Error creating agent:", error);
    throw error;
  }
}

Câu hỏi thường gặp (FAQ)

Có thể sử dụng cùng một URL đã xác nhận (signed URL) cho nhiều người dùng không?

Bạn có thể làm vậy, nhưng ElevenLabs khuyến nghị nên tạo một URL đã xác nhận mới cho mỗi phiên làm việc của người dùng.

Điều gì xảy ra nếu URL đã xác nhận hết hạn trong khi cuộc hội thoại đang diễn ra?

Nếu URL đã xác nhận hết hạn (sau 15 phút), bất kỳ kết nối WebSocket nào được tạo bằng URL đó vẫn sẽ được duy trì; tuy nhiên, việc cố gắng tạo kết nối mới bằng URL đã xác nhận đó sẽ không thành công.

Có thể giới hạn quyền truy cập cho những người dùng cụ thể không?

Cơ chế URL đã xác nhận chỉ xác minh rằng yêu cầu bắt nguồn từ một nguồn được ủy quyền. Để giới hạn quyền truy cập cho những người dùng cụ thể, bạn cần triển khai xác thực người dùng trong ứng dụng của mình trước khi yêu cầu cấp URL đã xác nhận.

Có giới hạn nào về số lượng URL đã xác nhận mà bạn có thể tạo không?

Không có giới hạn cụ thể nào về số lượng URL đã xác nhận mà bạn có thể tạo.

Danh sách cho phép (allowlist) xử lý các subdomain như thế nào?

Danh sách cho phép thực hiện khớp chính xác (exact matching) đối với hostname. Nếu bạn muốn cho phép cả domain chính và các subdomain của nó, bạn cần thêm từng domain một cách riêng biệt (ví dụ: “example.com” và “app.example.com”).

Có cần sử dụng cả hai phương thức xác thực không?

Không. Bạn chỉ cần cấu hình một trong hai phương thức: URL đã xác nhận hoặc danh sách cho phép cho mỗi agent. Đối với các ứng dụng phía client, URL đã xác nhận là phương thức mặc định được khuyến nghị.

Nên triển khai thêm các biện pháp bảo mật nào khác?

Ngoài URL đã xác nhận và danh sách cho phép, bạn nên cân nhắc triển khai thêm:

• Xác thực người dùng trước khi yêu cầu cấp URL đã xác nhận
• Giới hạn tần suất yêu cầu đối với các yêu cầu API
• Theo dõi quá trình sử dụng để phát hiện các hành vi đáng ngờ
• Xử lý lỗi phù hợp trong trường hợp xác thực thất bại