# 实现 HTTP 鉴权 (/zh-CN/ai/build/http-basic-auth)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

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

## 前提条件 [#前提条件]

- 已参考[开通服务](/zh-CN/ai/get-started/enable-service)开通对话式 AI 引擎服务。

<a id="使用-token-认证"></a>
## 使用 Token 认证（推荐） [#使用-token-认证推荐]

<a id="使用-rtc-token-认证-推荐"></a>

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

### 使用临时 Token [#使用临时-token]

测试环境下，你可以参考[开通服务](/zh-CN/ai/get-started/enable-service#获取临时-token)从声网控制台为你的项目生成临时 Token，有效期为 24 小时。

### 在服务端生成 Token [#在服务端生成-token]

<a id="部署-token-服务器生成"></a>

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

以下示例使用 Go 的 [`convoaitokenbuilder.BuildToken`](https://github.com/AgoraIO/Tools/blob/b75635c32d30cedd25fd1199926fd55219533688/DynamicKey/AgoraDynamicKey/go/src/convoaitokenbuilder/convoaitokenbuilder.go) 生成包含 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)
}
```

<Accordions>
<Accordion title="运行示例">

在空目录中将代码保存为 `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 写入公开日志。

</Accordion>
</Accordions>

自定义权限使用 [`BuildTokenWithPrivilege`](https://github.com/AgoraIO/Tools/blob/b75635c32d30cedd25fd1199926fd55219533688/DynamicKey/AgoraDynamicKey/go/src/convoaitokenbuilder/convoaitokenbuilder.go#L75-L96)；其他语言参见 [AgoraDynamicKey](https://github.com/AgoraIO/Tools/tree/feature/access-token2-convoai-stt-services/DynamicKey/AgoraDynamicKey)。

### 使用 Token [#使用-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 基本认证 [#使用-http-基本认证]

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

### 使用三方工具生成 [#使用三方工具生成]

你可以使用[第三方在线工具](https://www.debugbear.com/basic-auth-header-generator)快速得到 Authorization 值。将客户 ID 和客户密钥分别填入 Username 和 Password 框，得到形如 `Authorization: Basic NDI1OTQ3N2I4MzYy...YwZjA=` 的结果。冒号后的内容即是 `Authorization` 值。

### 使用示例代码生成 [#使用示例代码生成]

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

```java tab="Java" tabGroup="operating-systems"
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;
    }
}
```

```go tab="Golang" tabGroup="operating-systems"
package main

import (
    "fmt"
    "os"
    "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 tab="PHP" tabGroup="operating-systems"
<?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;
```

```cs tab="C#" tabGroup="operating-systems"
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;
        }
    }
}
```

```javascript tab="Node.js" tabGroup="operating-systems"
// 基于 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 tab="Python" tabGroup="operating-systems"
# -- coding utf-8 --
# Python 3
import base64
import http.client
import os

# 客户 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
```