实现 HTTP 安全认证

本文介绍在对话式 AI 引擎中使用 Token 或 HTTP 基本认证进行 HTTP 安全认证的方法。

前提条件

• 已参考开通服务开通对话式 AI 引擎服务。

使用 Token 认证（推荐）

推荐使用 Token 认证调用对话式 AI 引擎 RESTful API。将 Token 填入 HTTP 请求 Header 的 Authorization 字段，格式为 agora token="<token>"。

使用临时 Token

测试环境下，你可以参考开通服务从声网控制台为你的项目生成临时 Token，有效期为 24 小时。

在服务端生成 Token

生产环境下，你需要在自己的服务端生成 Token。本节以生成包含 ConvoAI、RTC 和 RTM service 的 Token 为例。请先从声网控制台获取 App ID 和 App Certificate，再参考以下示例生成 Token。

以下示例使用 Go 的 convoaitokenbuilder.BuildToken 生成包含 ConvoAI、RTC 和 RTM service 的 Token。

将 appID 和 appCertificate 替换为你的 App ID 和 App 证书：

Go

package main

import (
	"fmt"
	"log"
	"github.com/AgoraIO/Tools/DynamicKey/AgoraDynamicKey/go/src/convoaitokenbuilder"
)

func main() {
	appID := "<your_app_id>"
	appCertificate := "<your_app_certificate>"
	channelName := "testChannel"
	account := "0" // 智能体 UID

	tokenExpire := uint32(24 * 60 * 60) // Token 有效期，单位：秒
	privilegeExpire := uint32(60 * 60)  // RTC 和 RTM 权限有效期，单位：秒

	token, err := convoaitokenbuilder.BuildToken(
            appID,
            appCertificate,
            channelName,
            account,
            tokenExpire,
            privilegeExpire,
        )
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(token)
}

运行示例

在空目录中将代码保存为 main.go，运行以下命令：

Bash

go mod init example.com/convoai-token-generator
go get github.com/AgoraIO/Tools/DynamicKey/AgoraDynamicKey/go/src@v0.0.0-20261010073935-b75635c32d30
go run main.go

运行成功后输出以 007 开头的 Token。示例仅用于本地调试，请勿提交真实凭据或将 Token 写入公开日志。

自定义权限使用 BuildTokenWithPrivilege；其他语言参见 AgoraDynamicKey。

使用 Token

使用上述示例生成 Token 时，请确保以下参数与请求体保持一致：

• channelName 与 properties.channel 保持一致。
• account 与 properties.agent_rtc_uid 保持一致。

将生成的 Token 同时填入以下两个位置：

• HTTP Header：Authorization: agora token="<token>"，用于 ConvoAI REST API 鉴权。
• Request Body：properties.token，用于 Agent 加入 RTC 频道。

请求示例

Bash

curl --request POST \
  --url https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/:appid/join \
  --header 'Authorization: agora token="007abcxxxxxxx123"' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "unique_name",
  "properties": {
    "channel": "testChannel",
    "token": "<rawToken>",
    "agent_rtc_uid": "0",
    "remote_rtc_uids": [
      "123"
    ],
    "enable_string_uid": false,
    "idle_timeout": 120,
    "advanced_features": {
      "enable_rtm": true,
      "enable_aivad": true
    },
    "llm": {
      "url": "https://api.minimax.chat/v2/text/chatcompletion_v2",
      "api_key": "xxx",
      "system_messages": [
        {
          "role": "system",
          "content": "You are a helpful chatbot."
        }
      ],
      "greeting_message": "您好，有什么可以帮您？",
      "failure_message": "抱歉，我无法回答这个问题。",
      "max_history": 32,
      "params": {
        "model": "abab6.5s-chat",
        "max_token": 1024,
        "userName": "Tomas"
      }
    },
    "asr": {
      "language": "zh-CN",
      "vendor": "fengming"
    },
    "tts": {
      "vendor": "minimax",
      "skip_patterns": [
        1
      ],
      "params": {
        "group_id": "xxxx",
        "key": "xxxx",
        "model": "speech-01-turbo",
        "voice_setting": {
          "voice_id": "female-shaonv",
          "speed": 1,
          "vol": 1,
          "pitch": 0,
          "emotion": "happy"
        },
        "audio_setting": {
          "sample_rate": 16000
        }
      }
    }
  }
}
'

使用 HTTP 基本认证

除推荐的 Token 认证外，你也可以使用 HTTP 基本认证（HTTP Basic Auth）。该方式使用声网提供的客户 ID 和客户密钥，而非 Token，生成 Base64 编码的凭证，并填入 HTTP 请求 Header 的 Authorization 字段中。本节介绍如何获取用于 HTTP 基本认证的 Authorization 字段。

使用三方工具生成

你可以使用第三方在线工具快速得到 Authorization 值。将客户 ID 和客户密钥分别填入 Username 和 Password 框，得到形如 Authorization: Basic NDI1OTQ3N2I4MzYy...YwZjA= 的结果。冒号后的内容即是 Authorization 值。

