鉴权插件

Basic Authentication

配置信息

• 基本描述

• 参数

使用详情

• 创建消费者

curl -d "username=user123&custom_id=SOME_CUSTOM_ID" http://kong:8001/consumers/

• 创建凭证

curl -X POST http://kong:8001/consumers/{consumer}/basic-auth --data "username=Aladdin" --data "password=OpenSesame"

• 使用凭证

curl http://kong:8000/{path matching a configured Route} -H 'Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l'

凭证接口

• 查看所有basic-auths凭证信息

curl -X GET http://kong:8001/basic-auths

• 查看指定basic-auths凭证信息

curl -X GET http://kong:8001/consumers/{username or id}/basic-auths

HMAC Authentication

配置信息

• 基本描述

• 参数

使用详情

• 创建服务

curl -i -X POST http://localhost:8001/services -d "name=example-service" -d "url=http://example.com"

• 创建路由

curl -i -f -X POST http://localhost:8001/services/example-service/routes -d "paths[]=/"

• 创建插件

curl -i -X POST http://localhost:8001/services/example-service/plugins -d "name=hmac-auth" -d "config.enforce_headers=date, request-line" -d "config.algorithms=hmac-sha1, hmac-sha256"

• 创建消费者

curl -i -X POST http://localhost:8001/consumers/ -d "username=alice"

• 创建凭证

curl -i -X POST http://localhost:8001/consumers/alice/hmac-auth -d "username=alice123" -d "secret=secret"

• 使用凭证

curl -i -X GET http://localhost:8000/requests -H "Host: hmac.com" -H "Date: Thu, 22 Jun 2017 17:15:21 GMT" -H 'Authorization: hmac username="alice123", algorithm="hmac-sha256", headers="date request-line", signature="ujWCGHeec9Xd6UD2zlyxiNMCiXnDOWeVFMu5VeRUxtw="'

凭证接口

• 查看所有hmac-auths凭证信息

curl -X GET http://kong:8001/hmac-auths

• 查看指定hmac-auths凭证信息

curl -X GET http://kong:8001/consumers/{username or id}/hmac-auths

JWT

配置信息

• 基本描述

• 参数

使用详情

• 创建消费者

curl -d "username=user123&custom_id=SOME_CUSTOM_ID" http://kong:8001/consumers/

• 创建凭证

curl -X POST http://kong:8001/consumers/{consumer}/jwt -H "Content-Type: application/x-www-form-urlencoded"

• 使用凭证

curl http://kong:8000/{route path} -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhMzZjMzA0OWIzNjI0OWEzYzlmODg5MWNiMTI3MjQzYyIsImV4cCI6MTQ0MjQzMDA1NCwibmJmIjoxNDQyNDI2NDU0LCJpYXQiOjE0NDI0MjY0NTR9.AhumfY35GFLuEEjrOXiaADo7Ae6gt_8VLwX7qffhQN4'

或者

curl http://kong:8000/{route path}?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhMzZjMzA0OWIzNjI0OWEzYzlmODg5MWNiMTI3MjQzYyIsImV4cCI6MTQ0MjQzMDA1NCwibmJmIjoxNDQyNDI2NDU0LCJpYXQiOjE0NDI0MjY0NTR9.AhumfY35GFLuEEjrOXiaADo7Ae6gt_8VLwX7qffhQN4

或者

curl --cookie  jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhMzZjMzA0OWIzNjI0OWEzYzlmODg5MWNiMTI3MjQzYyIsImV4cCI6MTQ0MjQzMDA1NCwibmJmIjoxNDQyNDI2NDU0LCJpYXQiOjE0NDI0MjY0NTR9.AhumfY35GFLuEEjrOXiaADo7Ae6gt_8VLwX7qffhQN4 http://kong:8000/{route path}

• 删除凭证

curl -X DELETE http://kong:8001/consumers/{consumer}/jwt/{id}

• 查询凭证

curl -X GET http://kong:8001/consumers/{consumer}/jwt

加密详情

• 使用HS256签名

# 请求头
{
    "typ": "JWT",
    "alg": "HS256"
}

{
    "iss": "a36c3049b36249a3c9f8891cb127243c"
}

# token值
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhMzZjMzA0OWIzNjI0OWEzYzlmODg5MWNiMTI3MjQzYyIsImV4cCI6MTQ0MjQzMDA1NCwibmJmIjoxNDQyNDI2NDU0LCJpYXQiOjE0NDI0MjY0NTR9.AhumfY35GFLuEEjrOXiaADo7Ae6gt_8VLwX7qffhQN4

• 使用公私钥签名（RS256 or ES256）

