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 目前未使用這些變數。

錯誤參考資料

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle errors. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause	Fix
steps.basicauthentication.InvalidBasicAuthenticationSource	500	On a decode when the incoming Base64 encoded string does not contain a valid value or the header is malformed (for example, does not start with Basic).
steps.basicauthentication.UnresolvedVariable	500	The required source variables for the decode or encode are not present. This error can only occur if IgnoreUnresolvedVariables is false.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Occurs when	Fix
UserNameRequired	The <User> element must be present for the named operation.
PasswordRequired	The <Password> element must be present for the named operation.
AssignToRequired	The <AssignTo> element must be present for the named operation.
SourceRequired	The <Source> element must be present for the named operation.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "UnresolvedVariable"
BasicAuthentication.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	BasicAuthentication.BA-Authenticate.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

Example fault rule

<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