您可以通過本外掛程式配置自己的鑒權服務為API的訪問進行鑒權。
1. 概述
API Gateway在調用API後端服務之前將先調用使用者的鑒權服務，收到鑒權服務的鑒權成功應答後才會繼續調用後端服務，否則給用戶端返回鑒權失敗的應答。第三方鑒權外掛程式支援的功能如下：
允許使用者自訂發送給鑒權服務的請求參數。
允許使用者將鑒權應答結果在API Gateway緩衝一定時間，保持業務的平滑度。
允許使用者自訂鑒權失敗的應答。
2. 外掛程式配置
重要
2023-05-09 之前購買的專享執行個體，如果不生效需提交工單聯絡我們給您升級執行個體版本。
2.1 當鑒權服務為公網地址時，外掛程式配置樣本如下：
---
parameters: # 鑒權結果運算式中使用到的參數定義
statusCode: "StatusCode" # http應答碼
authUriType: "HTTP" # 鑒權服務類型：HTTP:公網的鑒權地址，HTTP-VPC:VPC授權地址
authUri: # 鑒權服務定義
address: "http://auth.com:8080" # 鑒權服務地址，包括連接埠號碼
path: "/auth" # 鑒權服務路徑
timeout: 7000 # 鑒權服務逾時時間，最大為10秒
method: POST # 鑒權服務HTTP Method
passThroughBody: false # 是否將請求的body透傳給鑒權服務
passThroughPath: true # 如果為true，請求path將放到X-Ca-Remote-Auth-Raw-Path頭中發送給鑒權服務
cachedTimeBySecond: 10 # API Gateway緩衝鑒權結果應答的時間，最長為10分鐘（目前緩衝是將所有apiuid+authparameters作為主鍵去緩衝的）
trimAuthorizationHeaderPrefix: true # 如果鑒權參數位置在Authorization頭中，智能跳過首碼提取參數內容，比如從Authorization:bearer hello這個頭提取出來的值是hello，而不是bearer hello
authParameters: # 發送給鑒權服務的參數映射
- targetParameterName: x-userId # 發送給鑒權服務的參數名稱
sourceParameterName: userId # 對應的原始請求中的參數名稱
targetLocation: query # 發送給鑒權服務的參數位置
sourceLocation: query # 對應的原始請求中的參數位置
- targetParameterName: x-password # 發送給鑒權服務的參數名稱
sourceParameterName: password # 對應的原始請求中的參數名稱
targetLocation: query # 發送給鑒權服務的參數位置
sourceLocation: query # 對應的原始請求中的參數位置
- targetParameterName: token
sourceParameterName: Authorization
targetLocation: query
sourceLocation: header
successCondition: "${statusCode} = 200" # 判斷鑒權應答的運算式，運算式為True表示鑒權成功
errorMessage: "auth failed" # 鑒權失敗時，用戶端收到的應答x-ca-errormessage頭的值
errorStatusCode : 401 # 鑒權失敗時，用戶端收到的http status值
errorPassThroughHeaderList: auth-result1,auth-result2 # 鑒權失敗時，透傳鑒權應答的指定頭給用戶端
errorPassThroughBody: true # 鑒權失敗時，將鑒權應答的body透傳給用戶端
ignoreAuthException: true # 如果鑒權發生Exception，比如逾時，串連出錯，忽略鑒權結果，直接存取後端綁定了此外掛程式的API，API Gateway在處理相關請求的時候，會先根據定義組裝一個鑒權請求發送給“http://auth.com:8080”，並且根據應答判斷鑒權是否通過。如果鑒權沒有通過，可以定製鑒權失敗的應答返回給用戶端。
2.2 當鑒權服務在VPC資源內時，需先給鑒權服務建立VPC授權，外掛程式配置樣本如下：
---
parameters: # 鑒權結果運算式中使用到的參數定義
statusCode: "StatusCode" # http應答碼
authUriType: "HTTP-VPC" # 鑒權服務類型：HTTP為公網的鑒權地址，HTTP-VPC為VPC授權地址
authUri: # 鑒權服務定義
vpcAccessName: "slbAccessForVip" # 鑒權服務的VPC授權名稱
path: "/auth" # 鑒權服務路徑
timeout: 7000 # 鑒權服務逾時時間，最大為10秒
method: POST # 鑒權服務HTTP Method
passThroughBody: false # 是否將請求的body透傳給鑒權服務
cachedTimeBySecond: 10 # API Gateway緩衝鑒權結果應答的時間，最長為10分鐘（目前緩衝是將所有apiuid+authparameters作為主鍵去緩衝的）
authParameters: # 發送給鑒權服務的參數映射
- targetParameterName: x-userId # 發送給鑒權服務的參數名稱
sourceParameterName: userId # 對應的原始請求中的參數名稱
targetLocation: query # 發送給鑒權服務的參數位置
sourceLocation: query # 對應的原始請求中的參數位置
- targetParameterName: x-password # 發送給鑒權服務的參數名稱
sourceParameterName: password # 對應的原始請求中的參數名稱
targetLocation: query # 發送給鑒權服務的參數位置
sourceLocation: query # 對應的原始請求中的參數位置
successCondition: "${statusCode} = 200" # 判斷鑒權應答的運算式，運算式為True表示鑒權成功
errorMessage: "auth failed" # 鑒權失敗時，用戶端收到的應答x-ca-errormessage頭的值
errorStatusCode : 401 # 鑒權失敗時，用戶端收到的http status值
errorPassThroughHeaderList: auth-result1,auth-result2 # 鑒權失敗時，透傳鑒權應答的指定頭給用戶端
errorPassThroughBody: true # 鑒權失敗時，將鑒權應答的body透傳給用戶端
ignoreAuthException: true # 如果鑒權發生Exception，比如逾時，串連出錯，忽略鑒權結果，直接存取後端2.3 支援提取鑒權結果Body中的JSON中的欄位作為運算式的參數
---
parameters: # 鑒權結果運算式中使用到的參數定義
clientId: "BodyJsonField:$.clientId"# 鑒權應答BODY中的JSON結構中的參數名為clientId
authUriType: "HTTP-VPC" # 鑒權服務類型：HTTP:公網的鑒權地址，HTTP-VPC:VPC授權地址
authUri: # 鑒權服務定義
vpcAccessName: "slbAccessForVip" # 鑒權服務的VPC授權名稱
vpcScheme: "https" # 鑒權服務合約指定HTTPS，不指定預設是HTTP
path: "/auth" # 鑒權服務路徑
timeout: 7000 # 鑒權服務逾時時間，最大為10秒
method: POST # 鑒權服務HTTP Method
passThroughBody: false # 是否將請求的body透傳給鑒權服務
cachedTimeBySecond: 10 # API Gateway緩衝鑒權結果應答的時間，最長為10分鐘（目前緩衝是將所有apiuid+authparameters作為主鍵去緩衝的）
authParameters: # 發送給鑒權服務的參數映射
- targetParameterName: x-userId # 發送給鑒權服務的參數名稱
sourceParameterName: userId # 對應的原始請求中的參數名稱
targetLocation: query # 發送給鑒權服務的參數位置
sourceLocation: query # 對應的原始請求中的參數位置
- targetParameterName: x-password # 發送給鑒權服務的參數名稱
sourceParameterName: password # 對應的原始請求中的參數名稱
targetLocation: query # 發送給鑒權服務的參數位置
sourceLocation: query # 對應的原始請求中的參數位置
successCondition: "${clientId} = 10086" # 判斷鑒權應答的運算式，運算式為True表示鑒權成功
errorMessage: "auth failed" # 鑒權失敗時，用戶端收到的應答x-ca-errormessage頭的值
errorStatusCode : 401 # 鑒權失敗時，用戶端收到的http status值
errorPassThroughHeaderList: auth-result1,auth-result2 # 鑒權失敗時，透傳鑒權應答的指定頭給用戶端
errorPassThroughBody: true # 鑒權失敗時，將鑒權應答的body透傳給用戶端
ignoreAuthException: true # 如果鑒權發生Exception，比如逾時，串連出錯，忽略鑒權結果，直接存取後端如果鑒權服務返回的應答中的clientId欄位為10086，那麼鑒權就成功。
{"code":200,"clientId":10086}2.4 支援提取鑒權結果與外掛程式資料集進行身份鑒權，實現動態白名單
使用者通過外掛程式資料集儲存一份白名單資料，API Gateway從第三方鑒權結果的應答中提取使用者身份欄位，並且驗證使用者身份是否在白名單中，只有白名單中使用者才能通過鑒權。
---
parameters: # 鑒權結果運算式中使用到的參數定義
statusCode: "StatusCode" # http應答碼
clientId: "BodyJsonField:$.clientId"# 鑒權應答BODY中的JSON結構中的參數名為clientId
authUriType: "HTTP-VPC" # 鑒權服務類型：HTTP:公網的鑒權地址，HTTP-VPC:VPC授權地址
authUri: # 鑒權服務定義
vpcAccessName: "slbAccessForVip" # 鑒權服務的VPC授權名稱
path: "/auth" # 鑒權服務路徑
timeout: 7000 # 鑒權服務逾時時間，最大為10秒
method: POST # 鑒權服務HTTP Method
passThroughBody: false # 是否將請求的body透傳給鑒權服務
cachedTimeBySecond: 10 # API Gateway緩衝鑒權結果應答的時間，最長為10分鐘（目前緩衝是將所有apiuid+authparameters作為主鍵去緩衝的）
authParameters: # 發送給鑒權服務的參數映射
- targetParameterName: x-userId # 發送給鑒權服務的參數名稱
sourceParameterName: userId # 對應的原始請求中的參數名稱
targetLocation: query # 發送給鑒權服務的參數位置
sourceLocation: query # 對應的原始請求中的參數位置
- targetParameterName: x-password # 發送給鑒權服務的參數名稱
sourceParameterName: password # 對應的原始請求中的參數名稱
targetLocation: query # 發送給鑒權服務的參數位置
sourceLocation: query # 對應的原始請求中的參數位置
successCondition: "${statusCode} = 200" # 判斷鑒權應答的運算式
accessParameterName: clientId # 參與資料集內資料進行比對的參數名稱
accessByDataSet: dataset_test # 參與鑒權的資料集，如果資料集內資料包含了clientId的值，那麼鑒權就通過
errorMessage: "auth failed" # 鑒權失敗時，用戶端收到的應答x-ca-errormessage頭的值
errorStatusCode : 401 # 鑒權失敗時，用戶端收到的http status值
errorPassThroughHeaderList: auth-result1,auth-result2 # 鑒權失敗時，透傳鑒權應答的指定頭給用戶端
errorPassThroughBody: true # 鑒權失敗時，將鑒權應答的body透傳給用戶端
ignoreAuthException: true # 如果鑒權發生Exception，比如逾時，串連出錯，忽略鑒權結果，直接存取後端如果鑒權服務返回的應答中的clientId欄位值在名稱為dataset_test的外掛程式資料集中存在，那麼鑒權就成功。
2.5 支援與APP驗證融合
---
parameters: # 鑒權結果運算式中使用到的參數定義
statusCode: "StatusCode" # http應答碼
authUriType: "HTTP-VPC" # 鑒權服務類型：HTTP:公網的鑒權地址，HTTP-VPC:VPC授權地址
authUri: # 鑒權服務定義
vpcAccessName: "slbAccessForVip" # 鑒權服務的VPC授權名稱
path: "/auth" # 鑒權服務路徑
timeout: 7000 # 鑒權服務逾時時間，最大為10秒
method: POST # 鑒權服務HTTP Method
cachedTimeBySecond: 10 # API Gateway緩衝鑒權結果應答的時間，最長為10分鐘（目前緩衝是將所有apiuid+authparameters作為主鍵去緩衝的）
authParameters: # 發送給鑒權服務的參數映射
- targetParameterName: x-password # 發送給鑒權服務的參數名稱
sourceParameterName: password # 對應的原始請求中的參數名稱
targetLocation: query # 發送給鑒權服務的參數位置
sourceLocation: query # 對應的原始請求中的參數位置
successCondition: "${statusCode} = 200" # 判斷鑒權應答的運算式
errorMessage: "auth failed" # 鑒權失敗時，用戶端收到的應答x-ca-errormessage頭的值
errorStatusCode : 401 # 鑒權失敗時，用戶端收到的http status值
errorPassThroughHeaderList: auth-result1,auth-result2 # 鑒權失敗時，透傳鑒權應答的指定頭給用戶端
errorPassThroughBody: true # 鑒權失敗時，將鑒權應答的body透傳給用戶端
ignoreAuthException: true # 如果鑒權發生Exception，比如逾時，串連出錯，忽略鑒權結果，直接存取後端
orAppAuth: true # APP驗證和第三方鑒權只要有一個成功了，就算鑒權成功配置了orAppAuth: true參數後，APP驗證和第三方鑒權只要有一個成功了，就算鑒權成功。
2.6 支援從鑒權服務的應答中提取欄位發給後端服務
從鑒權服務返回的應答中提取欄位發給後端服務，可以用authResultPassThrough來配置發送給後端服務的參數映射。
應答提取支援的參數位置：StatusCode、Header、JsonBody。
後端服務支援的參數位置：Header、Query、Formdata。
---
parameters: # 鑒權結果運算式中使用到的參數定義
statusCode: "StatusCode" # http應答碼
clientId: "BodyJsonField:$.Body" # 鑒權服務返回的jsonbody
authUriType: "HTTP" # 鑒權服務類型：HTTP:公網的鑒權地址，HTTP-VPC:VPC授權地址
authUri: # 鑒權服務定義
address: "http://127.0.0.1:8080" # 鑒權服務地址，包括連接埠號碼
path: "/web" # 鑒權服務路徑
timeout: 7000 # 鑒權服務逾時時間，單位是ms。最大支援10s
method: POST # 鑒權服務HTTP Method
passThroughBody: true # 是否將請求的body透傳給鑒權服務
cachedTimeBySecond: 10 # API Gateway緩衝鑒權結果應答的時間，最長為10分鐘（目前緩衝是將所有apiuid+authparameters作為主鍵去緩衝的）
authResultPassThrough: #發送給後端服務的參數映射
- targetParameterName: x-echo-header-client-id #發送給後端服務的參數名稱
targetLocation: header #發送給後端服務的參數位置
sourceParameterName: clientId #從鑒權服務應答中提取的參數
- targetParameterName: x-echo-header-status-code
targetLocation: query
sourceParameterName: statusCode
successCondition: "${statusCode} = 200" # 判斷鑒權應答的運算式
errorMessage: "auth failed" # 鑒權失敗時，用戶端收到的應答x-ca-errormessage頭的值
errorStatusCode: 401 # 鑒權失敗時，用戶端收到的http status值
errorPassThroughHeaderList: auth-result1,auth-result2 # 鑒權失敗時，透傳鑒權應答的指定頭給用戶端
errorPassThroughBody: true # 鑒權失敗時，將鑒權應答的body透傳給用戶端說明
從鑒權服務的應答中提取的參數，可作為Parameters用於其他外掛程式。樣本如下：
parameters: # 參數列表, 可用於流控的參數
clientId: "Parameter:x-echo-header-client-id" #發送給後端服務的參數名稱2.7 支援緩衝鑒權應答
API Gateway為提高業務處理的平滑度，減少使用者鑒權服務的壓力，支援緩衝鑒權應答，目前緩衝是將apiuid + 所有authparameters 拼接成主鍵，鑒權應答作為緩衝的值進行緩衝的。緩衝鑒權應答的時間最長為10分鐘。
2.8 提供根據參數的值跳過第三方鑒權的能力
重要
2025-05-26 之前購買的專享執行個體，如果不生效需提交工單聯絡我們以便給您升級執行個體版本。
該功能支援基於請求參數的值條件式鑒權路由，允許通過預定義規則動態選擇鑒權策略。適用於部分請求使用第三方鑒權，另一部分使用APP鑒權的情境。
skipRemoteAuthOnRequestParametersCondition這個配置塊負責實現跳過第三方鑒權的功能。當所有參數的值都命中條件的時候就跳過第三方鑒權，其中sourceParameterConditionValues可以是一個值的列表，請求欄位命中其中的一個值就算這個子條件命中了。如果sourceParameterConditionValues值設定為null，那麼這個欄位缺失才算這個子條件命中，如果sourceParameterConditionValues值設定為*，那麼這個欄位為任何值都算這個子條件命中。下面是相關的配置樣本。
parameters:
statusCode: "StatusCode"
userId: "BodyJsonField:$.Headers.tokenUserId"
authUriType: "HTTP"
authUri:
address: "https://auth.com"
path: "/auth"
timeout: 7000
method: POST
passThroughBody: false
cachedTimeBySecond: 1
authParameters:
- targetParameterName: tokenUserId
sourceParameterName: userId
targetLocation: Header
sourceLocation: Query
successCondition: "${userId} = 'admin'"
skipRemoteAuthOnRequestParametersCondition: // 負責實現跳過第三方鑒權的功能,下面所有條件均命中的情況下，跳過第三方鑒權
- sourceParameterName: userId // 請求參數的欄位名
sourceLocation: Query // 請求參數的欄位位置
sourceParameterConditionValues: admin1,admin2 // 參數值列表，如果本請求參數的值在列表內，本子條件就算命中
- sourceParameterName: password // 請求參數的欄位名
sourceLocation: Query // 請求參數的欄位位置
sourceParameterConditionValues: null // 本請求參數缺失就算命中2.9 向第三方鑒權服務發送常量參數的能力
重要
2025-03-22 之前購買的專享執行個體，如果不生效需提交工單聯絡我們以便給您升級執行個體版本。
該功能允許在向第三方鑒權服務發起的請求中注入常量參數，當鑒權參數配置中不設定源參數位置（sourceLocation）與來源參數名（sourceParameterName）而是直接設定targetParameterValue屬性值時，系統會自動將該參數判定為常量參數。
parameters:
userId: "BodyJsonField:$.Headers.tokenUserId"
authUriType: "HTTP"
authUri:
address: "https://auth.com"
path: "/auth"
timeout: 7000
method: POST
passThroughBody: false
cachedTimeBySecond: 1
authParameters:
- targetParameterName: tokenUserId
sourceParameterName: userId
targetLocation: Header
sourceLocation: Query
- targetParameterName: constantParam1 //鑒權常量參數，僅需要設定參數的值，不需要設定來源參數配置
targetParameterValue: "test"
targetLocation: Header
successCondition: "${userId} = 'A101' and ${constantParam} = 'test'"3. 日誌
在投遞給SLS的日誌中，有一個plugin欄位，裡面描述了第三方鑒權的結果，"authSuccess":"0"為鑒權失敗，"authSuccess":"1"為鑒權成功。
plugin:[{"context":{"authSuccess":"0"},"pluginName":"remoteAuth"}]