基本身份验证政策

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

内容

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

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

视频：此视频演示如何使用基本身份验证政策对用户名和密码进行 base64 编码。

视频：此视频演示如何使用基本身份验证政策解码 base64 编码的用户名和密码。

示例

出站编码

<BasicAuthentication name="ApplyBasicAuthHe>ader<"
   D>isplayNameApplyBasic<AuthHeader/D>ispl<ayName
  > Opera<tionEncode>/Ope<ration
   IgnoreUnresolve>dVari<ablesfalse/IgnoreUnresolve>dVar<iables
   User ref="credenti>als.<username" /
   Password ref=&quo>t;cr<edentials.password" />
   AssignTo createNew="<;false&qu>o<t;request.header.Aut>horization/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="BasicA>uth<Crede>ntials&q<uot;
 > Sc<opeapiproxy/Scope
  Get assignTo="creden>tials<.us>ername&<quot; ind>ex='<1'
   > Key
<    >  P<aram>ete<rusername/Parameter
    /Key
  /Get
  Get ass>ignTo<=&q>uot;cre<dentials.>password<" ind>ex=&#<39;1><9;
 > <  Key
      Parameterp>assword/Parameter
    /Key
  /Get
/KeyValueMapOperations

入站解码

<BasicAuthentication name="DecodeBaseAuthHea>ders<"
   D>isplayNameDecode Basic Authenticat<ion Header/D>ispl<ayName
  > Opera<tionDecode>/Ope<ration
   IgnoreUnresolve>dVari<ablesfalse/IgnoreUnresolve>dVar<iables
   User ref="request.hea>der.<username" /
   Password ref="r>eque<st.hea>der.password" /
   Sour<cereque>s<t.header.Authorizati>on/Source
/BasicAuthentication

在此政策示例中，该政策按照 <Source> 元素的指定对来自 Authorization HTTP 标头的用户名和密码进行解码。Base64 编码的字符串必须采用 Basic Base64EncodedString. 格式

该政策将已解码的用户名写入 request.header.username 变量，并将已解码的密码写入 request.header.password 变量。

关于基本身份验证政策

该政策具有两种操作模式：

  • 编码：Base64 对存储在变量中的用户名和密码进行编码
  • 解码：从 Base64 编码的字符串中解码用户名和密码

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

元素参考

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

<BasicAuthentication async="false" continueOnError="false" enabled="true"> nam<e="Bas>ic-Authentication-1&qu<ot;
   Displ>ayNa<meBasic A>uthent<ication 1/>Disp<layName
   OperationEncod>e/Ope<ration
   IgnoreUnresolved>Vari<ablesfalse/IgnoreUnresolvedVariab>les
<   User ref="credentials.usernam>e&qu<ot; /
   Password ref=&quo>t;credentials.password"< /
   Ass>ignT<o crea>teNew="false"reque<st.head>er<.Authorization/Assig>nTo
   Sourcerequest.header.Authorization/Source 
/BasicAuthentication

<BasicAuthentication> 属性

<BasicAuthentication async="false" continueOnError="false" enabled="true"> name="Basic-Authentication-1"

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

属性 说明 默认 状态
name

政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。

（可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

 不适用 必填
continueOnError

设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。

设置为 true，即使在政策失败后，仍可以继续执行流。

 false 可选
enabled

设置为 true 可强制执行政策。

设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。

 是 可选
async

此特性已弃用。

 false 已弃用

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>
默认

不适用

如果省略此元素，则会使用政策的 name 属性的值。
状态 可选
类型 字符串

<Operation> 元素

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

<Operation>Encode</Operation>
默认： 不适用
状态： 需要
类型：

String。

有效值包括：

  • 编码
  • 解码

<IgnoreUnresolvedVariables> 元素

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

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
默认： true
状态： 可选
类型：

布尔值

<User> 元素

  • 对于编码，请使用 <User> 元素指定包含用户名的变量。使用 Base64 编码前，用户名和密码会用冒号串联。
  • 对于解码，请指定写入已解码的用户名的变量。
<User ref="credentials.userna>me" /
默认： 不适用
状态： 需要
类型：

不适用

属性

属性 说明 默认值 状态
ref

政策从中动态读取用户名（编码）或写入用户名（解码）的变量。

 不适用 需要

<Password> 元素

  • 对于编码，请使用 <Password> 元素指定包含密码的变量。
  • 对于解码，请指定写入已解码的密码的变量。
<Password ref="credentials.passwo>rd" /
默认： 不适用
状态： 需要
类型：

不适用

属性

属性 说明 默认值 状态
ref

政策从中动态读取密码（编码）或写入密码（解码）的变量。

 不适用 需要

<AssignTo> 元素

对于 Encode 操作，指定使用此政策生成的编码值设置的目标变量。

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

<AssignTo createNew="f>alse"request.header.Aut<horizatio>n/AssignTo
默认： 不适用
状态： 对于 Encode 操作是必需的。
类型：

字符串

属性

属性 说明 默认值 状态
新建 确定如果变量已经设置，政策是否应该覆盖该变量。

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

如果为“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 时才会发生此错误。

部署错误

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

错误名称 发生的条件 修复
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

错误响应示例

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

架构

相关主题

键值对映射操作政策