HTTP 要求の認証

Mule アプリケーションが要求を認証が必要なサービスに送信するときには、HTTP 要求に設定した認証を使用します。こうしたサービスとして、[OAuth2 - Authorization Code]で説明する GitHub OAuth2 などがあります。この場合、Mule アプリケーションがクライアントです。一方で、API やアプリケーションを_受信要求_の不正なアクセスから保護するには、OAuth 2.0 Access Token Enforcement Using External Provide (外部プロバイダを使用した OAuth 2.0 アクセストークンの適用)r ポリシーなどの API Manager ポリシーを使用します。

HTTP 要求コネクタは、Mule クライアントアプリケーションと、次のいずれかの種別の認証が必要なサービスとの接続をサポートします。

要求の対象である HTTP サービスで認証が必要な場合、必要なログイン情報を [HTTP Request Configuration (HTTP 要求設定)] グローバル要素で指定します。Mule は、要求の認証ヘッダーに設定されたログイン情報を使用します。

トランスポートレイヤセキュリティ (TLS) を設定して OAuth ログイン情報を暗号化することもできます。

基本認証

この例では、Studio で、ユーザ情報への要求を GitHub API に送信するアプリケーションを作成して実行します。Github API はユーザ情報の要求をポート 443 で https://api.github.com/user に受け入れます。

基本認証要件を満たすため、アプリケーションは GitHub のユーザ名とパスワードを指定します。これらのログイン情報を指定するには、HTTP 要求コネクタを設定します。

この例では、GitHub アカウントが必要です。

GitHub API をコールするには、まず、次のように HTTP リスンコネクタをセットアップします。

Studio ビジュアルエディタ

  1. Studio で、[File (ファイル)] > [New (新規)] > [Mule Project (Mule プロジェクト)] を選択して新規 Mule プロジェクトを作成します。 [New Mule Project (新規 Mule プロジェクト)] ダイアログが表示されます。

  2. [Project Settings (プロジェクト設定)] で、HTTP リスンコネクタの次のオプションを設定します。

    • Project Name (プロジェクト名): myproject

    • Runtime (ランタイム): 選択するか、デフォルトの Mule Server 3.8.0 EE 以降を受け入れます。

  3. HTTP コンポーネントをパレットからフローの [Source (ソース)] セクションにドラッグします。

  4. プロパティエディタで、[Path (パス)] のデフォルト / を受け入れ、[Allowed Methods (許可されるメソッド)] を「GET」に設定します。

  5. [Connector Configuration (コネクタ設定)] で、Add-16x16 をクリックします。

    [HTTP Listen Configuration (HTTP リスン設定)] ダイアログが表示されます。

  6. [OK] をクリックして、次のオプションを受け入れます。

    • Name (名前): HTTP_Listen_Configuration

    • Protocol (プロトコル): HTTP

    • Host (ホスト): 0.0.0.0

    • Port (ポート): 8081

  7. [OK] をクリックします。

  8. 変更を保存します。

    エラーインジケータが消えます。

次に、HTTP 要求コネクタをセットアップします。

  1. HTTP コネクタをパレットからドラッグし、フローの [Process (プロセス)] 領域にドロップします。

  2. プロパティエディタの [Connector Configuration (コネクタ設定)] で、Add-16x16 をクリックします。

    [HTTP Request Configuration (HTTP 要求設定)] ダイアログが表示されます。

  3. [HTTP Request Configuration (HTTP 要求設定)] で次のオプションを設定します。

    • Name (名前): HTTP_Request_Configuration を受け入れます。

    • Protocol (プロトコル): HTTPS

    • Host (ホスト): api.github.com

    • Port (ポート): 443

  4. [Authentication (認証)] タブで、[Basic (基本)] プロトコルを選択します。

  5. [Username (ユーザ名)] に、各自の GitHub ユーザ名を入力します。

  6. [Password (パスワード)] に、各自の GitHub パスワードまたは 個人アクセストークンを入力します。

  7. [Preemptive (プリエンプティブ)] チェックボックスをオンにし、[OK] をクリックします。

    プリエンプティブオプションをオンにすると、サーバからのプロンプトを待たずにユーザ名とパスワードが渡されます。

  8. プロパティエディタで、HTTP 要求コネクタの次のオプションを設定します。

    • Path (パス): /user

    • Method (メソッド): ドロップダウンから [GET] を選択します。

  9. 変更を保存します。

出力を JSON 形式に設定します。

  1. Transform Message (メッセージの変換) コンポーネントをパレットから HTTP 要求コンポーネントの右にドラッグします。

  2. プロパティエディタで、ペイロードの出力を次のように変更します。

    %dw 1.0
    %output application/json
    ---
      payload