# 创建凭证
curl -X POST http://kong:8001/consumers/{consumer}/jwt -F "rsa_public_key=@/path/to/public_key.pem"

# 请求头
{
    "typ": "JWT",
    "alg": "RS256"
}

{
    "iss": "a36c3049b36249a3c9f8891cb127243c"
}

# 使用凭证
curl http://kong:8000/{route path} -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIxM2Q1ODE0NTcyZTc0YTIyYjFhOWEwMDJmMmQxN2MzNyJ9.uNPTnDZXVShFYUSiii78Q-IAfhnc2ExjarZr_WVhGrHHBLweOBJxGJlAKZQEKE4rVd7D6hCtWSkvAAOu7BU34OnlxtQqB8ArGX58xhpIqHtFUkj882JQ9QD6_v2S2Ad-EmEx5402ge71VWEJ0-jyH2WvfxZ_pD90n5AG5rAbYNAIlm2Ew78q4w4GVSivpletUhcv31-U3GROsa7dl8rYMqx6gyo9oIIDcGoMh3bu8su5kQc5SQBFp1CcA5H8sHGfYs-Et5rCU2A6yKbyXtpHrd1Y9oMrZpEfQdgpLae0AfWRf6JutA9SPhst9-5rn4o3cdUmto_TBGqHsFmVyob8VQ'

凭证接口

• 查看所有jwt凭证信息

curl -X GET http://kong:8001/jwts

• 查看指定jwt凭证信息

curl -X GET http://kong:8001/consumers/{username or id}/jwts

Key Authentication

配置信息

• 基本描述

• 参数

使用详情

• 创建消费者

curl -d  "username=user123&custom_id=SOME_CUSTOM_ID" http://kong:8001/consumers/

• 创建凭证

curl -X POST http://kong:8001/consumers/{consumer}/key-auth -d ''

• 使用凭证

curl http://kong:8000/{proxy path}?apikey=<some_key>

或者

curl http://kong:8000/{proxy path} -H 'apikey: <some_key>'

• 删除凭证

curl -X DELETE http://kong:8001/consumers/{consumer}/key-auth/{id}

凭证接口

• 查看所有key-auths凭证信息

curl -X GET http://kong:8001/key-auths

• 查看指定key-auths凭证信息

curl -X GET http://kong:8001/consumers/{username or id}/key-auth

LDAP Authentication

配置信息

• 基本描述

• 参数

OAuth2.0 Authentication

配置信息

• 基本描述

• 参数

使用详情

• OAuth2端点

• 创建消费者

curl -X POST http://kong:8001/consumers/ --data "username=user123" --data "custom_id=SOME_CUSTOM_ID"

• 创建OAuth2.0应用

curl -X POST http://kong:8001/consumers/{consumer_id}/oauth2 --data "name=Test%20Application" --data "client_id=SOME-CLIENT-ID" --data "client_secret=SOME-CLIENT-SECRET" --data "redirect_uris=http://some-domain/endpoint/"

OAuth2.0 Client Credentials模式

Client Credentials模式开箱即用，无需构建任何授权页面，客户端需要使用 /oauth2/token 端点获取access token

OAuth2.0 Authorization Code模式

配置完消费者并且与OAuth2.0凭证关联之后，需要正确了解OAuth2.0的授权流程，与大多数Kong插件不同，OAuth2.0插件需要一些额外的工作才能运转正常
用户必须在Web应用中实现授权页面，该页面与插件的服务器端通信，用户需要在网站或文档中解释清楚如何使用受OAuth2.0保护的服务，这个开发者可以知道如何实现客户端程序
构建授权页面是插件无法开箱即用的部分，因为它需要检查用户是否已正确登录，此操作与用户身份校验的实现密切相关
授权页面由两部分组成：

• 用户看到的前端的页面，这将允许他授权客户端应用程序访问他的数据
• 后端将处理HTML表单中显示的信息，这个表单会与Kong上的OAuth2.0插件进行通信，并最终将用户重定向到第三方URL上

完整流程如下：

1. 客户端应用会将终端用户重定向到用户实现的授权页面上，并将 client_id、response_type 和 scope（如果需要的话） 作为参数传递过来；
2. 在展示真实的授权页面前，应用程序需要确保该用户已经正常登录了；
3. 客户端应用会通过参数将 client_id 传递给应用程序，应用程序向Kong发送指令取回OAuth2.0应用名和开发者名：

curl kong:8001/oauth2?client_id=XXX

4. 如果终端用户授权了客户端程序，表单将使用 POST 请求将 client_id、response_type 和 scope 提交到后端；
5. 后端在发送 POST 请求时还需要加入 provision_key 和 authenticated_userid 参数，如果客户端带入了 Authorization 头，请求也需要透传，其中 provision_key 是插件添加到服务时生成的密钥，authenticated_userid 是授予权限的用户的Id，请求大致如下：

