基本身份验证政策

本页面适用于 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 属性指定的变量。必须在执行此政策之前设置变量。通常，变量由从键/值映射读取的值填充。请参阅键值对映射操作政策。

此配置将会导致名为 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 编码的字符串中解码用户名和密码

用户名和密码通常存储在键/值存储中，然后在运行时从键/值存储中读取。如需详细了解如何使用键/值存储，请参阅键值对映射操作政策。

元素参考

元素参考描述了基本身份验证政策的元素和属性

<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	可选
类型	字符串

不适用

如果省略此元素，则会使用政策的 name 属性的值。

Presence 可选

类型字符串

<Operation> 元素

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

<Operation>Encode</Operation>

默认：

不适用

状态：

必需

类型：

String。

有效值包括：

编码
解码

<IgnoreUnresolvedVariables> 元素

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

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

默认：	true
状态：	可选
类型：	布尔值

<User> 元素

对于编码，请使用 <User> 元素指定包含用户名的变量。使用 Base64 编码前，用户名和密码会用冒号串联。
对于解码，请指定写入已解码的用户名的变量。

<User ref="request.queryparam.username" />

默认：	不适用
状态：	必需
类型：	不适用

属性

属性	说明	默认	Presence
ref	政策从中动态读取用户名（编码）或写入用户名（解码）的变量。	不适用	必需

<Password> 元素

对于编码，请使用 <Password> 元素指定包含密码的变量。
对于解码，请指定写入已解码的密码的变量。

<Password ref="request.queryparam.password" />

默认：	不适用
状态：	必需
类型：	不适用

属性

属性	说明	默认	Presence
ref	政策从中动态读取密码（编码）或写入密码（解码）的变量。	不适用	必需

<AssignTo> 元素

指定使用此政策生成的编码或解码值设置的目标变量。

以下示例表明政策应将消息的 Authorization 标头设置为生成的值：

<AssignTo createNew="false">request.header.Authorization</AssignTo>

默认：	不适用
状态：	必需
类型：	字符串

属性

属性	说明	默认	Presence
createNew	确定如果变量已经设置，政策是否应该覆盖该变量。如果为“false”，只有在当前未设置变量 (null) 时才会发生对变量的分配。如果为“true”，则始终会对变量进行分配。通常，应将此属性设置为“false”（默认）。	false	可选

说明

默认

Presence

createNew

确定如果变量已经设置，政策是否应该覆盖该变量。

如果为“false”，只有在当前未设置变量 (null) 时才会发生对变量的分配。

如果为“true”，则始终会对变量进行分配。

通常，应将此属性设置为“false”（默认）。

false

可选

<Source> 元素

对于解码，包含 Base64 编码字符串的变量，其格式为 Basic Base64EncodedString。例如，指定 request.header.Authorization 对应于 Authorization 标头。

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

默认：	不适用
状态：	对于解码操作是必需的。
类型：	不适用

流变量

系统会在政策失败时设置以下流变量：

BasicAuthentication.{policy_name}.failed（值为 true）

错误参考信息

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>