您正在查看 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>
在上述政策設定範例中,要編碼的使用者名稱與密碼衍生自 <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 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 |
政策的內部名稱。 您也可以選擇使用 |
不適用 | 需要 |
continueOnError |
如果設為 設為 |
false | 選用 |
enabled |
如要強制執行政策,請設為 設為 |
true | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<DisplayName> 元素
除了 name
屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。
<DisplayName>Policy Display Name</DisplayName>
預設 |
不適用 如果省略這個元素,系統會使用政策的 |
---|---|
存在必要性 | 選用 |
類型 | 字串 |
<Operation> 元素
決定政策 Base64 要對憑證進行編碼或解碼。
<Operation>Encode</Operation>
預設: | 不適用 |
所在地: | 需要 |
類型: |
字串。 有效值包括:
|
<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 | 選用 |
<Source> 元素
對於解碼,包含 Base64 編碼字串的變數,格式為 Basic
Base64EncodedString
。例如,指定與 Authorization 標頭相對應的 request.header.Authorization
。
<Source>request.header.Authorization</Source>
預設: | 不適用 |
所在地: | 這是解碼作業的必要項目。 |
類型: |
不適用 |
流程變數
當政策失敗時,系統會設定下列流程變數:
BasicAuthentication.{policy_name}.failed
(具有 true 的值)
錯誤參考資料
本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。如果您開發的錯誤規則來處理錯誤,請務必瞭解這些資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。
執行階段錯誤
執行政策時,可能會發生這些錯誤。
錯誤代碼 | HTTP 狀態 | 原因 | 修正 |
---|---|---|---|
steps.basicauthentication.InvalidBasicAuthenticationSource |
500 | 當傳入的 Base64 編碼字串不含有效值,或是標頭格式錯誤 (例如不是以「Basic」開頭) 時,您進行的解碼。 | build |
steps.basicauthentication.UnresolvedVariable |
500 | 解碼或編碼所需的來源變數不存在。只有在 IgnoreUnresolvedVariables 為 false 時,才會發生這個錯誤。 |
build |
部署錯誤
若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。
錯誤名稱 | 發生時機 | 修正 |
---|---|---|
UserNameRequired |
已命名作業必須有 <User> 元素。 |
build |
PasswordRequired |
已命名作業必須有 <Password> 元素。 |
build |
AssignToRequired |
已命名作業必須有 <AssignTo> 元素。 |
build |
SourceRequired |
已命名作業必須有 <Source> 元素。 |
build |
錯誤變數
這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。
錯誤回應範例
{ "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>