curl https://your.service.com/oauth2/authorize --header "Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW" --data "client_id=XXX" --data "response_type=XXX" --data "scope=XXX" --data "provision_key=XXX" --data "authenticated_userid=XXX"

6. Kong响应大致如下，200 OK 或者 400 Bad Request 响应码取决请求是否成功：

{
   "redirect_uri": "http://some/url"
}

7. 无论哪种情况，忽略响应状态码，只需将用户重定向到 redirect_uri 属性返回的URI上；
8. 客户端应用将在此处获取它，并将继续使用Kong，而不与用户的应用进行其他交互；
9. 当获取到access token之后，客户端应用可以作为用户，向上游服务发起请求；
10. access token是会过期的，当发生这种情况时，客户端应用程序需要使用Kong续订访问令牌

在这些步骤中，用户需要实现的步骤有：

• 登录页（步骤2）
• 授权页面，以及后端简单地收集信息，向Kong发送请求，并重定向到Kong返回的URL上

Password Grant模式

Password Grant模式是一个比较简单的模式，但仍需要后端授权（无前端）才能正常工作：

1. 第一个请求中，客户端应用向应用程序发送请求，携带一些OAuth2的参数，包含用户名和密码；
2. 应用程序的后端会校验客户端发送的用户名和密码，如果校验成功，会将 provision_key、authenticated_userid 和 grant_type 这些参数添加到客户端最初发送的参数中，并向Kong的 /oauth2/token 端点发送 POST 请求，其中 provision_key 是插件添加到服务时生成的密钥，authenticated_userid 是授予权限的用户的Id，请求大致如下：

curl https://your.service.com/oauth2/token --header "Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW" --data "client_id=XXX" --data "client_secret=XXX" --data "grant_type=password" --data "scope=XXX" --data "provision_key=XXX" --data "authenticated_userid=XXX" --data "username=XXX" --data "password=XXX"

3. Kong返回一个JSON响应；
4. Kong的响应必须原样发送回客户端，如果操作成功，响应中会包含access token，否则会包含错误

在这些步骤中，用户需要实现的步骤有：
后端端点将处理原始请求并验证客户端发送的用户名和密码，如果验证成功，则向Kong发出请求并返回客户端，无论Kong响应什么内容

刷新Token

当用户的access token过期时，用户可以使用refresh token生成新的access token

curl -X POST https://your.service.com/oauth2/token --data "grant_type=refresh_token" --data "client_id=XXX" --data "client_secret=XXX" --data "refresh_token=XXX"

安全插件

CORS

配置信息

• 基本描述

• 参数

使用详情

• 在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=cors" --data "config.origins=http://mockbin.com" --data "config.methods=GET" --data "config.methods=POST" --data "config.headers=Accept" --data "config.headers=Accept-Version" --data "config.headers=Content-Length" --data "config.headers=Content-MD5" --data "config.headers=Content-Type" --data "config.headers=Date" --data "config.headers=X-Auth-Token" --data "config.exposed_headers=X-Auth-Token" --data "config.credentials=true" --data "config.max_age=3600"

• 在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=cors" --data "config.origins=http://mockbin.com" --data "config.methods=GET" --data "config.methods=POST" --data "config.headers=Accept" --data "config.headers=Accept-Version" --data "config.headers=Content-Length" --data "config.headers=Content-MD5" --data "config.headers=Content-Type" --data "config.headers=Date" --data "config.headers=X-Auth-Token" --data "config.exposed_headers=X-Auth-Token" --data "config.credentials=true" --data "config.max_age=3600"

IP Restriction

配置信息

• 基本描述

• 参数

使用详情

• 在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=ip-restriction" --data "config.whitelist=54.13.21.1" --data "config.whitelist=143.1.0.0/24"

• 在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=ip-restriction" --data "config.whitelist=54.13.21.1" --data "config.whitelist=143.1.0.0/24"

• 在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=ip-restriction" --data "config.whitelist=54.13.21.1" --data "config.whitelist=143.1.0.0/24"

注意，白名单 和 黑名单模型在使用中是互斥的，它们提供了互补的方法，也就是说，用户无法既用白名单 ，又用黑名单配置插件，白名单提供了积极的安全模型，只允许配置范围内的ip访问资源，其他全部拒绝；黑名单提供了被动的安全模型，只拒绝配置范围内的ip访问资源，其他全部允许

流量控制插件

ACL

配置信息

• 基本描述

• 参数

使用详情