最後に、アプリケーションを実行します。

  1. プロジェクトエクスプローラでプロジェクト名を右クリックし、[Run As (別のユーザとして実行)] > [Mule Application (Mule アプリケーション)] をクリックします。

    コンソールにアプリケーションがデプロイされたことが表示されます。

  2. ブラウザで URL http://localhost:8081/ を使用してアプリケーションをコールします。

    GitHub API がユーザ情報を返します。

    {
        "login":"kahn",
        "id":16xxx343,"avatar_url":"https://avatars.githubusercontent.com/u/16xxx343?v=3"`
        ...
    }

XML エディタ

<?xml version="1.0" encoding="UTF-8"?>

...
    <http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="8081" doc:name="HTTP Listener Configuration"/>
    <http:request-config name="HTTP_Request_Configuration" protocol="HTTPS" host="api.github.com" port="443" doc:name="HTTP Request Configuration">
        <http:basic-authentication username="kahn" password="7e5....921" preemptive="true"/>
    </http:request-config>
    <flow name="myprojectFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP"/>
        <http:request config-ref="HTTP_Request_Configuration" path="/user" method="GET" doc:name="HTTP"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/json
---
  payload]]></dw:set-payload>
        </dw:transform-message>
    </flow>
</mule>

NTLM 認証

NT LAN Manager (NTLM) 認証で、以前の Microsoft 製品である Microsoft LAN Manager (LANMAN) の認証プロトコルが置き換えられました。NTLM は Mule 3.7 以降で使用できます。

この例では、指定されたユーザ名とパスワードを含む「認証」ヘッダーが追加された GET 要求が http://www.example.com/test に送信されます。

Studio ビジュアルエディタ

  1. HTTP コネクタをキャンバスにドラッグし、新規の [Connector Configuration (コネクタ設定)] 要素を作成します。

  2. [Authentication (認証)] タブを選択します。

  3. [Protocol (プロトコル)] ドロップダウンメニューで、[NTLM] を選択します。

  4. ユーザ名とパスワード (またはそれらが含まれるプロファイルへの参照) を指定し、必要に応じてドメインとワークステーションも指定します。

XML エディタ

NTML 認証は基本認証と同様に設定され、子要素の属性にユーザ名とパスワードを指定します。違いは、子要素に異なる名前「ntml-authentication」が設定されることと、必要に応じてドメインおよびワークステーション属性を追加できることだけです。

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP Request Configuration">
        <http:ntlm-authentication username="myuser" password="mypass" domain="mydomain"/>
</http:request-config>

<flow name="digest_flow">
    ...
    <http:request config-ref="HTTP_Request_Configuration" path="test" method="GET" />

</flow>

ダイジェスト認証

Studio ビジュアルエディタ

  1. HTTP コネクタをキャンバスにドラッグし、新規の [Connector Configuration (コネクタ設定)] 要素を作成します。

  2. [Authentication (認証)] タブを選択します。

  3. [Protocol (プロトコル)] ドロップダウンメニューで、[Digest (ダイジェスト)] を選択します。

  4. ユーザ名とパスワード (またはそれらが含まれるプロファイルへの参照) を指定します。

XML エディタ

ダイジェスト認証は基本認証と同様に設定され、子要素の属性にユーザ名とパスワードを指定します。違いは、子要素に異なる名前「digest-authentication」が設定されることだけです。

<http:request-config name="HTTP_Request_Configuration" host="example.com" port="8081" doc:name="HTTP Request Configuration">
        <http:digest-authentication username="myuser" password="mypass"/>
    </http:request-config>

<flow name="digest_flow">
    ...
    <http:request config-ref="HTTP_Request_Configuration" path="test" method="GET" />

</flow>

この例では、指定されたユーザ名とパスワードを含む「認証」ヘッダーが追加された GET 要求が http://www.example.com/test に送信されます。

OAuth2 - 認証コード

OAuth2 - 認証コードでは、OAuth 2.0 認証コード付与種別を設定します。OAuth 認証サーバには、OAuth で保護されるリソースが保持されています。たとえば、GitHub API へのコールを OAuth を使用する GitHub サーバで認証できます。このセクションの例は、Mule クライアントアプリケーションを作成して GitHub OAuth 認証サーバ上の保護されたリソースである GitHub ユーザデータにアクセスする方法を示しています。この例では次のことを行います。

  • セットアップ

  • Mule クライアントアプリケーションの作成

  • Mule クライアントアプリケーションの実行

この例では、GitHub アカウントが必要です。

セットアップ

まず、クライアントアプリケーションを認証サーバに登録します。認証サーバが Mule クライアントアプリケーションにクライアント ID とクライアントシークレットを割り当てます。アプリケーションは、後でこれらのログイン情報を使用して認証サーバに身元を証明します。登録時には、Mule アプリケーションホームページへの URL とアプリケーションコールバック URL も指定します。

authentication in http requests 75e03

Mule クライアントアプリケーションの例をセットアップする手順は、次のとおりです。

  1. GitHub にログインします。

  2. GitHub の [Personal settings (個人設定)] で、 アプリケーションを登録します。[Register a new OAuth application (新規 OAuth アプリケーションの登録)] ページで、次のテキストボックスに入力します。

    • Application name (アプリケーション名): 任意のアプリケーション名を入力します。この例では、oauth-grant-code を使用します。

    • Homepage URL (ホームページ URL): この例では、http://localhost:8082 を使用します。

    • Authorization callback URL (認証コールバック URL): この例では、http://localhost:8082/callback を使用します。

    • [Register application (アプリケーションを登録)] をクリックします。

      GitHub で、登録されたアプリケーションのページが https://github.com/settings/applications/<app number> に作成されます。このページには、GitHub で割り当てられたクライアント ID とクライアントシークレットが含まれます。

Mule クライアントアプリケーションの作成

このセクションでは、GitHub で割り当てられたクライアント ID とクライアントシークレットを使用して GitHub OAuth2 認証サーバ上にあるユーザデータにアクセスする Mule クライアントアプリケーションを作成します。サンプルは、HTTP リスンコネクタ、HTTP 要求コネクタ、およびプレーンテキストを JSON に変換する DataWeave (Transform) コンポーネントで構成されます。HTTP 要求者に、認証サーバへのアクセスを設定します。

以下の手順で、次のようないくつかのオプションを設定します。

  • localauthorizationUrl

    受信要求をリスンするアプリケーションに URL を定義します。

  • 認証URL

    Github で提供されるこの URL により、Mule クライアントアプリケーションからのユーザ要求は GitHub 認証サーバの認証 URL にリダイレクトされます。

  • トークン URL

    Mule クライアントアプリケーションはトークンを、Mule クライアントアプリケーションに設定された*トークン URL* に送信します。

Mule クライアントアプリケーションに GitHub 認証サーバへのアクセスを設定する手順は、次のとおりです。

Studio ビジュアルエディタ

  1. OAuth モジュールをパレットから追加します。

  2. Studio で、OAuth 認証コード付与種別を使用する [HTTP Request Configuration (HTTP 要求設定)] グローバル要素を選択します。

  3. [Authentication (認証)] コンボボックスで、Authorization code grant type を選択します。

  4. 次のオプションを設定します。

    • Client Id (クライアント ID): アプリケーション登録時に GitHub から指定されたクライアント ID を入力します。

    • Client Secret (クライアントシークレット): アプリケーション登録時に GitHub から指定されたクライアント シークレットを入力します。

    • Local callback URL (ローカルコールバック URL): http://localhost:8082/callback

      この値は、GitHub にアプリケーションを登録したときに [Authorization callback URL (認証 コールバック URL)] に設定した値と同じです。

    • Authorization Url (認証URL): https://github.com/login/oauth/authorize

    • Local Authorization Ur (ローカル認証 URL)l: https://localhost:8082/login

    • Token Url (トークン URL): https://github.com/login/oauth/access_token

    • Response Access Token (応答アクセストークン): #[payload.'access_token']

      この DataWeave 式は、アクセストークンを抽出します

    • Response Refresh Token (応答更新トークン): #[payload.'access_token']

      使用しているプロバイダが更新トークンを送信する場合は、更新トークン用に類似の DataWeave 式を使用できます (#[payload.'refresh_token'] など)。ただし、この例では GitHub が実際に更新トークンを使用することはありません。

      authentication in http requests c2070
  5. [OK] をクリックします。

  6. 変更を保存します。

XML エディタ

コネクタのグローバル設定内に、oauth:authorization-code-grant-type 子要素を追加し、次の値を含めます。

  • clientIdclientSecret

    アプリケーションの登録時に GitHub から受信したクライアント ID とクライアントシークレットを使用します。

  • リソース所有者 (RO) からアクセス権が付与されたら、GitHub 認証サーバがアクセストークンを送信する先の localCallbackUrl

GitHub へのアプリケーション登録時にリダイレクト URL を指定するように要求された場合、この値はそこで指定した値と一致する必要があります。

次の属性を追加します。

  • GitHub 認証サーバが公開する authorizationUrl

  • localauthorizationUrl

次の属性も追加します。

  • GitHub 認証サーバが公開する tokenUrl

    <http:listener-config name="HTTP_Listener_Configuration"
                          host="0.0.0.0" port="8081" basePath="/github"/>
    <http:request-config name="HTTP_Request_Configuration"
                         protocol="HTTPS" host="api.github.com" port="443">
        <oauth:authorization-code-grant-type
            clientId="27...df" clientSecret="ae...6"
            localCallbackUrl="http://localhost:8082/callback"
        	   authorizationUrl="https://github.com/login/oauth/authorize"
        	   localAuthorizationUrl="http://localhost:8082/login"
            tokenUrl="https://github.com/login/oauth/access_token"
        	   responseAccessToken="#[payload.'access_token']"
        	   responseRefreshToken="#[payload.'access_token']">
        </oauth:authorization-code-grant-type>
    </http:request-config>

Mule クライアントアプリケーションの実行

Mule クライアントアプリケーションをデプロイした後、このセクションの手順に従ってアプリケーションを実行します。この手順では、次のアクションを実行します。

  • GitHub アクセスへの HTTP 要求を Mule クライアントアプリケーションに送信する (次の図の 1)。

    クライアントアプリケーションが要求を GitHub 認証サーバにリダイレクトする (図の 2)。GitHub が、ログインと登録したクライアントアプリケーションの認証を促します。

  • GitHub ログインアカウントのログイン情報を使用してログインし、アプリケーションを認証する (図の 3 ~ 4)。

    応答で、GitHub 認証サーバが​アクセストークン​を返す (図の 5)。

    authentication in http requests 42011
  • アクセストークンを使用して保護されたユーザデータを要求する (次の図の 1 ~ 2)。

    クライアントアプリケーションが GitHub 認証サーバからユーザデータを取得する (図の 3)。

    authentication in http requests 278ae

Mule クライアントアプリケーションを実行して GitHub ユーザデータを取得する手順は、次のとおりです。

アクセストークンの期限が切れる前に次の手順を実行します。

  1. プロジェクトエクスプローラでプロジェクト名を右クリックし、[Run As (別のユーザとして実行)] > [Mule Application (Mule アプリケーション)] をクリックします。

    コンソールにアプリケーションがデプロイされたことが表示されます。

  2. ブラウザで、ローカル認証 URL http://localhost:8082/login を入力して、 OAuth2 ダンスを開始します。

    GitHub がログインを促します。

  3. GitHub のユーザ名とパスワードを使用してログインします。

    GitHub が、登録されたアプリケーションの実行を認証するように促します。

    authentication in http requests 96a5d
  4. [Authorize application (アプリケーションを認証)] をクリックします。

    OAuth2 ダンスの開始に使用したブラウザに、本文テキストとして Successfully retrieved access token が表示されます。

    トークンを返してデータを取得するには、ブラウザに URL http://localhost:8081/github を入力します。

    GitHub API がユーザ情報を返します。

    {
        "login":"kahn",
        "id":16xxx343,"avatar_url":"https://avatars.githubusercontent.com/u/16xxx343?v=3"`
        ...
    }

