本頁面由 Cloud Translation API 翻譯而成。

BasicAuthentication 政策
透過集合功能整理內容你可以依據偏好儲存及分類內容。

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

結果

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

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

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

影片：這部影片示範如何使用基本驗證政策，將使用者名稱和密碼以 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 屬性指定的變數衍生而來。必須先設定變數，政策才能執行。通常，變數會填入從鍵/值對應讀取的值。請參閱「鍵值對應作業」政策。

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

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

預設

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

不適用

如果省略這個元素，系統會使用政策的 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	選用

說明

預設

存在必要性

createNew

決定在變數已設定的情況下，政策是否應覆寫該變數。

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

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

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

false

選用

<Source> 元素

解碼時，變數會包含 Base64 編碼字串，格式為 Basic Base64EncodedString。例如，指定 request.header.Authorization，對應至「Authorization」標頭。

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

預設值：	不適用
外觀狀態：	解碼作業需要此屬性。
類型：	不適用

流程變數

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

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

錯誤參考資料

本節說明這項政策觸發錯誤時，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>

BasicAuthentication 政策
透過集合功能整理內容你可以依據偏好儲存及分類內容。

結果

範例

出站編碼

傳入解碼

關於基本驗證政策

元素參照

<BasicAuthentication> 屬性

<DisplayName> 元素

<Operation> 元素

<IgnoreUnresolvedVariables> 元素

<User> 元素

屬性

<Password> 元素

屬性

<AssignTo> 元素

屬性

<Source> 元素

流程變數

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

結構定義

相關主題

BasicAuthentication 政策 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

結果

範例

出站編碼

傳入解碼

關於基本驗證政策

元素參照

<BasicAuthentication> 屬性

<DisplayName> 元素

<Operation> 元素

<IgnoreUnresolvedVariables> 元素

<User> 元素

屬性

<Password> 元素

屬性

<AssignTo> 元素

屬性

<Source> 元素

流程變數

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

結構定義

相關主題

BasicAuthentication 政策
透過集合功能整理內容你可以依據偏好儲存及分類內容。