• 在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=acl" --data "config.whitelist=group1" --data "config.whitelist=group2" --data "config.hide_groups_header=true"

• 在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=acl" --data "config.whitelist=group1" --data "config.whitelist=group2" --data "config.hide_groups_header=true"

• 在消费者上添加ACL组属性

curl -X POST http://kong:8001/consumers/{consumer}/acls --data "group=group1"

凭证接口

• 查询所有消费者的ACL组

curl -X GET http://kong:8001/acls

• 查询指定消费者的ACL组

curl -X GET http://kong:8001/consumers/{username or id}/acls

• 查询ACL组Id关联的消费者

curl -X GET http://kong:8001/acls/{id}/consumer

Proxy Caching

配置信息

• 基本描述

• 参数

使用详情

• 在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=proxy-cache" --data "config.strategy=memory"

• 在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=proxy-cache" --data "config.strategy=memory"

• 在消费者上添加插件

curl -X POST http://kong:8001/apis/{api}/plugins --data "name=proxy-cache" --data "config.strategy=memory"

• 缓存策略

• 缓存Key
  Kong基于请求方法、完整的客户端请求（路径和请求参数）和绑定在请求上的API或消费者UUID来生成缓存 Key，所以各个API或消费者之间的缓存都是不同的，目前缓存Key的格式是硬编码的，无法调整，缓存的组成方式如下：

key = md5(UUID | method | request)

其中 method 是通过 ngx.req.get_method() 方法获得的，request 是根据 Nginx $request 变量获得的，Kong会在响应的 X-Cache-Key 头中返回缓存Key值，如上所述，可以预先计算缓存Key

• 缓存控制
  当启用 cache_control 时，Kong将遵守 Cache-Control 头的使用规范，有一些例外情况：

1. 不支持缓存重新验证
2. 类似地，no-cache 排除缓存存在
3. 不支持根据 Vary 计算二级缓存

• 缓存状态
  Kong通过 X-Cache-Status 头表示缓存行为的状态：

• 存储TTL
  Kong可以在存储引擎中存储数据，存储时间超过 cache_ttl 或 Cache-Control 阈值所限定的时间，这使得Kong在资源过期后，还能维持一份资源的缓存副本，这样客户端在必要时可以使用 max-age 或 max-stale 头请求过期的数据

缓存API

• 获取缓存实体
  GET /proxy-cache/:plugin_id/caches/:cache_id
  GET /proxy-cache/:cache_id
• 删除缓存实体
  DELETE /proxy-cache/:plugin_id/caches/:cache_id
  DELETE /proxy-cache/:cache_id
• 清除所有缓存
  DELETE /proxy-cache/

Rate Limiting

配置信息

• 基本描述

• 参数

使用详情

• 在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=rate-limiting" --data "config.second=5" --data "config.hour=10000"

• 在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=rate-limiting" --data "config.second=5" --data "config.hour=10000"

• 在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=rate-limiting" --data "config.second=5" --data "config.hour=10000"

• 返回给客户端的头部信息

X-RateLimit-Limit-Second: 5
X-RateLimit-Remaining-Second: 4
X-RateLimit-Limit-Minute: 10
X-RateLimit-Remaining-Minute: 9

• 实施细节

1. 事务粒度
   这个场景中，不能选用 local 策略，应该在 cluster 或 redis 策略中考量，推荐是先尝试使用 cluster 策略，如果性能急速下降，则切换成 redis 策略，需要注意的是，指标数据无法从原有数据源切换到redis，通常来说，短周期指标（如秒、分）不受影响，长周期指标（月）可能会有影响，所以切换数据源时需要小心
2. 后端保护模式
   这种场景中因为准确性不太重要，可以使用 local 策略，这需要多些尝试才能找到合适的值，比如用户希望配置限流每秒100个请求，总共有5个Kong节点，设置 local 策略，每秒30个请求，大致可以满足需求，如果觉得返回的失败过于频繁，可以适当增大阈值
   需要注意的是，当增加Kong节点时，会增加总请求数；同理减少Kong节点时，会降低总请求数，所以调整节点数时需要同步调整阈值
   在Kong节点前使用Hash一致性负载均衡器可以避免上述的问题，因为它会保证相同的用户会路由到指定的Kong节点，保证数据准确，并且不受节点缩放的影响
   通常情况下，真实的请求数会大于限流的阈值，但是它还是能有效的防止攻击，并且保持最佳性能

RequestTermination

配置信息

• 基本描述

• 参数

使用详情

• 在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=request-termination" --data "config.status_code=403" --data "config.message=So long and thanks for all the fish!"