使用示例代码生成

复制如下代码，填入你的客户 ID 和客户密钥，即可生成对应的 Authorization 字段：

Java

Java

import java.io.IOException;
import java.net.URI;
import java.util.Base64;

public class Base64Encoding {

    public static void main(String[] args) throws IOException, InterruptedException {

        // 客户 ID
        // 需要设置环境变量 AGORA_CUSTOMER_KEY
        final String customerKey = System.getenv("AGORA_CUSTOMER_KEY");
        // 客户密钥
        // 需要设置环境变量 AGORA_CUSTOMER_SECRET
        final String customerSecret = System.getenv("AGORA_CUSTOMER_SECRET");

        // 拼接客户 ID 和客户密钥并使用 base64 编码
        String plainCredentials = customerKey + ":" + customerSecret;
        String base64Credentials = new String(Base64.getEncoder().encode(plainCredentials.getBytes()));
        // 创建 authorization header
        String authorizationHeader = "Basic " + base64Credentials;
    }
}

Golang

Go

package main

import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
    "encoding/base64"
)

func main() {
    // 客户 ID
    // 需要设置环境变量 AGORA_CUSTOMER_KEY
    customerKey := os.Getenv("AGORA_CUSTOMER_KEY")
    // 客户密钥
    // 需要设置环境变量 AGORA_CUSTOMER_SECRET
    customerSecret := os.Getenv("AGORA_CUSTOMER_SECRET")

    // 拼接客户 ID 和客户密钥并使用 base64 进行编码
    plainCredentials := customerKey + ":" + customerSecret
    base64Credentials := base64.StdEncoding.EncodeToString([]byte(plainCredentials))
    // 创建 Authorization header
    authHeader := "Basic " + base64Credentials
    // 打印生成的认证头部
    fmt.Println(authHeader)
}

PHP

PHP

<?php
// 客户 ID
// 需要设置环境变量 AGORA_CUSTOMER_KEY
$customerKey = getenv("AGORA_CUSTOMER_KEY");
// 客户密钥
// 需要设置环境变量 AGORA_CUSTOMER_SECRET
$customerSecret = getenv("AGORA_CUSTOMER_SECRET");
// 拼接客户 ID 和客户密钥
$credentials = $customerKey . ":" . $customerSecret;

// 使用 base64 进行编码
$base64Credentials = base64_encode($credentials);
// 创建 authorization header
$arr_header = "Authorization: Basic " . $base64Credentials;

C#

C#

using System;
using System.IO;
using System.Net;
using System.Text;

namespace Examples.System.Net
{
    public class WebRequestPostExample
    {
        public static void Main()
        {
            // 客户 ID
            // 需要设置环境变量 AGORA_CUSTOMER_KEY
            string customerKey = Environment.GetEnvironmentVariable("AGORA_CUSTOMER_KEY");
            // 客户密钥
            // 需要设置环境变量 AGORA_CUSTOMER_SECRET
            string customerSecret = Environment.GetEnvironmentVariable("AGORA_CUSTOMER_SECRET");
            // 拼接客户 ID 和客户密钥
            string plainCredential = customerKey + ":" + customerSecret;

            // 使用 base64 进行编码
            var plainTextBytes = Encoding.UTF8.GetBytes(plainCredential);
            string encodedCredential = Convert.ToBase64String(plainTextBytes);
            // 创建 authorization header
            string authorizationHeader = "Authorization: Basic " + encodedCredential;
        }
    }
}

Node.js

JavaScript

// 基于 Node.js 实现的 HTTP 基本认证示例
const https = require('https')
// 客户 ID
// 需要设置环境变量 AGORA_CUSTOMER_KEY
const customerKey = process.env.AGORA_CUSTOMER_KEY;
// 客户密钥
// 需要设置环境变量 AGORA_CUSTOMER_SECRET
const customerSecret = process.env.AGORA_CUSTOMER_SECRET;
// 拼接客户 ID 和客户密钥
const plainCredential = customerKey + ":" + customerSecret
// 使用 base64 进行编码
encodedCredential = Buffer.from(plainCredential).toString('base64')
// 创建 authorization header
authorizationField = "Basic " + encodedCredential

Python

Python

# -- coding utf-8 --
# Python 3
import base64
import http.client

# 客户 ID
# 需要设置环境变量 AGORA_CUSTOMER_KEY
customer_key = os.environ.get("AGORA_CUSTOMER_KEY")
# 客户密钥
# 需要设置环境变量 AGORA_CUSTOMER_SECRET
customer_secret = os.environ.get("AGORA_CUSTOMER_SECRET")

# 拼接客户 ID 和客户密钥
credentials = customer_key + ":" + customer_secret
# 使用 base64 进行编码
base64_credentials = base64.b64encode(credentials.encode("utf8"))
credential = base64_credentials.decode("utf8")
# 创建 authorization header
basic_auth_header = 'basic ' + credential