BasicAuthentication 政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

優勢

可讓您使用輕量級基本驗證,獲得最後一里的安全性。這項政策採用使用者名稱和密碼,Base64 進行編碼,然後將產生的值寫入變數。產生的值格式為 Basic Base64EncodedString。您通常會將這個值寫入 HTTP 標頭,例如 Authorization 標頭。

此外,這項政策還可讓您將儲存在 Base64 編碼字串中的憑證解碼為使用者名稱和密碼。

影片:這部影片示範如何使用基本驗證政策,對使用者名稱和密碼進行 base64 編碼。

影片:這部影片說明如何使用基本驗證政策,將採用 Base64 編碼的使用者名稱和密碼解碼。

範例

傳出編碼

<BasicAuthentication name="ApplyBasicAuthHeader">
   <DisplayName>ApplyBasicAuthHeader</DisplayName>
   <Operation>Encode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="BasicAuth.credentials.username" />
   <Password ref="BasicAuth.credentials.password" />
   <AssignTo createNew="false">request.header.Authorization</AssignTo>
</BasicAuthentication>

在上述政策設定範例中,要編碼的使用者名稱與密碼衍生自 <User><Password> 元素上 ref 屬性指定的變數。必須先設定變數,才能執行這項政策。一般來說,變數會填入從鍵/值對應讀取的值。請參閱鍵/值對應作業政策

這項設定會產生名為 Authorization 的 HTTP 標頭 (依 <AssignTo> 元素所指定),並且會新增至傳送至後端伺服器的傳出要求訊息:

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

<User><Password> 值會以半形冒號串連在 Base64 編碼之前。

假設您的鍵/值對應包含下列項目:

{
  "encrypted" : true,
  "entry" : [ {
    "name" : "username",
    "value" : "MyUsername"
  }, {
    "name" : "password",
    "value" : "MyPassword"
  } ],
  "name" : "BasicAuthCredentials"
}
      

請在 BasicAuthentication 政策之前附加下列 KeyValueMapOperations 政策,以便從鍵/值儲存庫擷取 <User><Password> 元素的值,並填入 credentials.usernamecredentials.password 變數。

<KeyValueMapOperations name="getCredentials" mapIdentifier="BasicAuthCredentials">
  <Scope>apiproxy</Scope>
  <Get assignTo="credentials.username" index='1'>
    <Key>
      <Parameter>username</Parameter>
    </Key>
  </Get>
  <Get assignTo="credentials.password" index='1'>
    <Key>
      <Parameter>password</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>
      

內送解碼

<BasicAuthentication name="DecodeBaseAuthHeaders">
   <DisplayName>Decode Basic Authentication Header</DisplayName>
   <Operation>Decode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="request.header.username" />
   <Password ref="request.header.password" />
   <Source>request.header.Authorization</Source>
</BasicAuthentication>

在這項政策範例中,政策會依照 <Source> 元素指定的內容,將 Authorization HTTP 標頭中的使用者名稱和密碼解碼。Base64 編碼的字串必須採用 Basic Base64EncodedString. 格式

政策會將解碼的使用者名稱寫入 request.header.username 變數,並將解碼密碼寫入 request.header.password 變數。


關於基本驗證政策

這項政策提供兩種作業模式:

  • 編碼:Base64 會將儲存在變數中的使用者名稱和密碼進行編碼
  • 解碼:從 Base64 編碼字串中解碼使用者名稱和密碼

使用者名稱和密碼通常會儲存鍵/值儲存庫,然後在執行階段從鍵/值存放區讀取資料。如要進一步瞭解如何使用鍵/值存放區,請參閱鍵/值對應作業政策

元素參照

元素參考資料說明基本驗證政策的元素和屬性。

<BasicAuthentication async="false" continueOnError="false" enabled="true" name="Basic-Authentication-1">
   <DisplayName>Basic Authentication 1</DisplayName>
   <Operation>Encode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="request.queryparam.username" />
   <Password ref="request.queryparam.password" />
   <AssignTo createNew="false">request.header.Authorization</AssignTo>
   <Source>request.header.Authorization</Source> 
</BasicAuthentication>

<BasicAuthentication> 屬性

<BasicAuthentication async="false" continueOnError="false" enabled="true" name="Basic-Authentication-1">

下表說明所有政策父項元素的通用屬性:

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和半形句號。這個值不得超過 255 個半形字元。

您也可以選擇使用 <DisplayName> 元素,在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 需要
continueOnError

如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
enabled

如要強制執行政策,請設為 true

設為 false 即可停用這項政策。即使政策仍附加在流程中,系統也不會強制執行政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

<DisplayName> 元素

除了 name 屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素,系統會使用政策的 name 屬性值。

存在必要性 選用
類型 字串

<Operation> 元素

