基本身份验证政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

是什么

允许您使用轻量级基本身份验证实现最后一公里安全性。该政策接受用户名和密码，Base64 对其进行编码，并将结果值写入变量。结果值的形式为 Basic Base64EncodedString。通常，会将此值写入 HTTP 标头，例如 Authorization 标头。

该政策还允许您将存储在 Base64 编码的字符串中的凭据解码为用户名和密码。

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

注意：此政策不会对向 API 代理发出的请求强制执行基本身份验证。相反，您会将其用于 Base64 编码/解码凭据，通常是连接到后端服务器或使用服务调出政策时（例如需要进行基本身份验证的 Service Callout 政策）。

注意：以下视频显示了 Apigee 界面中的经典版代理编辑器。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 属性指定的变量。必须在执行此政策之前设置变量。通常，变量由从键/值映射读取的值填充。请参阅键值对映射操作政策。

此配置将会导致名为 Authorization 的 HTTP 标头（由 <AssignTo> 元素指定）添加到发送到后端服务器的出站请求消息中：

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

在 Base64 编码之前，<User> 和 <Password> 值使用冒号进行串联。

假设您的键/值映射具有以下条目：

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

下表介绍了所有政策父元素通用的特性：

属性	说明	默认	Presence
name	政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。 （可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。	不适用	必需
continueOnError	设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。 设置为 true，即使在政策失败后，仍可以继续执行流。另请参阅： 故障规则仅在错误状态下触发（关于 continueOnError） 处理当前流中的故障	false	可选
enabled	设置为 true 可强制执行政策。 设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。	true	可选
async	此特性已弃用。	false	已弃用

<DisplayName> 元素

用于在 name 属性之外在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>

默认	不适用 如果省略此元素，则会使用政策的 name 属性的值。
Presence	可选
类型	字符串

<Operation> 元素

确定政策是否对凭据进行 Base64 编码或解码。

<Operation>Encode</Operation>

默认：	不适用
状态：	需要
类型：	String。 有效值包括： 编码 解码

<IgnoreUnresolvedVariables> 元素

设置为 true 时，如果无法解析变量，则政策不会抛出错误。在 BasicAuthentication 政策的上下文中使用时，此设置通常设为 false，因为如果在指定变量中找不到用户名或密码，其通常会抛出错误，这是有利的。

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

默认：	true
状态：	可选
类型：	Boolean

<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”，只有在当前未设置变量 (null) 时才会发生对变量的分配。 如果为“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 设置的故障变量。在开发故障规则以处理错误时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码	HTTP 状态	原因	修复
steps.basicauthentication.InvalidBasicAuthenticationSource	500	如果采用 Base64 编码的传入字符串不包含有效值或标头格式不正确（例如，不以 Basic 开头），系统会进行解码。
steps.basicauthentication.UnresolvedVariable	500	解码或编码所需的源变量不存在。仅当 IgnoreUnresolvedVariables 为 false 时才会发生此错误。

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

错误名称	发生的条件	修复
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 代码库示例，了解最新架构。

相关主题

键值对映射操作政策