• 在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=request-termination" --data "config.status_code=403" --data "config.message=So long and thanks for all the fish!"

• 在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=request-termination" --data "config.status_code=403" --data "config.message=So long and thanks for all the fish!"

• 使用场景

1. 临时禁用某个服务（比如正在维护中）
2. 临时禁用某个路由（比如需要禁用某个端点）
3. 临时禁用某个消费者（比如过度消费）
4. 阻止匿名访问

Kong Service Virtualization

配置信息

• 基本描述

• 参数

• JSON配置项

使用详情

• 在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=kong-service-virtualization" --data "config.virtual_tests={"name"=>"TestCase1", "requestHttpMethod"=>"POST", "requestHash"=>"0296217561490155228da9c17fc555cf9db82d159732f3206638c25f04a285c4", "responseHttpStatus"=>"200", "responseContentType"=>"application/json", "response"=>"eyJtZXNzYWdlIjogIkEgQmlnIFN1Y2Nlc3MhIn0="}" --data "config.virtual_tests={"name"=>"TestCase2", "requestHttpMethod"=>"GET", "requestHash"=>"e2c319e4ef41706e2c0c1b266c62cad607a014c59597ba662bef6d10a0b64a32", "responseHttpStatus"=>"200", "responseContentType"=>"application/json", "response"=>"eyJtZXNzYWdlIjogIkFub3RoZXIgU3VjY2VzcyEifQ=="}"

• 在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=kong-service-virtualization" --data "config.virtual_tests={"name"=>"TestCase1", "requestHttpMethod"=>"POST", "requestHash"=>"0296217561490155228da9c17fc555cf9db82d159732f3206638c25f04a285c4", "responseHttpStatus"=>"200", "responseContentType"=>"application/json", "response"=>"eyJtZXNzYWdlIjogIkEgQmlnIFN1Y2Nlc3MhIn0="}" --data "config.virtual_tests={"name"=>"TestCase2", "requestHttpMethod"=>"GET", "requestHash"=>"e2c319e4ef41706e2c0c1b266c62cad607a014c59597ba662bef6d10a0b64a32", "responseHttpStatus"=>"200", "responseContentType"=>"application/json", "response"=>"eyJtZXNzYWdlIjogIkFub3RoZXIgU3VjY2VzcyEifQ=="}"

• 安装插件

1. 推荐安装方式

luarocks install kong-service-virtualization

2. 其他选择安装方式

git clone https://github.com/Optum/kong-service-virtualization
cd /path/to/kong/plugins/kong-service-virtualization
luarocks make *.rockspec

• virtual_tests参数详解

[
     {
        "name": "TestCase1",           
        "requestHttpMethod": "POST",
        "requestHash": "0296217561490155228da9c17fc555cf9db82d159732f3206638c25f04a285c4",
        "responseHttpStatus": "200",
        "responseContentType": "application/json",
        "response": "eyJtZXNzYWdlIjogIkEgQmlnIFN1Y2Nlc3MhIn0="
    },
    {         
        "name": "TestCase2",           
        "requestHttpMethod": "GET",
        "requestHash": "e2c319e4ef41706e2c0c1b266c62cad607a014c59597ba662bef6d10a0b64a32",
        "responseHttpStatus": "200",
        "responseContentType": "application/json",
        "response": "eyJtZXNzYWdlIjogIkFub3RoZXIgU3VjY2VzcyEifQ=="
    }
]

上述的请求相当于：

https://gateway.company.com/virtualtest
POST:
{
   "virtual": "test"
}
Response : {"message": "A Big Success!"} as base64 encoded in plugin
GET:
hello=world&service=virtualized
Response : {"message": "Another Success!"} as base4 encoded in plugin

日志插件

HTTP Log

配置信息

• 基本描述

• 参数

使用详情

• 在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=http-log" --data "config.http_endpoint=http://mockbin.org/bin/:id" --data "config.method=POST" --data "config.timeout=1000" --data "config.keepalive=1000"

• 在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=http-log" --data "config.http_endpoint=http://mockbin.org/bin/:id" --data "config.method=POST" --data "config.timeout=1000" --data "config.keepalive=1000"

• 在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=http-log" --data "config.http_endpoint=http://mockbin.org/bin/:id" --data "config.method=POST" --data "config.timeout=1000" --data "config.keepalive=1000"

日志格式

