# 配置 JWT 身份认证

JSON Web Token（JWT）身份认证是一种常用的无状态身份认证方式。与简单 API Key（API 密钥）不同，JWT 可以携带声明，网关无需为每个请求查询其他系统即可验证这些声明。

API7 网关中的 [`jwt-auth`](https://docs.apiseven.com/hub/jwt-auth.md) 插件会根据所配置的消费者凭证验证传入 JWT 的签名。

本指南介绍常见 JWT 配置流程。有关完整插件字段参考以及声明验证、其他 Token 位置等高级选项，请参阅 [`jwt-auth`](https://docs.apiseven.com/hub/jwt-auth.md)。

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

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

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

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

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

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

* Admin API
* ADC

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

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

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

  -d '{

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

    "upstream": {

      "type": "roundrobin",

      "scheme": "http",

      "nodes": [

        {

          "host": "httpbin.org",

          "port": 80,

          "weight": 100

        }

      ]

    }

  }'
```

adc.yaml

```
services:

  - name: jwt-auth-httpbin-service

    upstream:

      name: default

      scheme: http

      nodes:

        - host: httpbin.org

          port: 80

          weight: 100

    routes:

      - name: jwt-auth-route

        uris:

          - /anything/jwt-auth

        methods:

          - GET

        plugins:

          jwt-auth: {}

    labels:

      docs-example: jwt-auth-httpbin-service

consumers:

  - username: jwt-auth-consumer

    credentials:

      - name: jwt-auth-consumer-cred

        type: jwt-auth

        config:

          key: user-1-identity

          secret: my-shared-secret

    labels:

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

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

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --include-resource-type consumer \

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

审查变更后同步配置：

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --include-resource-type consumer \

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

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

* Admin API
* ADC

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

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

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

  -d '{

    "name": "jwt-auth-route",

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

    "methods": ["GET"],

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

    "plugins": {

      "jwt-auth": {}

    }

  }'
```

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

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

对于 HS256，请为凭证配置用于标识消费者的 `key`，以及用于验证签名的共享 `secret`。

* Admin API
* ADC

```
# 1. 创建消费者

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

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

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

  -d '{

    "username": "jwt-auth-consumer"

  }'



# 2. 创建 jwt-auth 凭证

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

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

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

  -d '{

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

    "plugins": {

      "jwt-auth": {

        "key": "user-1-identity",

        "secret": "my-shared-secret"

      }

    }

  }'
```

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

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

首先发送不含 Token 的请求。网关应返回 `401 Unauthorized` 拒绝请求：

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

然后为所配置的消费者凭证生成 JWT：

```
expires_at=$(( $(date +%s) + 300 ))

header=$(printf '%s' '{"alg":"HS256","typ":"JWT"}' | openssl base64 -A | tr '+/' '-_' | tr -d '=')

payload=$(printf '{"key":"user-1-identity","exp":%s}' "$expires_at" | openssl base64 -A | tr '+/' '-_' | tr -d '=')

signature=$(printf '%s' "$header.$payload" | openssl dgst -binary -sha256 -hmac 'my-shared-secret' | openssl base64 -A | tr '+/' '-_' | tr -d '=')

jwt="$header.$payload.$signature"
```

在 `Authorization` 请求头中使用生成的 Token：

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

  -H "Authorization: Bearer $jwt"
```

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

```
{

  "headers": {

    "Authorization": "Bearer <your-jwt>",

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

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

  }

}
```

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

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

* [配置 HMAC 身份认证](https://docs.apiseven.com/api7-gateway/how-to-guides/api-security/hmac-auth.md)——使用请求签名提高安全性。
* [配置 Key 身份认证](https://docs.apiseven.com/api7-gateway/how-to-guides/api-security/key-auth.md)——使用简单 API Key 快速保护 API。
* [消费者和凭证](https://docs.apiseven.com/api7-gateway/key-concepts/consumers-and-credentials.md)——理解 API7 网关如何管理 API 身份。
