BasicAuthentication 政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

結果

您可以使用輕量型基本驗證，確保最後一哩路的安全。這項政策會採用使用者名稱和密碼，以 Base64 編碼，然後將產生的值寫入變數。結果值的格式為 Basic Base64EncodedString。您通常會將這個值寫入 HTTP 標頭，例如 Authorization 標頭。

這項政策也能將以 Base64 編碼字串儲存的憑證解碼為使用者名稱和密碼。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

注意：這項政策不會對 API Proxy 的要求強制執行基本驗證。而是用於 Base64 編碼/解碼憑證，通常是在連線至後端伺服器或使用服務呼叫政策 (例如服務呼叫政策) 時，需要基本驗證。

注意：以下影片顯示 Apigee UI 中的傳統 Proxy 編輯器。Apigee 推出新版 Proxy 編輯器，設計與影片中顯示的傳統版不同。

影片：這部影片示範如何使用基本驗證政策，以 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 編碼的字串解碼使用者名稱和密碼

使用者名稱和密碼通常會儲存在鍵/值儲存庫中，然後在執行階段從鍵/值儲存庫讀取。如要瞭解如何使用鍵/值儲存空間，請參閱「鍵/值對應作業政策」。

警告：基本驗證不會提供機密性。 一律透過啟用 TLS 的 (HTTPS) 連線，將憑證傳送至後端服務。

元素參考資料

元素參考資料說明 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> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。	不適用	必填
continueOnError	將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。 將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱： 錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤	false	選用
enabled	設為 true 即可強制執行政策。 設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。	是	選用
async	此屬性已淘汰。	false	已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>

預設	不適用 如果省略這個元素，系統會使用政策的 name 屬性值。
存在必要性	選用
類型	字串

<Operation> 元素

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

<Operation>Encode</Operation>

預設值：	不適用
外觀狀態：	必填
類型：	字串。 有效值包括： 編碼 Decode

<IgnoreUnresolvedVariables> 元素

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

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

預設值：	是
外觀狀態：	選用
類型：	布林值

<User> 元素

• 如要進行編碼，請使用 <User> 元素指定含有使用者名稱的變數。使用者名稱和密碼值會先以半形冒號串連，再進行 Base64 編碼。
• 如要解碼，請指定要寫入解碼後使用者名稱的變數。

<User ref="request.queryparam.username" /> 

預設值：	不適用
外觀狀態：	必填
類型：	不適用

屬性

屬性	說明	預設	存在必要性
ref	政策會從這個變數動態讀取使用者名稱 (編碼) 或寫入使用者名稱 (解碼)。	不適用	必填

<Password> 元素

• 如要進行編碼，請使用 <Password> 元素指定含有密碼的變數。
• 如要解碼，請指定要寫入解碼後密碼的變數。

<Password ref="request.queryparam.password" />

預設值：	不適用
外觀狀態：	必填
類型：	不適用

屬性

屬性	說明	預設	存在必要性
ref	政策會從這個變數動態讀取密碼 (編碼) 或寫入密碼 (解碼)。	不適用	必填

<AssignTo> 元素

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

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

<AssignTo createNew="false">request.header.Authorization</AssignTo>

預設值：	不適用
外觀狀態：	必填
類型：	字串

屬性

屬性	說明	預設	存在必要性
createNew	決定政策是否應覆寫變數 (如果變數已設定)。 如果為「false」，則只有在變數目前未設定 (空值) 時，才會指派給變數。 如果為「true」，系統一律會將值指派給變數。 您通常會將這個屬性設為「false」(預設值)。	false	選用

<Source> 元素

如要解碼，請使用包含 Base64 編碼字串的變數，格式為 Basic Base64EncodedString。舉例來說，指定 request.header.Authorization，對應至「Authorization」標頭。

<Source>request.header.Authorization</Source>

預設值：	不適用
外觀狀態：	解碼作業需要這項資訊。
類型：	不適用

流程變數

政策失敗時，系統會設定下列流程變數：

• BasicAuthentication.{policy_name}.failed (值為 true)

注意：如果看到名為 BasicAuthentication.{policy_name}.fault.cause 和 BasicAuthentication.{policy_name}.fault.name 的變數，表示 Apigee 目前未使用這些變數。

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理錯誤的錯誤規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

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

錯誤代碼	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

錯誤回應範例

注意：如要處理錯誤，最佳做法是擷取錯誤回應的 errorcode 部分。請勿依賴 faultstring 中的文字，因為該文字可能會變更。

{  
   "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>

結構定義

範例：如要查看最新結構定義，請參閱 GitHub 存放區範例。

相關主題

Key Value Map Operations policy