BasicAuthentication ポリシー

概要

ラストマイル セキュリティのために、簡易な Basic 認証を使用できます。このポリシーは、ユーザー名とパスワードを取得し、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 属性で指定された変数から取得されます。これらの変数はポリシーの実行前に設定されている必要があります。一般に、変数には 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.usernamecredentials.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 変数にそれぞれ書き込まれます。


Basic Authentication ポリシーについて

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

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

一般に、ユーザー名とパスワードは Key-Value ストアに格納され、ランタイムにその Key-Value ストアから読み取られます。Key-Value ストアの使用について詳しくは、Key Value Map Operations ポリシーをご覧ください。

要素リファレンス

この要素リファレンスは、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 に設定します。

false 省略可
enabled

ポリシーを適用するには true に設定します。

ポリシーを無効にするには false に設定します。その場合、ポリシーはフローに接続されていているとしても適用されません。

true 省略可
async

この属性は非推奨となりました。

false 非推奨

<DisplayName> 要素

name 属性に加えて、管理 UI プロキシ エディタのポリシーに別のわかりやすい名前でラベルを付けるために使います。

<DisplayName>Policy Display Name</DisplayName>
デフォルト:

なし

この要素を省略した場合、ポリシーの 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 省略可

<Source> 要素

デコードの場合は、Base64 でエンコードされた文字列を含む変数(Basic Base64EncodedString)。たとえば、Authorization ヘッダーに対応して request.header.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 Edge 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 (e.g., 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

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

スキーマ

関連トピック

Key Value Map Operations ポリシー