決定政策 Base64 要對憑證進行編碼或解碼。

<Operation>Encode</Operation>
預設: 不適用
所在地: 需要
類型:

字串。

有效值包括:

  • 編碼
  • Decode

<IgnoreUnresolvedVariables> 元素

設為 true 時,如果變數無法解析,政策不會擲回錯誤。在基本驗證政策中使用時,系統通常會設為 false,因為如果在指定的變數中找不到使用者名稱或密碼,這項設定通常有利於擲回錯誤。

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
預設: true
所在地: 選用
類型:

布林值

<User> 元素

  • 如要編碼,請使用 <User> 元素指定包含使用者名稱的變數。使用者名稱和密碼值會與 Base64 編碼之前的冒號串連。
  • 如要進行解碼,請指定已解碼使用者名稱的變數。
<User ref="request.queryparam.username" /> 
預設: 不適用
所在地: 需要
類型:

不適用

屬性

屬性 說明 預設 存在必要性
參考資料

政策中的變數會動態讀取使用者名稱 (編碼) 或寫入使用者名稱 (解碼)。

不適用 需要

<Password> 元素

  • 如要編碼,請使用 <Password> 元素指定包含密碼的變數。
  • 如要進行解碼,請指定寫入已解碼密碼的變數。
<Password ref="request.queryparam.password" />
預設: 不適用
所在地: 需要
類型:

不適用

屬性

屬性 說明 預設 存在必要性
參考資料

政策用於動態讀取密碼 (編碼) 或寫入密碼 (解碼) 的變數。

不適用 需要

<AssignTo> 元素

指定要使用這項政策產生的編碼或解碼值設定的目標變數。

以下範例表示政策應將訊息的 Authorization 標頭設為產生的值:

<AssignTo createNew="false">request.header.Authorization</AssignTo>
預設: 不適用
所在地: 需要
類型:

字串

屬性

屬性 說明 預設 存在必要性
createNew 決定如果已設定變數,政策是否應覆寫變數。

設為「false」時,「只有」在目前未設定變數 (空值) 時,才會進行變數的指派作業。

若為「true」,系統會一律進行變數的指派作業。

通常會將這個屬性設為「false」(預設值)。

false 選用

<Source> 元素

對於解碼,包含 Base64 編碼字串的變數,格式為 Basic Base64EncodedString。例如,指定與 Authorization 標頭相對應的 request.header.Authorization

<Source>request.header.Authorization</Source>
預設: 不適用
所在地: 這是解碼作業的必要項目。
類型:

不適用

流程變數

當政策失敗時,系統會設定下列流程變數:

  • BasicAuthentication.{policy_name}.failed (具有 true 的值)

錯誤參考資料

本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。如果您開發的錯誤規則來處理錯誤,請務必瞭解這些資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

執行政策時,可能會發生這些錯誤。

錯誤代碼 HTTP 狀態 原因 修正
steps.basicauthentication.InvalidBasicAuthenticationSource 500 當傳入的 Base64 編碼字串不含有效值,或是標頭格式錯誤 (例如不是以「Basic」開頭) 時,您進行的解碼。
steps.basicauthentication.UnresolvedVariable 500 解碼或編碼所需的來源變數不存在。只有在 IgnoreUnresolvedVariables 為 false 時,才會發生這個錯誤。

部署錯誤

若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。

錯誤名稱 發生時機 修正
UserNameRequired 已命名作業必須有 <User> 元素。
PasswordRequired 已命名作業必須有 <Password> 元素。
AssignToRequired 已命名作業必須有 <AssignTo> 元素。
SourceRequired 已命名作業必須有 <Source> 元素。

錯誤變數

這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。

Variables 地點 範例
fault.name="fault_name" fault_name 是錯誤的名稱,如上方的「執行階段錯誤」表格所示。錯誤名稱是錯誤碼的最後一個部分。 fault.name Matches "UnresolvedVariable"
BasicAuthentication.policy_name.failed policy_name 是擲回錯誤的政策使用者指定的名稱。 BasicAuthentication.BA-Authenticate.failed = true

錯誤回應範例

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.basicauthentication.UnresolvedVariable"
      },
      "faultstring":"Unresolved variable : request.queryparam.password"
   }
}

故障規則示例

<FaultRule name="Basic Authentication Faults">
    <Step>
        <Name>AM-UnresolvedVariable</Name>
        <Condition>(fault.name Matches "UnresolvedVariable") </Condition>
    </Step>
    <Step>
        <Name>AM-AuthFailedResponse</Name>
        <Condition>(fault.name = "InvalidBasicAuthenticationSource")</Condition>
    </Step>
    <Condition>(BasicAuthentication.BA-Authentication.failed = true) </Condition>
</FaultRule>

結構定義

相關主題

鍵/值對應作業政策