BasicAuthentication ポリシー

概要

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

このポリシーでは、Base64 でエンコードされた文字列で保管された認証情報をユーザー名とパスワードにデコードすることもできます。

動画: 次の動画では、Basic Authentication ポリシーを使用してユーザー名とパスワードを Base64 でエンコードする方法を紹介しています。

動画: 次の動画では、Basic Authentication ポリシーを使用して、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 ポリシーで Key-Value ストアから <User> 要素と <Password> 要素の値を抽出し、それらを変数 credentials.usernamecredentials.password に代入できるようにするには、あらかじめ、次の KeyValueMapOperations ポリシーを添付しておきます。

    <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 変数に書き込まれます。


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 でエンコードまたはデコードするかどうかを決定します。

    <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>
デフォルト: なし
必須?: 必須
型:

String

属性

属性 説明 デフォルト 要否
createNew 変数がすでに設定されている場合に、このポリシーでその変数を上書きするかどうかを決定します。

「false」の場合、変数が現在未設定(null)の場合にのみ、変数への割り当てが行われます。

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

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

false 省略可

<Source> 要素

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

    <Source>request.header.Authorization</Source>
    
デフォルト: なし
要否: デコード操作の場合は必須。
型:

なし

フロー変数

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

  • BasicAuthentication.{policy_name}.failed(値は ture)

エラー リファレンス

このセクションでは、このポリシーでエラーをトリガーしたときに返される障害コードおよびエラー メッセージと、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>
    

スキーマ

関連トピック

Key Value Map Operations ポリシー