{
    "request": {
        "method": "GET",
        "uri": "/get",
        "url": "http://httpbin.org:8000/get",
        "size": "75",
        "querystring": {},
        "headers": {
            "accept": "*/*",
            "host": "httpbin.org",
            "user-agent": "curl/7.37.1"
        },
        "tls": {
            "version": "TLSv1.2",
            "cipher": "ECDHE-RSA-AES256-GCM-SHA384",
            "supported_client_ciphers": "ECDHE-RSA-AES256-GCM-SHA384",
            "client_verify": "NONE"
        }
    },
    "upstream_uri": "/",
    "response": {
        "status": 200,
        "size": "434",
        "headers": {
            "Content-Length": "197",
            "via": "kong/0.3.0",
            "Connection": "close",
            "access-control-allow-credentials": "true",
            "Content-Type": "application/json",
            "server": "nginx",
            "access-control-allow-origin": "*"
        }
    },
    "tries": [
        {
            "state": "next",
            "code": 502,
            "ip": "127.0.0.1",
            "port": 8000
        },
        {
            "ip": "127.0.0.1",
            "port": 8000
        }
    ],
    "authenticated_entity": {
        "consumer_id": "80f74eef-31b8-45d5-c525-ae532297ea8e",
        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e"
    },
    "route": {
        "created_at": 1521555129,
        "hosts": null,
        "id": "75818c5f-202d-4b82-a553-6a46e7c9a19e",
        "methods": null,
        "paths": [
            "/example-path"
        ],
        "preserve_host": false,
        "protocols": [
            "http",
            "https"
        ],
        "regex_priority": 0,
        "service": {
            "id": "0590139e-7481-466c-bcdf-929adcaaf804"
        },
        "strip_path": true,
        "updated_at": 1521555129
    },
    "service": {
        "connect_timeout": 60000,
        "created_at": 1521554518,
        "host": "example.com",
        "id": "0590139e-7481-466c-bcdf-929adcaaf804",
        "name": "myservice",
        "path": "/",
        "port": 80,
        "protocol": "http",
        "read_timeout": 60000,
        "retries": 5,
        "updated_at": 1521554518,
        "write_timeout": 60000
    },
    "workspaces": [
        {
            "id":"b7cac81a-05dc-41f5-b6dc-b87e29b6c3a3",
            "name": "default"
        }
    ],
    "consumer": {
        "username": "demo",
        "created_at": 1491847011000,
        "id": "35b03bfc-7a5b-4a23-a594-aa350c585fa8"
    },
    "latencies": {
        "proxy": 1430,
        "kong": 9,
        "request": 1921
    },
    "client_ip": "127.0.0.1",
    "started_at": 1433209822425
}

TCP Log

配置信息

• 基本描述

• 参数

使用详情

• 在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=tcp-log" --data "config.host=127.0.0.1" --data "config.port=9999"

• 在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=tcp-log" --data "config.host=127.0.0.1" --data "config.port=9999"

• 在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=tcp-log" --data "config.host=127.0.0.1" --data "config.port=9999"

日志格式

{
    "request": {
        "method": "GET",
        "uri": "/get",
        "url": "http://httpbin.org:8000/get",
        "size": "75",
        "querystring": {},
        "headers": {
            "accept": "*/*",
            "host": "httpbin.org",
            "user-agent": "curl/7.37.1"
        },
        "tls": {
            "version": "TLSv1.2",
            "cipher": "ECDHE-RSA-AES256-GCM-SHA384",
            "supported_client_ciphers": "ECDHE-RSA-AES256-GCM-SHA384",
            "client_verify": "NONE"
        }
    },
    "upstream_uri": "/",
    "response": {
        "status": 200,
        "size": "434",
        "headers": {
            "Content-Length": "197",
            "via": "kong/0.3.0",
            "Connection": "close",
            "access-control-allow-credentials": "true",
            "Content-Type": "application/json",
            "server": "nginx",
            "access-control-allow-origin": "*"
        }
    },
    "tries": [
        {
            "state": "next",
            "code": 502,
            "ip": "127.0.0.1",
            "port": 8000
        },
        {
            "ip": "127.0.0.1",
            "port": 8000
        }
    ],
    "authenticated_entity": {
        "consumer_id": "80f74eef-31b8-45d5-c525-ae532297ea8e",
        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e"
    },
    "route": {
        "created_at": 1521555129,
        "hosts": null,
        "id": "75818c5f-202d-4b82-a553-6a46e7c9a19e",
        "methods": null,
        "paths": [
            "/example-path"
        ],
        "preserve_host": false,
        "protocols": [
            "http",
            "https"
        ],
        "regex_priority": 0,
        "service": {
            "id": "0590139e-7481-466c-bcdf-929adcaaf804"
        },
        "strip_path": true,
        "updated_at": 1521555129
    },
    "service": {
        "connect_timeout": 60000,
        "created_at": 1521554518,
        "host": "example.com",
        "id": "0590139e-7481-466c-bcdf-929adcaaf804",
        "name": "myservice",
        "path": "/",
        "port": 80,
        "protocol": "http",
        "read_timeout": 60000,
        "retries": 5,
        "updated_at": 1521554518,
        "write_timeout": 60000
    },
    "workspaces": [
        {
            "id":"b7cac81a-05dc-41f5-b6dc-b87e29b6c3a3",
            "name": "default"
        }
    ],
    "consumer": {
        "username": "demo",
        "created_at": 1491847011000,
        "id": "35b03bfc-7a5b-4a23-a594-aa350c585fa8"
    },
    "latencies": {
        "proxy": 1430,
        "kong": 9,
        "request": 1921
    },
    "client_ip": "127.0.0.1",
    "started_at": 1433209822425
}

