BasicAuthentication 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

您可以使用輕量型基本驗證，確保最後一哩路的安全。這項政策會採用使用者名稱和密碼，以 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.username 和 credentials.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 政策的元素和屬性。

<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> 元素，為政策加上標籤： 管理使用者介面 Proxy 編輯器，使用不同的自然語言名稱。

 不適用 必填
continueOnError

如果設為「false」，系統會在政策失敗時傳回錯誤。這是可預期的情況 大多數政策的行為

如果設為 true，即使政策已發生，流程執行作業仍會繼續執行 失敗。

 false 選用
enabled

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

設為 false 即可停用政策。這項政策不會 仍會強制執行 政策。

 true 選用
async

此屬性已淘汰。

 false 已淘汰

&lt;DisplayName&gt;元素

除 name 屬性外，一併使用 管理 UI Proxy 編輯器，使用不同的自然語言名稱。

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

不適用

如果省略這個元素，政策的 name 屬性值會是

存在必要性 選用
類型 字串

<Operation> 元素

決定政策是否要以 Base64 編碼或解碼憑證。

<Operation>Encode</Operation>
預設值： 不適用
外觀狀態： 必填
類型：

字串。

有效值包括：

  • 編碼
  • Decode

<IgnoreUnresolvedVariables> 元素

如果設為 true，當變數無法解析時，政策不會擲回錯誤。在 BasicAuthentication 政策的環境中使用時，這項設定通常會設為 false，因為如果找不到指定變數中的使用者名稱或密碼，一般來說擲回錯誤會比較好。

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
預設值： true
外觀狀態： 選用
類型：

布林值

<User> 元素

  • 如要進行編碼，請使用 <User> 元素指定含有使用者名稱的變數。使用者名稱和密碼值會先以半形冒號串連，再進行 Base64 編碼。
  • 如要解碼，請指定要寫入解碼後使用者名稱的變數。
<User ref="request.queryparam.username" />
預設值： 不適用
外觀狀態： 必填
類型：

不適用

屬性

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

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

 不適用 必填

<Password> 元素

  • 如要進行編碼，請使用 <Password> 元素指定含有密碼的變數。
  • 如要解碼，請指定要寫入解碼後密碼的變數。
<Password ref="request.queryparam.password" />
預設值： 不適用
外觀狀態： 必填
類型：

不適用

屬性

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

政策會從這個變數動態讀取密碼 (編碼) 或寫入密碼 (解碼)。

 不適用 必填

<AssignTo> 元素

針對 Encode 作業，指定要使用這項政策產生的編碼值設定的目標變數。

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

<AssignTo createNew="false">request.header.Authorization</AssignTo>
預設值： 不適用
外觀狀態： Encode作業的必要條件。
類型：

字串

屬性

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

如果為「false」，則只有在變數目前未設定 (空值) 時，才會指派給變數。

如果為「true」，系統一律會將值指派給變數。

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

 false 選用

<Source> 元素

如要解碼，請使用包含 Base64 編碼字串的變數，格式為 Basic Base64EncodedString。舉例來說，指定 request.header.Authorization，對應至「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> 元素。

錯誤變數

系統會在發生執行階段錯誤時設定這些變數。詳情請參閱重要須知 政策錯誤。

變數 地點 範例
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>

結構定義

相關主題

鍵值對應表 營運政策