スコープの使用

必要に応じて、Mule クライアントアプリケーションに scopes (スコープ) 属性を設定できますが、この GitHub の例では必要ありません。スコープを設定するには、認証サーバで使用できる OAuth スコープのカンマ区切りリストを定義します。OAuth のスコープはセキュリティロールに似ています。

認証 URL へのカスタムパラメータの送信

OAuth 実装で、OAuth 認証サーバ (OAS) の認証 URL をコールするときに、追加のクエリパラメータの送信を要求または許可する場合があります。

Studio ビジュアルエディタ

  1. Studio で、OAuth 認証コード付与種別を使用する [HTTP Request Configuration (HTTP 要求設定)] グローバル要素を選択します。

  2. [Authentication (認証)] コンボボックスで、Authorization code grant type を選択します。

  3. 前の例と同じ項目に入力します。

  4. Custom Parameters で、Edit inline を選択します。プラス (+) ボタンを必要な回数クリックして、各カスタムパラメータの名前と値を定義します。

XML エディタ

この例には、この API 固有のパラメータを定義する 2 つの oauth:custom-parameter 子要素が含まれます。

<http:request-config name="HTTP_Request_Configuration"
                     host="api.box.com" port="443" basePath="/2.0">
        <oauth:authorization-code-grant-type
            clientId="your_client_id" clientSecret="your_client_secret"
            localCallbackUrl="http://localhost:8082/redirectUrl"
            authorizationUrl="http://www.box.com/api/oauth2/authorize"
            localAuthorizationUrl="http://localhost:8082/authorization"
            tokenUrl="http://www.box.com/api/oauth2/token">
                <oauth:custom-parameters>
                    <oauth:custom-parameter
                        key="box_device_id" value="123142"/>
                    <oauth:custom-parameter
                        key="box_device_name" value="my-phone"/>
                </oauth:custom-parameters>
        </oauth:authorization-code-grant-type>
    </http:request-config>