UDP Log

配置信息

• 基本描述

• 参数

使用详情

• 在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=udp-log" --data "config.host=127.0.0.1" --data "config.port=9999" --data "config.timeout=10000"

• 在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=udp-log" --data "config.host=127.0.0.1" --data "config.port=9999" --data "config.timeout=10000"

• 在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=udp-log" --data "config.host=127.0.0.1" --data "config.port=9999" --data "config.timeout=10000"

日志格式

{
    "request": {
        "method": "GET",
        "uri": "/get",
        "url": "http://httpbin.org:8000/get",
        "size": "75",
        "querystring": {},
        "headers": {
            "accept": "*/*",
            "host": "httpbin.org",
            "user-agent": "curl/7.37.1"
        },
        "tls": {
            "version": "TLSv1.2",
            "cipher": "ECDHE-RSA-AES256-GCM-SHA384",
            "supported_client_ciphers": "ECDHE-RSA-AES256-GCM-SHA384",
            "client_verify": "NONE"
        }
    },
    "upstream_uri": "/",
    "response": {
        "status": 200,
        "size": "434",
        "headers": {
            "Content-Length": "197",
            "via": "kong/0.3.0",
            "Connection": "close",
            "access-control-allow-credentials": "true",
            "Content-Type": "application/json",
            "server": "nginx",
            "access-control-allow-origin": "*"
        }
    },
    "tries": [
        {
            "state": "next",
            "code": 502,
            "ip": "127.0.0.1",
            "port": 8000
        },
        {
            "ip": "127.0.0.1",
            "port": 8000
        }
    ],
    "authenticated_entity": {
        "consumer_id": "80f74eef-31b8-45d5-c525-ae532297ea8e",
        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e"
    },
    "route": {
        "created_at": 1521555129,
        "hosts": null,
        "id": "75818c5f-202d-4b82-a553-6a46e7c9a19e",
        "methods": null,
        "paths": [
            "/example-path"
        ],
        "preserve_host": false,
        "protocols": [
            "http",
            "https"
        ],
        "regex_priority": 0,
        "service": {
            "id": "0590139e-7481-466c-bcdf-929adcaaf804"
        },
        "strip_path": true,
        "updated_at": 1521555129
    },
    "service": {
        "connect_timeout": 60000,
        "created_at": 1521554518,
        "host": "example.com",
        "id": "0590139e-7481-466c-bcdf-929adcaaf804",
        "name": "myservice",
        "path": "/",
        "port": 80,
        "protocol": "http",
        "read_timeout": 60000,
        "retries": 5,
        "updated_at": 1521554518,
        "write_timeout": 60000
    },
    "workspaces": [
        {
            "id":"b7cac81a-05dc-41f5-b6dc-b87e29b6c3a3",
            "name": "default"
        }
    ],
    "consumer": {
        "username": "demo",
        "created_at": 1491847011000,
        "id": "35b03bfc-7a5b-4a23-a594-aa350c585fa8"
    },
    "latencies": {
        "proxy": 1430,
        "kong": 9,
        "request": 1921
    },
    "client_ip": "127.0.0.1",
    "started_at": 1433209822425
}

转换插件

Correlation ID

配置信息

• 基本描述

• 参数

使用详情

• 在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=correlation-id" --data "config.header_name=Kong-Request-ID" --data "config.generator=uuid#counter" --data "config.echo_downstream=false"

• 在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=correlation-id" --data "config.header_name=Kong-Request-ID" --data "config.generator=uuid#counter" --data "config.echo_downstream=false"

• 在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=correlation-id" --data "config.header_name=Kong-Request-ID" --data "config.generator=uuid#counter" --data "config.echo_downstream=false"

ID生成器

• uuid
  格式：

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

使用这种格式时，每个请求以十六进制形式生成UUID

• uuid#counter
  格式：

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx#counter

