BasicAuthentication ポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントを表示する。

BasicAuthentication ポリシーでは、ラストワンマイルセキュリティに軽量の基本認証を使用できます。このポリシーは、ユーザー名とパスワードを取得し、Base64 でエンコードして、生成された値を変数に書き込みます。生成された値の形式は Basic Base64EncodedString です。この値は一般に、HTTP ヘッダー（Authorization ヘッダーなど）に書き込みます。

このポリシーには次の 2 つの操作モードがあります。

エンコード: 変数に格納されるユーザー名とパスワードを Base64 でエンコードします。
デコード: Base64 でエンコードされた文字列からユーザー名とパスワードをデコードします。

通常、ユーザー名とパスワードは Key-Value ストアに格納され、実行時に Key-Value ストアから読み取られます。Key-Value ストアの使用について詳しくは、KeyValueMapOperations ポリシーをご覧ください。

このポリシーによって、API プロキシへのリクエストに基本認証が強制適用されることはありません。このポリシーは通常、バックエンドサーバーへの接続時や、ServiceCallout ポリシーなど、基本認証を必要とするサービスコールアウトポリシーの使用時に、認証情報を Base64 でエンコード / デコードするために使用します。

このポリシーは拡張可能なポリシーであり、Apigee ライセンスによっては、このポリシーの使用が、費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

サンプル

アウトバウンドエンコード

<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 属性で指定された変数から取得されます。これらの変数はポリシーの実行前に設定されている必要があります。一般に、変数には Key-Value マップから読み取られた値が代入されます。Key Value Map Operations ポリシーをご覧ください。

この構成では、Authorization という名前の HTTP ヘッダーが <AssignTo> 要素で指定され、バックエンドサーバーに送信される送信リクエストメッセージに追加されます。

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

<User> と <Password> の値は、コロンで連結されてから Base64 でエンコードされます。

次のエントリを持つ Key-Value マップがあるとします。

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

BasicAuthentication ポリシーの前に次の KeyValueMapOperations ポリシーを配置して、Key-Value ストアから <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 変数にそれぞれ書き込まれます。

要素リファレンス

この要素リファレンスは、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 文字を超えることはできません。管理 UI プロキシエディタで `<DisplayName>` 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。	なし	必須
`continueOnError`	ポリシーが失敗したときにエラーを返す場合は、`false` に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、`true` に設定します。関連項目: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について）現在のフローにおける障害処理	false	省略可
`enabled`	ポリシーを適用するには、`true` に設定します。ポリシーを無効にするには、`false` に設定します。ポリシーがフローに接続されている場合でも適用されません。	true	省略可
`async`	この属性は非推奨となりました。	false	非推奨

<DisplayName> 要素

管理 UI プロキシエディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

<DisplayName>Policy Display Name</DisplayName>

デフォルト

デフォルト	なしこの要素を省略した場合、ポリシーの `name` 属性の値が使用されます。
要否	省略可
タイプ	文字列

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます。

要否省略可

タイプ文字列

<Operation> 要素

認証情報を Base64 エンコードまたは Base64 デコードするかどうかを指定します。

<Operation>Encode</Operation>

デフォルト:

なし

要否:

必須

型:

文字列。

有効な値は次のとおりです。

Encode
Decode

<IgnoreUnresolvedVariables> 要素

true に設定すると、変数を解決できない場合でもポリシーはエラーを返しません。BasicAuthentication ポリシーのコンテキストで使用される場合、この値は通常、指定された変数にユーザー名またはパスワードが格納されていない場合にエラーを返すために、false に設定されます。

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

デフォルト:	true
要否:	省略可
型:	ブール値

<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	省略可

説明

デフォルト

要否

createNew

変数がすでに設定されている場合に、その変数を上書きするかどうかを指定します。

「false」の場合、変数への割り当ては、変数が現在設定されていない（値が NULL）場合にのみ行われます。

「true」の場合は常に変数の割り当てが行われます。

通常、この値は「false」（デフォルト）に設定します。

false

省略可

<Source> 要素

デコードの場合は、Base64 でエンコードされた文字列を含む変数（Basic Base64EncodedString）。たとえば、Authorization ヘッダーに対応して request.header.Authorization を指定します。

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

デフォルト:	なし
要否:	デコード操作の場合は必須。
型:	なし

フロー変数

ポリシーが失敗した場合は、次のフロー変数が設定されます。

BasicAuthentication.{policy_name}.failed（値が true の場合）

エラーリファレンス

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 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>

BasicAuthentication ポリシー

サンプル

アウトバウンドエンコード

受信時のデコード

要素リファレンス

<BasicAuthentication> 属性

<DisplayName> 要素

<Operation> 要素

<IgnoreUnresolvedVariables> 要素

<User> 要素

属性

<Password> 要素

属性

<AssignTo> 要素

属性

<Source> 要素

フロー変数

エラーリファレンス

运行时错误

部署错误

故障变量

错误响应示例

故障规则示例

スキーマ

関連トピック

BasicAuthentication ポリシー コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

サンプル

アウトバウンド エンコード

受信時のデコード

要素リファレンス

<BasicAuthentication> 属性

<DisplayName> 要素

<Operation> 要素

<IgnoreUnresolvedVariables> 要素

<User> 要素

属性

<Password> 要素

属性

<AssignTo> 要素

属性

<Source> 要素

フロー変数

エラー リファレンス

运行时错误

部署错误

故障变量

错误响应示例

故障规则示例

スキーマ

関連トピック

BasicAuthentication ポリシー

アウトバウンドエンコード

エラーリファレンス