# 配置 Basic 身份认证

Basic 身份认证是保护 Web 服务的常见方式。它使用标准 HTTP `Authorization` 请求头和 `Basic` 方案，后跟经过 Base64 编码的 `username:password` 字符串。

API7 网关提供 [`basic-auth`](https://docs.apiseven.com/hub/basic-auth.md) 插件来处理此身份认证流程，并根据消费者凭证数据库验证凭证。

本指南介绍标准配置流程。有关完整的插件字段参考和高级行为，请参阅 [`basic-auth`](https://docs.apiseven.com/hub/basic-auth.md)。

## 前置条件[​](#前置条件 "前置条件的直接链接")

* API7 企业版实例正在运行。
* 已创建网关组且网关实例正在运行。
* 已[从控制台获取 Token](https://docs.apiseven.com/api7-gateway/reference/obtain-dashboard-token.md)。

## 配置 Basic 身份认证[​](#配置-basic-身份认证 "配置 Basic 身份认证的直接链接")

配置 Basic 身份认证包含三个步骤：

1. 创建具有有效上游的服务。
2. 创建启用 `basic-auth` 的路由。
3. 创建消费者并挂载 Basic 身份认证凭证。

### 第 1 步：创建具有上游的服务[​](#第-1-步创建具有上游的服务 "第 1 步：创建具有上游的服务的直接链接")

* Admin API
* ADC

```
curl -k "https://localhost:7443/apisix/admin/services/basic-auth-httpbin-service?gateway_group_id={gateway_group_id}" -X PUT \

  -H "X-API-KEY: ${API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "basic-auth-httpbin-service",

    "upstream": {

      "type": "roundrobin",

      "scheme": "http",

      "nodes": [

        {

          "host": "httpbin.org",

          "port": 80,

          "weight": 100

        }

      ]

    }

  }'
```

adc.yaml

```
services:

  - name: basic-auth-httpbin-service

    upstream:

      name: default

      scheme: http

      nodes:

        - host: httpbin.org

          port: 80

          weight: 100

    routes:

      - name: basic-auth-route

        uris:

          - /anything/basic-auth

        methods:

          - GET

        plugins:

          basic-auth:

            hide_credentials: true

    labels:

      docs-example: basic-auth-httpbin-service

consumers:

  - username: basic-auth-consumer

    credentials:

      - name: basic-auth-consumer-cred

        type: basic-auth

        config:

          username: alice

          password: secret-password

    labels:

      docs-example: basic-auth-httpbin-service
```

预览本示例管理的资源变更，确认没有非预期的更新或删除：

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --include-resource-type consumer \

  --label-selector docs-example=basic-auth-httpbin-service
```

审查变更后同步配置：

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --include-resource-type consumer \

  --label-selector docs-example=basic-auth-httpbin-service
```

### 第 2 步：创建路由并启用 `basic-auth`[​](#第-2-步创建路由并启用-basic-auth "第-2-步创建路由并启用-basic-auth的直接链接")

* Admin API
* ADC

```
curl -k "https://localhost:7443/apisix/admin/routes/basic-auth-route?gateway_group_id={gateway_group_id}" -X PUT \

  -H "X-API-KEY: ${API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "basic-auth-route",

    "paths": ["/anything/basic-auth"],

    "methods": ["GET"],

    "service_id": "basic-auth-httpbin-service",

    "plugins": {

      "basic-auth": {

        "hide_credentials": true

      }

    }

  }'
```

该路由已包含在前面的 `adc.yaml` 示例中。

### 第 3 步：创建消费者和凭证[​](#第-3-步创建消费者和凭证 "第 3 步：创建消费者和凭证的直接链接")

* Admin API
* ADC

```
# 1. 创建消费者

curl -k "https://localhost:7443/apisix/admin/consumers/basic-auth-consumer?gateway_group_id={gateway_group_id}" -X PUT \

  -H "X-API-KEY: ${API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "username": "basic-auth-consumer"

  }'



# 2. 创建 basic-auth 凭证

curl -k "https://localhost:7443/apisix/admin/consumers/basic-auth-consumer/credentials/basic-auth-consumer-cred?gateway_group_id={gateway_group_id}" -X PUT \

  -H "X-API-KEY: ${API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "basic-auth-consumer-cred",

    "plugins": {

      "basic-auth": {

        "username": "alice",

        "password": "secret-password"

      }

    }

  }'
```

消费者和凭证已包含在前面的 `adc.yaml` 示例中。

## 验证配置[​](#验证配置 "验证配置的直接链接")

发送不含 `Authorization` 请求头的请求。网关应返回 `401 Unauthorized` 拒绝请求：

```
curl -i "http://127.0.0.1:9080/anything/basic-auth"
```

然后使用正确凭证发送请求：

```
curl -i "http://127.0.0.1:9080/anything/basic-auth" \

  -u alice:secret-password
```

应收到 `200 OK`，上游响应应包含类似以下的请求头：

```
{

  "headers": {

    "X-Consumer-Username": "basic-auth-consumer",

    "X-Credential-Identifier": "basic-auth-consumer-cred"

  }

}
```

如果应用配置后，已认证请求仍返回 `401` 或路由返回 `404`，请等待几秒，让最新配置下发到网关后重试。

## 后续步骤[​](#后续步骤 "后续步骤的直接链接")

* [配置 Key 身份认证](https://docs.apiseven.com/api7-gateway/how-to-guides/api-security/key-auth.md)——使用唯一 API Key（API 密钥）保护 API。
* [配置 JWT 身份认证](https://docs.apiseven.com/api7-gateway/how-to-guides/api-security/jwt-auth.md)——使用 JSON Web Token 实现无状态身份认证。
* [消费者和凭证](https://docs.apiseven.com/api7-gateway/key-concepts/consumers-and-credentials.md)——理解 API7 网关如何管理 API 身份。