リダイレクト URI の上書き (external redirect_uri)

OAuth 2.0 仕様には、リダイレクトの宛先サイトからリダイレクト URI をチェックする方法が説明されています。OAuth 認証サーバはこの URL を使用して、アクセストークンを取得するための認証コードを Mule サーバに提供します。この URL を指定する場合、Mule はその URL にエンドポイントを作成して認証コードを保存します。ただし、手動で認証コードを抽出するためのエンドポイントがすでに登録されていている場合は除きます。

属性 externalCallbackUrl を設定して、外部 リダイレクト URI を設定します。

externalCallbackUrl を使用すると、アプリケーションを CloudHub にデプロイする場合などは特に便利です。認証の設定時に、localCallbackUrl を次の形式で指定する必要があります。

たとえば、localCallbackUrl は、前の例では http://localhost:8082/callback です。

CloudHub のエンドポイントを作成するために、Mule は、CloudHub のエンドポイントを別の形式で作成する必要があります。次に例を示します。

https://<app>.cloudhub.io/<redirect Uri>

Mule に、正しい形式で CloudHub のエンドポイントを作成するように指示するには、oauth:authorization-code-grant-type 設定に externalCallbackUrl 属性を含めます。

トークン URL 応答からのパラメータの抽出

認証サーバから認証コードを取得したら、OAuth ダンサーがサーバのトークン URL に​アクセストークン​の受信を要求します。

トークン URL への要求に対する応答の形式は、OAuth 仕様では定義されていません。したがって、実装ごとに異なる応答形式が返されることがあります。デフォルトでは、Mule は応答が JSON 形式であることを期待します。この場合、その要素の名前が次のようであれば、HTTP 応答コネクタは必要な情報の抽出方法を判断できます。

  • アクセストークン: JSON 項目の名前が access_token

  • 更新トークン: JSON 項目の名前が refresh_token

  • 有効期限: JSON 項目の名前が expires_in

応答が JSON 形式の場合、パラメータは自動的に抽出されるため、前の GitHub の例のように、DataWeave 式を使用して、トークン URL への要求に対する応答内のこれらの値を参照できます。