使用这种格式时，基于每个 worker 生成UUID，之后的请求会在UUID之后添加一个累加器，每个计数器从0开始计数，每个 worker 之间都是独立的，这种格式性能比较高，但是比较难以存储并进一步进行处理

• tracker
  格式：

ip-port-pid-connection-connection_requests-timestamp

使用这种格式时，关联Id更有实际意义：

Request Transformer

配置信息

• 基本描述

• 参数

使用详情

• 在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=request-transformer" --data "config.remove.headers=x-toremove" --data "config.remove.headers=x-another-one" --data "config.remove.querystring=qs-old-name:qs-new-name" --data "config.remove.querystring=qs2-old-name:qs2-new-name" --data "config.remove.body=formparam-toremove" --data "config.remove.body=formparam-another-one" --data "config.rename.headers=header-old-name:header-new-name" --data "config.rename.headers=another-old-name:another-new-name" --data "config.rename.querystring=qs-old-name:qs-new-name" --data "config.rename.querystring=qs2-old-name:qs2-new-name" --data "config.rename.body=param-old:param-new" --data "config.rename.body=param2-old:param2-new" --data "config.add.headers=x-new-header:value" --data "config.add.headers=x-another-header:something" --data "config.add.querystring=new-param:some_value" --data "config.add.querystring=another-param:some_value" --data "config.add.body=new-form-param:some_value" --data "config.add.body=another-form-param:some_value"

• 在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=request-transformer" --data "config.remove.headers=x-toremove" --data "config.remove.headers=x-another-one" --data "config.remove.querystring=qs-old-name:qs-new-name" --data "config.remove.querystring=qs2-old-name:qs2-new-name" --data "config.remove.body=formparam-toremove" --data "config.remove.body=formparam-another-one" --data "config.rename.headers=header-old-name:header-new-name" --data "config.rename.headers=another-old-name:another-new-name" --data "config.rename.querystring=qs-old-name:qs-new-name" --data "config.rename.querystring=qs2-old-name:qs2-new-name" --data "config.rename.body=param-old:param-new" --data "config.rename.body=param2-old:param2-new" --data "config.add.headers=x-new-header:value" --data "config.add.headers=x-another-header:something" --data "config.add.querystring=new-param:some_value" --data "config.add.querystring=another-param:some_value" --data "config.add.body=new-form-param:some_value" --data "config.add.body=another-form-param:some_value"

• 在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=request-transformer" --data "config.remove.headers=x-toremove" --data "config.remove.headers=x-another-one" --data "config.remove.querystring=qs-old-name:qs-new-name" --data "config.remove.querystring=qs2-old-name:qs2-new-name" --data "config.remove.body=formparam-toremove" --data "config.remove.body=formparam-another-one" --data "config.rename.headers=header-old-name:header-new-name" --data "config.rename.headers=another-old-name:another-new-name" --data "config.rename.querystring=qs-old-name:qs-new-name" --data "config.rename.querystring=qs2-old-name:qs2-new-name" --data "config.rename.body=param-old:param-new" --data "config.rename.body=param2-old:param2-new" --data "config.add.headers=x-new-header:value" --data "config.add.headers=x-another-header:something" --data "config.add.querystring=new-param:some_value" --data "config.add.querystring=another-param:some_value" --data "config.add.body=new-form-param:some_value" --data "config.add.body=another-form-param:some_value"

• 参数执行顺序
  删除 -> 重命名 -> 替换 -> 添加 -> 追加

Response Transformer

配置信息

• 基本描述

• 参数

使用详情

• 在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=response-transformer" --data "config.remove.headers=x-toremove, x-another-one" --data "config.remove.json=json-key-toremove, another-json-key" --data "config.add.headers=x-new-header:value,x-another-header:something" --data "config.add.json=new-json-key:some_value, another-json-key:some_value" --data "config.append.headers=x-existing-header:some_value, x-another-header:some_value"

• 在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=response-transformer" --data "config.remove.headers=x-toremove, x-another-one" --data "config.remove.json=json-key-toremove, another-json-key" --data "config.add.headers=x-new-header:value,x-another-header:something" --data "config.add.json=new-json-key:some_value, another-json-key:some_value" --data "config.append.headers=x-existing-header:some_value, x-another-header:some_value"

• 在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=response-transformer" --data "config.remove.headers=x-toremove, x-another-one" --data "config.remove.json=json-key-toremove, another-json-key" --data "config.add.headers=x-new-header:value,x-another-header:something" --data "config.add.json=new-json-key:some_value, another-json-key:some_value" --data "config.append.headers=x-existing-header:some_value, x-another-header:some_value"

• 参数执行顺序
  删除 -> 替换 -> 添加 -> 追加