全部產品
Search

搜尋本產品

    API Gateway：第三方鑒權外掛程式

    文件中心

    API Gateway：第三方鑒權外掛程式

    更新時間：Jul 16, 2024

    您可以通過本外掛程式配置自己的鑒權服務為API的訪問進行鑒權。

    1. 概述

    API Gateway在調用API後端服務之前將先調用使用者的鑒權服務，收到鑒權服務的鑒權成功應答後才會繼續調用後端服務，否則給用戶端返回鑒權失敗的應答。第三方鑒權外掛程式支援的功能如下：

    • 允許使用者自訂發送給鑒權服務的請求參數；

    • 允許使用者將鑒權應答結果在API Gateway緩衝一定時間，保持業務的平滑度；

    • 允許使用者自訂鑒權失敗的應答；

    image

    2. 外掛程式配置

    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            # 鑒權失敗時，將鑒權應答的ody透傳給用戶端
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            # 鑒權失敗時，將鑒權應答的ody透傳給用戶端
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               # 鑒權失敗時，將鑒權應答的ody透傳給用戶端
    重要

    2023-05-09號之前購買的專享執行個體，如果不生效需提交工單聯絡我們給您升級執行個體版本。

    3. 日誌

    在投遞給sls的日誌中，有一個plugin欄位，裡面描述了第三方鑒權的結果，"authSuccess":"0"為鑒權失敗，"authSuccess":"1"為鑒權成功

    plugin:[{"context":{"authSuccess":"0"},"pluginName":"remoteAuth"}]