応答が JSON 形式ではない場合、最初にコネクタを設定して、これらの値の抽出方法がわかるようにする必要があります。次の例では、コネクタは応答の Content-Typeapplication/x-www-form-urlencoded であることを期待するため、応答の本文はペイロードのマッピングに変換されます。DataWeave 式 (#[payload.access_token] など) を使用してマッピングから値を抽出します。

Studio ビジュアルエディタ

[Authentication (認証)] タブで、次のように OAuth2 - 認証コード​のオプションを設定します。

  • Response Access Token (応答アクセストークン): #[payload.access_token]

  • Response Refresh Token (応答更新トークン): #[payload.refresh_token]

  • Response Expires In (応答有効期限): #[payload.expires_in]

XML エディタ

この例には、この API 固有のパラメータを定義する 2 つの oauth:custom-parameter 子要素が含まれます。

<http:request-config name="HTTP_Request_Configuration"
                     host="api.box.com" port="443" basePath="/2.0">
        <oauth:authorization-code-grant-type
            clientId="your_client_id" clientSecret="your_client_secret"
            localCallbackUrl="http://localhost:8082/redirectUrl"
            authorizationUrl="http://www.box.com/api/oauth2/authorize"
            localAuthorizationUrl="http://localhost:8082/authorization"
            tokenUrl="http://www.box.com/api/oauth2/token"
            responseAccessToken="#[payload.'access_token']"
            responseExpiresIn="#[payload.'expires_in']"
             responseRefreshToken="#[payload.'refresh_token']>
        </oauth:authorization-code-grant-type>
    </http:request-config>

更新アクセストークンのカスタマイズ

トークン URL から取得するアクセストークンは、そのうち期限切れになります。トークンの有効期間の長さは、認証サーバの実装に応じて異なります。アクセストークンの期限が切れたら、プロセス全体をもう一度実行するのではなく、トークン URL 応答で提供される​更新アクセストークン​を使用して、新しいアクセストークンを取得できます。

Mule では、このユースケースが自動的に処理されます。そのためデフォルトでは、HTTP 要求コネクタが実行され、応答の状況コードが 403 の場合、Mule はトークン URL をコールして新しいアクセストークンを取得します。

Mule がいつこれらの要求のいずれかを実行し、DataWeave 式を使用して新しいアクセストークンを取得するかをカスタマイズできます。式は HTTP 要求コネクタコールの応答に対して評価されます。

Studio ビジュアルエディタ

[Authentication (認証)] セクションで、​[Request Token When (トークンを要求するタイミング)] コンボを Expression に設定し、その横にある項目に次の DataWeave 式を設定します。 #[payload.response.status == 'unauthorized']

XML エディタ

新しいアクセストークンを取得するためのコールをいつ実行するかを設定するには、oauth:authorization-code-grant-type 要素の属性 refreshTokenWhen に対する DataWeave 式を設定します。

<http:request-config name="HTTP_Request_Configuration"
                     host="api.box.com" port="443" basePath="/2.0">
        <oauth:authorization-code-grant-type
            clientId="your_client_id" clientSecret="your_client_secret"
            localCallbackUrl="http://localhost:8082/redirectUrl"
            authorizationUrl="http://www.box.com/api/oauth2/authorize"
            localAuthorizationUrl="http://localhost:8082/authorization"
            tokenUrl="http://www.box.com/api/oauth2/token"
            refreshTokenWhen="#[payload.response.status == 'unauthorized']">
        </oauth:authorization-code-grant-type>
    </http:request-config>

要求の認証が失敗したら、応答には名前が status で値が ‘unauthorized’ の XML ノードが含まれます。前の例では、DataWeave 式がその条件を評価します。true と評価すると、Mule は要求をトークン URL に送信して新しいアクセストークンを取得します。

複数ユーザの代理でのリソースアクセス

これまでの例では、1 人のユーザを認証しました。認証期間中に各ユーザを識別する方法を定義することで、1 つのアプリケーションで複数のユーザのアクセストークンを処理できます。この期間中、要求をトークン URL に送信してアクセストークンを取得し、必要なアクセストークンを使用して API に対する操作を実行します。

Mule クライアントアプリケーションにアクセス権を付与するユーザを識別するには、ローカル認証 URL へのコールに基づいて​リソース所有者 ID を取得する DataWeave 式を定義します。

Studio ビジュアルエディタ

[Authentication (認証)] セクションで、次のように OAuth2 - 認証コード​のオプションを設定します。

  • Resource Owner ID (リソース所有者 ID): #[vars.userId]

  • Local Authorization URL resource owner id (ローカル認証 URL のリソース所有者 ID): #[attributes.queryParams.userId]

項目 [Resource Owner ID (リソース所有者 ID)] に DataWeave 式を設定して、HTTP 要求コネクタの実行ごとに Mule メッセージから RO ID を取得できるようにする必要があります。そのためこの例では、HTTP 要求コネクタが実行されるときは常に、「userId」という名前のフロー変数に使用する RO ID が含まれている必要があります。この変数を作成するには、Variable (変数) トランスフォーマをフローの HTTP 要求コネクタの前の位置に追加し、Mule イベントで userId 変数を作成するようにそのトランスフォーマを設定できます。

それを [Local Authorization URI (ローカル認証 URI)] 項目 ([Advanced (詳細)] セクション内) で定義します。RO ID を取得するには、終了したコールから userId クエリパラメータをローカル認証 URL に解析する必要があります。

http://localhost:8082/authorization?userId=john と入力した場合、RO の john は、クライアントアプリケーション (CA) に代理 アクセス権を付与できます。http://localhost:8082/authorization?userId=peter と入力した場合、RO の peter は、CA に代理アクセス権を付与できます。

XML エディタ

resourceOwnerId[vars.userId]localAuthorizationUrlResourceOwnerId[attributes.queryParams.userId] に設定します。

<http:request-config name="HTTP_Request_Configuration"
                     host="api.box.com" port="443" basePath="/2.0"
                     tlsContext-ref="TLS_Context">
        <oauth:authorization-code-grant-type
            clientId="your_client_id" clientSecret="your_client_secret"
            localCallbackUrl="http://localhost:8082/redirectUrl"
            localAuthorizationUrlResourceOwnerId="#[attributes.queryParams.userId]"
            resourceOwnerId="#[vars.userId']"
            authorizationUrl="http://www.box.com/api/oauth2/authorize"
            localAuthorizationUrl="http://localhost:8082/authorization"
            scopes="access_user_details, read_user_files"
            tokenUrl="http://www.box.com/api/oauth2/token"
            refreshTokenWhen="#[xpath3('/response/status/text()')]">
        </oauth:authorization-code-grant-type>
    </http:request-config>

属性 resourceOwnerId に DataWeave 式を設定して、http:request の実行ごとに Mule イベントから RO ID を取得できるようにする必要があります。そのためこの例では、http:request が実行されるときは常に、「userId」という名前のフロー変数に使用する RO ID が含まれている必要があります。

    <flow name="accessROFolders">
        <set-variable variableName="userId" value="#['Peter']"/>
        <http:request config-ref="HTTP_Request_Configuration"
            path="/folders" method="GET"/>
    </flow>

それを属性 localAuthorizationUrlResourceOwnerId で定義します。RO ID を取得するには、終了したコールから userId クエリパラメータをローカル認証 URL に解析する必要があります。

http://localhost:8082/authorization?userId=john と入力した場合、RO の john は、クライアントアプリケーション (CA) に代理 アクセス権を付与できます。http://localhost:8082/authorization?userId=peter と入力した場合、RO の peter は、CA に代理アクセス権を付与できます。

OAuth 認証コードでの HTTPS の使用

本番環境のように、認証サーバとの通信に HTTPS を使用する必要がある場合、HTTPS エンコードをすべての要求 (以下に対する要求を含む) の OAuth ログイン情報に適用します。

  • ローカル認証 ID

  • 認証 URL

  • リダイレクト URL

  • トークン URL

HTTP 要求コネクタの認証設定に TLS コンテキストを指定することで、これがすべての要求で処理されます。

Studio ビジュアルエディタ

[Authentication (認証)] セクションで、次のように OAuth2 - 認証コード​のオプションを設定します。

  1. TLS 設定セクションで、[Global Reference (グローバル参照)] を選択します。

  2. 項目の横にある緑のプラス記号をクリックして新規 TLS コンテキストを作成します。

  3. トラストストアおよびキーストア設定をセットアップし、[OK] をクリックして保存します。

[Authentication (認証)] タブの TLS 設定で、OAuth ログイン情報をエンコードします。[HTTP Request Configuration (HTTP 要求設定)] の [TLS/SSL] タブで、リクエストボディをエンコードします。

XML エディタ

tlsContext を設定して TLS コンテキスト要素を参照し、この要素にトラストストアとキーストアのログイン情報を指定します。

<http:request-config name="HTTP_Request_Configuration_HTTPS"
                     host="api.box.com" port="443" basePath="/2.0"
                     tlsContext-ref="TLS_Context" protocol="HTTPS">
        <oauth:authorization-code-grant-type
            clientId="your_client_id" clientSecret="your_client_secret"
            localCallbackUrl="http://localhost:8082/redirectUrl"
            tlsContext="TLS_Context"
            authorizationUrl="https://www.box.com/api/oauth2/authorize"
            localAuthorizationUrl="https://localhost:8082/authorization"
            scopes="access_user_details, read_user_files"
            tokenUrl="https://www.box.com/api/oauth2/token">
        </oauth:authorization-code-grant-type>
    </http:request-config>

    <tls:context name="TLS_Context">
        <tls:trust-store path="your_trust_store"
            password="your_password"/>
        <tls:key-store path="your_keystore_path"
            password="your_password" keyPassword="your_key_password"/>
    </tls:context>

oauth:authorization-code-grant-type 要素の tlsContext 属性は、OAuth ログイン情報のエンコードに使用されます。http:request-configtls:context 子要素は、リクエストボディのエンコードに使用されます。

OAuth2 - クライアントログイン情報

[OAuth Authentication - Client Credentials (OAuth 認証 - クライアントログイン情報)] タブで、クライアントログイン情報付与種別を設定します。

OAuth 認証サーバ (​OAS​) は、OAuth で保護されるリソースが保持されるサーバです。たとえば、Box サーバは OAuth 認証のある API を提供します。

クライアントアプリケーション (​CA​) は、OAuth 認証サーバに保持されていてリソース所有者に属する保護されたリソースへのアクセスを試みるサーバです。たとえば、Box サーバに保持されていて属するリソースにアクセスしようとする Mule サーバなどです。

この場合、リソース所有者 (RO) は CA でもあります。つまり、RO によって CA が暗黙的に認証されるため、手順全体が大幅に簡素化されます。

シンプルな OAuth ダンス
  1. CA はアプリケーションを OAS サーバに登録する必要があります。これが行われると、OAS がログイン情報を CA に割り当て、それを後で使用して身元証明に使用できます (​クライアント ID と​クライアントシークレット​)。OAS は​トークン URL も提供する必要があります。CA は、後で保護されたリソースへのアクセスが必要になったときに、このトークン URL に HTTP 要求を送信して必要な​アクセストークン​を取得できます。

  2. CA は、OAS の​トークン URL に対して、身元を証明するためのクライアント ID が含まれる要求を実行します。応答として、OAS は CA に​アクセストークン​を付与します。

  3. このアクセストークンがあると、CA は、要求にアクセストークンが含まれている限り、OAS にある保護されたリソースに自由にアクセスできるようになります。OAS が定義したポリシーに応じて、このトークンがそのうち期限切れになることがあります。

設定

クライアントログイン情報付与種別は、CA が、OAS の RO (リソース所有者) の代理ではなく、それ自体の代理としてアプリケーションにアクセス権を付与するためのものです。アクセストークンを取得するために必要なのは、アプリケーションのログイン情報のみです。

Studio ビジュアルエディタ

  1. Studio で、OAuth 認証コード付与種別を使用する [HTTP Request Configuration (HTTP 要求設定)] グローバル要素を選択します。

  2. [Authentication (認証)] コンボボックスで、Client credentials grant type を選択します。

  3. 次の項目に入力します。

    • アプリケーションの登録時に OAS から割り当てられた [Client Id (クライアント ID)][Client Secret (クライアントシークレット)]

    • [Scopes (スコープ)] 項目 (省略可能)。OAS で使用可能な OAuth スコープのカンマ区切りリストを定義できます。OAuth のスコープはセキュリティロールによく似ています。 OAuth が公開する トークン URL

XML エディタ

次の情報を含める必要があります。

  • アプリケーションの登録時に OAS から割り当てられた clientIdclientSecret​。

  • scopes 属性 (省略可能)。OAS で使用可能な OAuth スコープのカンマ区切りリストを定義できます。OAuth のスコープはセキュリティロールによく似ています。

  • OAuth が公開する tokenUrl​。

<http:request-config name="HTTP_Request_Configuration"
                     host="some.api.com" port="80" basePath="/api/1.0">
        <oauth:client-credentials-grant-type
            clientId="your_client_id" clientSecret="your_client_secret"
            tokenUrl="http://some.api.com/api/1.0/oauth/token"
            scopes="access_user_details, read_user_files">
        </oauth:client-credentials-grant-type>
    </http:request-config>

Mule アプリケーションは、デプロイ時にアクセストークンの取得を試みます。アプリケーションがアクセストークンを取得できない場合、デプロイメントで失敗します。

トークン URL 応答からのパラメータの抽出

認証コードに適用されるのと同じ動作をクライアントログイン情報付与種別に適用できます。

更新アクセストークンのカスタマイズ

認証コードに適用されるのと同じ動作をクライアントログイン情報付与種別に適用できます。

トークンマネージャ設定

トークンマネージャ設定を使用して、クライアントログイン情報と認証コードの認証情報にアクセスできます。

Studio ビジュアルエディタ

  1. Studio で、OAuth 認証コード付与種別を使用する [HTTP Request Configuration (HTTP 要求設定)] グローバル要素を選択します。

  2. [Authentication (認証)] コンボボックスで、Client credentials grant type を選択します。

  3. フォームの [Advanced (詳細)] セクションで、Token ManagerGlobal Reference に設定し、​[Token Manager (トークンマネージャ)] の横にある​緑のプラス記号​をクリックして新しいトークンマネージャを作成します。

  4. それをオブジェクトストアへの参照に割り当てます。

XML エディタ

tokenManager-ref 属性は、設定の token-manager-config 要素を参照する必要があります。

    <oauth:token-manager-config name="Token_Manager_Config"/>

    <http:request-config name="HTTP_Request_Configuration"
                         host="api.box.com" port="443" basePath="/2.0">
        <oauth:authorization-code-grant-type
            clientId="your_client_id" clientSecret="your_client_secret"
            localCallbackUrl="http://localhost:8082/redirectUrl"
            tokenManager-ref="Token_Manager_Config"
            localAuthorizationUrlResourceOwnerId="#[attributes.queryParams.userId]"
            resourceOwnerId="#[vars.userId']"
            authorizationUrl="https://www.box.com/api/oauth2/authorize"
            localAuthorizationUrl="https://localhost:8082/authorization"
            scopes="access_user_details, read_user_files"
            tokenUrl="https://www.box.com/api/oauth2/token">
        </oauth:authorization-code-grant-type>
    </http:request-config>

トークンマネージャを使用した認証情報へのアクセス

トークンマネージャを認証付与種別に関連付けたら (以下の例では認証コードに関連付け)、OAuth モジュールで提供される操作をフロー内の任意の場所で使用して、OAuth 認証からの情報にアクセスできます。

RO が単一​の​クライアントログイン情報​または認証コードを使用している場合、フローでは次の操作を使用します。

    <oauth:retrieve-access-token tokenManager="tokenManagerConfig"/>

    <oauth:retrieve-refresh-token tokenManager="tokenManagerConfig"/>

    <oauth:retrieve-expires-in tokenManager="tokenManagerConfig"/>

    <oauth:retrieve-state tokenManager="tokenManagerConfig"/>

    <oauth:retrieve-custom-token-response-param tokenManager="tokenManagerConfig" key="#[vars.key]"/>

この操作では、トークンマネージャから OAuth 認証情報にアクセスできます。

  • tokenManager: 設定でのトークンマネージャの名前

RO が複数​の認証コードを使用している場合、次の操作を使用します。

    <oauth:retrieve-access-token tokenManager="tokenManagerConfig" resourceOwnerId="#[vars.resourceOwnerId]"/>

    <oauth:retrieve-refresh-token tokenManager="tokenManagerConfig" resourceOwnerId="#[vars.resourceOwnerId]"/>

    <oauth:retrieve-expires-in tokenManager="tokenManagerConfig" resourceOwnerId="#[vars.resourceOwnerId]"/>

    <oauth:retrieve-state tokenManager="tokenManagerConfig" resourceOwnerId="#[vars.resourceOwnerId]"/>

    <oauth:retrieve-custom-token-response-param tokenManager="tokenManagerConfig" resourceOwnerId="#[vars.resourceOwnerId]" key="#[vars.key]"/>

この操作では、トークンマネージャから OAuth 認証情報にアクセスできます。

  • tokenManager: 設定でのトークンマネージャの名前

  • resourceOwnerId: RO の ID

次の表には、トークンマネージャから情報を取得する方法の例が含まれます。フローで、OAuth 認証を処理する HTTP 要求コネクタの後にこれらの操作を配置して使用します。

関数 結果

<oauth:retrieve-access-token tokenManager="tokenManagerConfig" target="accessToken"/>

accessToken 値には、DataWeave から vars.accessToken を使用してアクセスできます。

<oauth:retrieve-access-token tokenManager="tokenManagerConfig" resourceOwnerId="Perter" target="accessToken"/>

ID 「Peter:」で識別される RO の accessToken 値には、DataWeave から vars.accessToken を使用してアクセスできます。

<oauth:retrieve-refresh-token tokenManager="tokenManagerConfig" target="refreshToken"/>

refreshToken 値には、DataWeave から 'vars.refreshToken' を使用してアクセスできます。

<oauth:retrieve-expires-in tokenManager="tokenManagerConfig" target="expiresIn"/>

expires in 値には、DataWeave から 'vars.expiresIn' を使用してアクセスできます。

<oauth:retrieve-state tokenManager="tokenManagerConfig" target="state"/>

認証 URL に使用される state には、DataWeave から 'vars.state' を使用してアクセスできます。

<oauth:retrieve-custom-token-response-param tokenManager="tokenManagerConfig" key="a_custom_param_name" target="customParam"/>

トークン URL 応答から抽出されたカスタムパラメータには、DataWeave から 'vars.customParam' を使用してアクセスできます。

<oauth:retrieve-custom-token-response-param tokenManager="tokenManagerConfig" esourceOwnerId="Perter" key="a_custom_param_name" target="customParam"/>

RO 'Peter' のトークン URL 応答から抽出されたカスタムパラメータには、DataWeave から vars.customParam を使用してアクセスできます。

アクセストークンの無効化

トークンマネージャの使用時に、特定の RO をブロックできます。

Studio ビジュアルエディタ

  1. [Invalidate OAuth Context (OAuth コンテキストの無効化)] 要素をキャンバスにドラッグします。

  2. プロパティエディタで、[Token Manager Configuration (トークンマネージャ設定)] をセットアップして、OAuth 認証の処理時に HTTP 要求コネクタが参照するものと同じ​トークンマネージャ​を参照するようにします。

XML エディタ

<flow name="invalidateOauthContext">
    <oauth:invalidate-oauth-context tokenManager="tokenManagerConfig"/>
</flow>

[Invalidate OAuth Context (OAuth コンテキストの無効化)] 要素は、トークンマネージャ内に保存されているすべての OAuth 情報をクリーンアップします。

1 つのトークンマネージャで複数の RO を使用する場合、ある RO の OAuth 情報のみをクリアするには、[Invalidate OAuth Context (OAuth コンテキストの無効化)] 要素にリソース所有者 ID を指定する必要があります。

Studio ビジュアルエディタ

  1. [Invalidate OAuth Context (OAuth コンテキストの無効化)] 要素をキャンバスにドラッグします。

  2. プロパティエディタで、[Token Manager Configuration (トークンマネージャ設定)] をセットアップして、OAuth 認証の処理時に HTTP 要求コネクタが参照するものと同じ*トークンマネージャ*を参照するようにします。

  3. [Resource Owner Id (リソース所有者 ID)] を、クリアする RO を参照する式に設定します。例: #[vars.resourceOwnerId]

XML エディタ

<flow name="invalidateOauthContextWithResourceOwnerId">
    <oauth:invalidate-oauth-context tokenManager="tokenManagerConfig"
                                    resourceOwnerId="#[vars.resourceOwnerId]"/>
</flow>

トークンマネージャのオブジェクトストアのカスタマイズ

デフォルトでは、トークンマネージャはメモリ内オブジェクトストアを使用してログイン情報を保存します。objectStore 属性を使用して、トークンマネージャのオブジェクトストアをカスタマイズできます。カスタムオブジェクトストアの設定方法を参照してください

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub