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

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>

在上述政策設定範例中，要編碼的使用者名稱和密碼衍生自ref 屬性上 <User> 和 <Password> 元素。變數必須是。一般而言，變數會填入從鍵/值對應中讀取資料請參閱鍵/值對應作業政策：

這樣就會產生名為 Authorization 的 HTTP 標頭，如 <AssignTo> 元素中將新增至傳送至後端伺服器的傳出要求訊息：

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

<User> 和 <Password> 值會串連開頭加上冒號和 Base64 編碼

請考慮您的鍵/值對應具有下列項目：

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

在基本驗證政策之前附加下列 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>

在此政策範例中，這項政策會將使用者的 Authorization HTTP 標頭，如 <Source> 元素所指定。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	已淘汰

<DisplayName>元素

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

<DisplayName>Policy Display Name</DisplayName>

預設

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

不適用

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

說明

預設

存在必要性

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`

錯誤回應範例

注意：如要處理錯誤，最佳做法是將錯誤回應的 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 政策

結果

範例

傳出編碼

傳入解碼

關於「基本驗證」政策

元素參照

&lt;BasicAuthentication&gt;屬性

&lt;DisplayName&gt;元素

&lt;Operation&gt;元素

&lt;IgnoreUnresolvedVariables&gt;元素

&lt;User&gt;元素

屬性

&lt;Password&gt;元素

屬性

&lt;AssignTo&gt;元素

屬性

&lt;Source&gt;元素

流程變數

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

結構定義

相關主題

<BasicAuthentication>屬性

<DisplayName>元素

<Operation>元素

<IgnoreUnresolvedVariables>元素

<User>元素

<Password>元素

<AssignTo>元素

<Source>元素