HTTP 要求の認証の設定 - Mule 4

HTTP 用 Anypoint Connector (HTTP Connector) の Request 操作は、Mule クライアントアプリケーションと、次のいずれかの種別の認証が必要なサービスとの接続をサポートします。

Basic Authentication (基本認証)
ダイジェスト認証
NTLM 認証
OAuth2 認証コード許可種別認証
OAuth2 クライアントログイン情報許可種別認証

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

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

API または Mule アプリケーションが未認証のソースから要求を受信しないように保護するには、API Manager ポリシーを使用します。「外部プロバイダーを使用した OAuth 2.0 アクセストークンの適用」を参照してください。

Anypoint Studio の HTTP Request 操作のグローバル設定では、[Authentication (認証)] 項目で [Expression (式)] オプションを使用しないでください。

HTTP XML 認証のセットアップ

HTTP Connector の認証の XML 値:

認証種別 XML 値

認証種別	XML 値
基本認証	`<http:authentication > <http:basic-authentication username="UN" password="PW"/> </http:authentication>`
NTLM 認証	`<http:authentication > <http:ntlm-authentication domain="DM" workstation="WS" username="UN" password="PW" /> </http:authentication>`
ダイジェスト認証	`<http:authentication > <http:digest-authentication username="UN" password="PW"/> </http:authentication>`

基本認証

<http:authentication >
  <http:basic-authentication
  username="UN" password="PW"/>
</http:authentication>

NTLM 認証

<http:authentication >
  <http:ntlm-authentication
  domain="DM" workstation="WS"
  username="UN" password="PW" />
</http:authentication>

ダイジェスト認証

<http:authentication >
  <http:digest-authentication
  username="UN" password="PW"/>
</http:authentication>

また、Studio で OAuth コンポーネントの操作をキャンバスに追加すると、次の連動関係がプロジェクトの pom.xml ファイルに自動的に追加されます。

<dependency>
    <groupId>org.mule.modules</groupId>
    <artifactId>mule-oauth-module</artifactId>
    <version>1.1.8</version>
    <classifier>mule-plugin</classifier>
</dependency>

基本認証を設定する

基本認証メソッドを使用すると、HTTP ユーザーエージェントは HTTP 要求を行うときにユーザー名とパスワードを指定できます。

次の Mule アプリケーションの例は、ユーザー情報の要求を GitHub API に送信して HTTP Request 操作の基本認証を設定する方法を示しています。この例では、Github API はユーザー情報の要求を https://api.github.com/user へのポート 443 で受け入れます。基本認証要件を満たすため、Mule アプリケーションは GitHub のユーザー名とパスワードを指定します。このログイン情報を指定するには、HTTP Request 操作を設定します。

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

Studio の [Mule Palette (Mule パレット)] で、[HTTP] > [Listener] を選択します。
[Listener] を Studio キャンバスにドラッグします。
[Path (パス)] を /path に設定します。
[Connector configuration (コネクタ設定)] 項目の横にあるプラス記号 (+) をクリックして、アプリケーション内のすべてのソースのインスタンスで使用できるグローバル要素を設定します。
[HTTP Listener config (HTTP リスナー設定)] ウィンドウで、次の項目を設定します。
- Protocol (プロトコル): HTTP (Default)
- Host (ホスト): All Interfaces [0.0.0.0] (default)
- Port (ポート): 8081
[OK] をクリックします。
[Advanced (詳細)] タブで [Allowed methods (許可されるメソッド)] を GET に設定します。
HTTP の [Request] 操作を HTTP の [Listener] ソースの横にドラッグします。
[Connector configuration (コネクタ設定)] 項目の横にあるプラス記号 (+) をクリックして、アプリケーション内の操作のすべてのインスタンスで使用できるグローバル要素を設定します。
[HTTP Request configuration (HTTP 要求設定)] ウィンドウで、次の項目を設定します。
- Name (名前): HTTP_Request_configuration
- Protocol (プロトコル): HTTPS
- Host (ホスト): api.github.com
- Port (ポート): 443
[Authentication (認証)] を [Basic authentication (基本認証)] に設定します。
[Username (ユーザー名)] を GitHub ユーザー名アカウントに設定します。
[Password (パスワード)] を GitHub パスワードアカウントまたは個人アクセストークンに設定します。
[Preemptive (プリエンプティブ)] を [True (Default) (True (デフォルト))] に設定します。
[OK] をクリックします。
HTTP Request 設定ウィンドウで、[Method (メソッド)] を [GET (Default) (GET (デフォルト))] に設定します。
[Path (パス)] を /user に設定します。
[Mule Palette (Mule パレット)] で、[Core (コア)] > [Transform message] を選択します。
[Transform message] コンポーネントを HTTP の [Request] 操作の右にドラッグします。
[Output (出力)] プロパティウィンドウで、出力を次の DataWeave コードに変更します。
```
%dw 2.0
output application/json
---
payload
```
Mule アプリケーションを保存します。
[Run (実行)] > [Run As (別のユーザーとして実行)] > [Mule Application (Mule アプリケーション)] をクリックします。
API をコールするには、インターネットブラウザーに http://localhost:8081/ を入力します。

GitHub API がユーザー情報を返します。次に例を示します。
```
{
    "login":"kahn",
    "id":16xxx343,
    "avatar_url":"https://avatars.githubusercontent.com/u/16xxx343?v=3"`
    ...
}
```

ブラウザーで HTTP GET on resource 'https://api.github.com:443/user' failed: unauthorized (401) が返された場合、GitHub パスワードを指定する代わりに個人アクセストークンを使用します。新しいトークンを生成する場合、[user] > [read:user] スコープのみが必要です。

基本認証を設定する XML の例

この例のフローをすばやく Mule アプリケーションに読み込むには、次のコードを Studio XML エディターに貼り付けます。

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core" xmlns:http="http://www.mulesoft.org/schema/mule/http"
	xmlns="http://www.mulesoft.org/schema/mule/core"
	xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/ee/core http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd">
	<http:listener-config name="HTTP_Listener_config" >
		<http:listener-connection host="0.0.0.0" port="8081" />
	</http:listener-config>
	<http:request-config name="HTTP_Request_configuration" >
		<http:request-connection protocol="HTTPS" host="api.github.com" port="443" >
			<http:authentication >
				<http:basic-authentication username="GitHubusername" password="GitHubpassword" />
			</http:authentication>
		</http:request-connection>
	</http:request-config>
	<flow name="Authenticaterequests" >
		<http:listener config-ref="HTTP_Listener_config" path="/path">
		</http:listener>
		<http:request method="GET" config-ref="HTTP_Request_configuration" path="/user"/>
		<ee:transform >
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
payload]]></ee:set-payload>
			</ee:message>
		</ee:transform>
	</flow>
</mule>

ダイジェスト認証を設定する

ダイジェスト認証メソッドを使用すると、Web サーバーはユーザーの Web ブラウザーを介してユーザーログイン情報を検証できます。

次の例は、GET 要求を URL http://www.example.com/test に送信し、指定されたユーザー名とパスワードを含む認証ヘッダーを追加して、HTTP Request 操作のダイジェスト認証を設定する方法を示しています。

Studio で、フローから HTTP の [Request] 操作を選択します。
[Method (メソッド)] を GET に、[Path (パス)] を test に設定します。
[Connector configuration (コネクタ設定)] 項目の横にあるプラス記号 (+) をクリックして、アプリケーション内の操作のすべてのインスタンスで使用できるグローバル要素を設定します。
[HTTP Request configuration (HTTP 要求設定)] ウィンドウで、次の項目を設定します。
- Name (名前): HTTP_Request_configuration
- Protocol (プロトコル): HTTPS
- Host (ホスト): example.com
- Port (ポート): 8081
[Authentication (認証)] を [Digest authentication (ダイジェスト認証)] に設定します。
[Username (ユーザー名)] を Username に設定します。
[Password (パスワード)] を Password に設定します。
[OK] をクリックします。

ダイジェスト認証を設定する XML の例

次のコードは、XML でダイジェスト認証を設定する方法を示しています。

...
<http:request-config name="HTTP_Request_configuration"
      doc:name="HTTP Request configuration" >
    <http:request-connection host="example.com" port="8081" >
        <http:authentication >
            <http:digest-authentication
              username="Username"
              password="Password" />
        </http:authentication>
    </http:request-connection>
</http:request-config>
<flow name="digest_flow">
    ...
    <http:request config-ref="HTTP_Request_configuration"
    path="test"
    method="GET" />
</flow>

NTLM 認証を設定する

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

次の例は、GET 要求を URL http://www.example.com/test に送信し、指定されたユーザー名とパスワードを含む認証ヘッダーを追加して、HTTP Request 操作の NTLM 認証を設定する方法を示しています。

Studio で、フローから HTTP の [Request] 操作を選択します。
[Method (メソッド)] を GET に、[Path (パス)] を test に設定します。
[Connector configuration (コネクタ設定)] 項目の横にあるプラス記号 (+) をクリックして、アプリケーション内の操作のすべてのインスタンスで使用できるグローバル要素を設定します。
[HTTP Request configuration (HTTP 要求設定)] ウィンドウで、次の項目を設定します。
- Name (名前): HTTP_Request_configuration
- Protocol (プロトコル): HTTPS
- Host (ホスト): example.com
- Port (ポート): 8081
[Authentication (認証)] を [Ntlm authentication (NTLM 認証)] に設定します。
[Username (ユーザー名)] を Username に設定します。
[Password (パスワード)] を Password に設定します。
[Domain (ドメイン)] と [Workstation (ワークステーション)] を設定します (省略可能)。
[OK] をクリックします。

NTLM 認証を設定する XML

次のコードは、XML で NTLM 認証を設定する方法を示しています。

<http:request-config name="HTTP_Request_configuration"
     doc:name="HTTP Request Configuration" >
  <http:request-connection
     host="example.com"
     port="8081" >
     <http:authentication >
        <http:ntlm-authentication username="Username" password="Password" />
     </http:authentication>
  </http:request-connection>
</http:request-config>
<flow name="digest_flow">
    ...
    <http:request method="GET" doc:name="Request"
    config-ref="HTTP_Request_configuration"
    path="test"
     />
</flow>

OAuth2 認証コード許可種別認証を設定する

OAuth2 認証コードでは、OAuth 2.0 認証コード許可種別を設定します。OAuth 認証サーバーには、OAuth で保護されるリソースが保持されています。たとえば、GitHub API への API コールを OAuth を使用する GitHub サーバーで認証できます。

HTTP Connector では OAuth 2.0 のみがサポートされています。

次の例は、GitHub OAuth 認証サーバー上の保護されたリソースである GitHub ユーザーデータにアクセスする Mule アプリケーションを作成して、HTTP Request 操作の OAuth2 認証コード許可種別認証を設定する方法を示しています。この例では次の方法を説明します。

認証のセットアップ
Mule アプリケーションの作成
Mule アプリケーションの実行

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

Mule アプリケーションを作成する前に、次の図で、OAuth アクセストークンを取得してデータのトークンを返す手順を確認してください。

GitHub アクセスへの HTTP 要求をクライアントアプリケーションに送信します。
クライアントアプリケーションは要求を GitHub 認証サーバーにリダイレクトします。
GitHub はログイン情報を要求します。
ログインしてクライアントアプリケーションを認証します。
GitHub 認証サーバーはアクセストークンを返します。
クライアントアプリケーションは次の要求をリスンします。

アクセストークンを使用して保護されたユーザーデータを要求します。
ユーザーデータの要求をリダイレクトします。
クライアントアプリケーションは GitHub 認証サーバーからユーザーデータを取得します。
クライアントアプリケーションは次の要求をリスンします。

認証のセットアップ

認証をセットアップする手順は、次のとおりです。

クライアントアプリケーションを認証サーバーに登録します。
認証サーバーが Mule アプリケーションにクライアント ID とクライアントシークレットを割り当てます。アプリケーションは、このログイン情報を使用して認証サーバーに身元を証明します。登録時には、Mule アプリケーションホームページへの URL とアプリケーションコールバック URL も指定します。
GitHub にログインします。
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 アプリケーションを作成します。

Mule アプリケーションは、HTTP Listener ソース、HTTP Request 操作、およびプレーンテキストを JSON に変換する DataWeave Transform message コンポーネントで構成されます。HTTP Request 操作で、認証サーバーへのアクセスを設定します。Mule アプリケーションを作成する手順は、次のとおりです。

Studio の [Mule Palette (Mule パレット)] で、[HTTP] > [Listener] を選択します。
[Listener] を Studio キャンバスにドラッグします。
[Path (パス)] を / に設定します。
[Connector configuration (コネクタ設定)] 項目の横にあるプラス記号 (+) をクリックして、アプリケーション内のすべてのソースのインスタンスで使用できるグローバル要素を設定します。
[HTTP Listener config (HTTP リスナー設定)] ウィンドウで、次の項目を設定します。
- Protocol (プロトコル): HTTP (Default)
- Host (ホスト): All Interfaces [0.0.0.0] (default)
- Port (ポート): 8081
[HTTP] > [Request] 操作を [Listener] ソースの右にドラッグします。
Package Explorer ウィンドウを展開します。
Mule アプリケーションプロジェクトを展開します。
pom.xml ファイルを開きます。
<dependencies> セクションの最後で、</dependencies> ステートメントの前に次のステートメントを追加し、Request 操作の OAuth オプションを有効化します。
```
<dependency>
    <groupId>org.mule.modules</groupId>
    <artifactId>mule-oauth-module</artifactId>
    <version>1.1.8</version>
    <classifier>mule-plugin</classifier>
</dependency>
```
フローから HTTP の [Request] 操作を選択し、[Connector Configuration (コネクタ設定)] のプロパティエディターで、プラス記号 (+) をクリックします。
[Authentication (認証)] を [Authorization code grant type (認証コード許可種別)] に設定します。
次の必須項目を入力します。
- External callback url (外部コールバック URL): http://myapp.mycompany.com:8082/callback
  OAuth 認証サーバーはこの URL を使用して認証コードを Mule サーバーに提供します。これで、Mule サーバーはアクセストークンを取得できます。これは、ローカルのアドレスではなく、外部に表示できるコールバックアドレスである必要があります。
- Local authorization url (ローカル認証 URL): https://localhost:8082/login
  この URL により、アカウントに対してアプリケーションへのアクセスを認証して許可できます。
- Authorization url (認証 URL): https://github.com/login/oauth/authorize
  この URL により、Mule アプリケーションからのユーザー要求は GitHub 認証サーバーの認証 URL にリダイレクトされます。
- Client id (クライアント ID)
  アプリケーション登録時に GitHub から指定されたクライアント ID。
- Client Secret (クライアントシークレット)
  アプリケーション登録時に GitHub から指定されたクライアントシークレット。
- Token url (トークン URL): https://github.com/login/oauth/access_token
  Mule クライアントアプリケーションはトークンをトークン URL に送信します。
  
  さらに、次の省略可能な項目を設定できます。
- Local callback url (ローカルコールバック URL): http://localhost:8082/callback
  この URL は、GitHub にアプリケーションを登録したときに設定した External callback url (外部コールバック URL) の値と同じです。これは、リモートホストから External callback url (外部コールバック URL) に送信された要求を受信するために Mule が作成するサーバーの設定です。外部と内部のコールバック URL は同じです。一方の URL でランタイムでサーバーを作成し (内部)、もう一方の URL でインターネットでサーバーを参照できます (外部)。
- Response Access Token (応答アクセストークン): #[payload.access_token]
  この DataWeave 式は、アクセストークンを抽出します。
- Response Refresh Token (応答更新トークン): [payload.access_token]
  プロバイダーが更新トークンを送信する場合、更新トークンには [payload.refresh_token] のように DataWeave 式を使用します。ただし、この例では GitHub が実際に更新トークンを使用することはありません。
[OK] をクリックします。
Mule アプリケーションを保存します。

Mule クライアントアプリケーションを実行する

Mule クライアントアプリケーションを実行し、GitHub ユーザーデータを取得するには、アクセストークンの有効期限が切れる前に次の手順を実行します。

Package Explorer ウィンドウで、プロジェクト名を右クリックし、[Run As (別のユーザーとして実行)] > [Mule Application (Mule アプリケーション)] を選択します。

コンソールに Mule アプリケーションがデプロイされていることが表示されます。
ブラウザーで、ローカル認証 URL http://localhost:8082/login を入力して、 OAuth2 ダンスを開始します。

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

GitHub が、登録されたアプリケーションの実行を認証するように促します。
[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"`
    ...
}
```

OAuth2 認証コードを設定する XML の例

次のコードは、XML で OAuth2 認証コードを設定する方法を示しています。

<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">
    <http:authentication>
        <oauth:authorization-code-grant-type
        externalCallbackUrl="http://myapp.mycompany.com:8082/callback"
        localAuthorizationUrl="http://localhost:8082/login"
        authorizationUrl="https://github.com/login/oauth/authorize"
        clientId="CLIENT_ID"
        clientSecret="CLIENT_SECRET"
        tokenUrl="https://github.com/login/oauth/access_token" />
    </http:authentication>
</http:request-config>

OAuth2 認証スコープを設定する

OAuth のスコープはセキュリティロールに似ています。[Scopes (スコープ)] 項目で、認証サーバーで使用可能な OAuth スコープのカンマ区切りリストを定義して、OAuth2 認証コード許可種別のスコープを設定します。

Studio で、フローから HTTP の [Request] 操作を選択します。
グローバル要素を設定するために、[Connector configuration (コネクタ設定)] 項目の横にあるプラス記号 (+) をクリックします。
[Authentication (認証)] を [Authorization code grant type (認証コード許可種別)] に設定します。
[Scopes (スコープ)] を access_user_details, read_user_files に設定します。
[OK] をクリックします。

設定 XML エディターでは、scopes 設定は次のように記述されます。

<http:authentication>
    <oauth:authorization-code-grant-type
        localCallbackUrl="http://localhost:8082/redirectUrl"
        externalCallbackUrl="http://myapp.mycompany.com:8082/callback"
        localAuthorizationUrl="https://localhost:8082/authorization"
        authorizationUrl="https://www.box.com/api/oauth2/authorize"
        clientId="your_client_id"
        clientSecret="your_client_secret"
        tokenUrl="https://www.box.com/api/oauth2/token"
        tlsContextFactory="TLS_Context"
        scopes="access_user_details, read_user_files" />
</http:authentication>

OAuth2 認証のカスタムパラメーターを設定する

OAuth 実装で、OAuth 認証サーバー (OAS) の認証 URL をコールするときに、追加のクエリパラメーターの送信を要求または許可する場合があります。OAuth2 認証コード許可種別の次のパラメーターを [Custom parameters (カスタムパラメーター)] 項目で設定します。

Studio で、フローから HTTP の [Request] 操作を選択します。
グローバル要素を設定するために、[Connector configuration (コネクタ設定)] 項目の横にあるプラス記号 (+) をクリックします。
[Authentication (認証)] を [Authorization code grant type (認証コード許可種別)] に設定します。
次の項目を設定します。
- External callback url (外部コールバック URL): http://myapp.mycompany.com:8082/callback
- Local authorization url (ローカル認証 URL): http://localhost:8082/login
- Authorization url (認証 URL): https://github.com/login/oauth/authorize
- Client id (クライアント ID): GitHub アカウントのクライアント ID
- Client secret (クライアントシークレット): GitHub アカウントのクライアントシークレット
- Token url (トークン URL): https://github.com/login/oauth/access_token
[Custom parameters (カスタムパラメーター)] を [Edit inline (インライン編集)] に設定します。
プラス記号 (+) をクリックして、新しいカスタムパラメーターを追加します。
[Key (キー)] を box_device_id に、[Value (値)] を 123142 に設定します。
ステップ 6 を繰り返します。
[Key (キー)] を box_device_name に、[Value (値)] を my-phone に設定します。
[OK] をクリックします。

設定 XML エディターでは、oauth:custom-parameter 設定は次のように記述されます。

<http:request-config name="HTTP_Request_Configuration"
        host="api.box.com" port="443" basePath="/2.0">
    <http:authentication>
        <oauth:authorization-code-grant-type
        externalCallbackUrl="http://myapp.mycompany.com:8082/callback"
        localAuthorizationUrl="http://localhost:8082/login"
        authorizationUrl="https://github.com/login/oauth/authorize"
        clientId="CLIENT_ID"
        clientSecret="CLIENT_SECRET"
        tokenUrl="https://github.com/login/oauth/access_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>
    </http:authentication>
</http:request-config>

OAuth2 認証のリダイレクト URI を設定する

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

リダイレクト URI (外部 redirect_uri) を上書きするには、[External callback url (外部コールバック URL)] 項目で外部リダイレクト URI を設定します。これは、CloudHub にアプリケーションをデプロイするなどのアクションに役立ちます。認証を設定するときに、必要に応じて [Local callback url (ローカルコールバック URL)] 項目も設定できます。

CloudHub の場合、Mule はエンドポイントを次のような形式で作成する必要があります。

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

Mule に、正しい形式で CloudHub のエンドポイントを作成するように指示するには、OAuth2 認証コード許可種別設定に [External callback url (外部コールバック URL)] 項目を含めます。

OAuth2 認証のパラメーターの抽出を設定する

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

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

Response access token (応答アクセストークン)
JSON 項目が access_token。
Response refresh token (応答更新トークン)
JSON 項目が refresh_token。
Response expires in (応答有効期限)
JSON 項目が expires_in。

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

応答が JSON 形式ではない場合、最初にコネクタを設定して、これらの値の抽出方法がわかるようにする必要があります。

次の例では、HTTP Connector は応答の Content-Type が application/x-www-form-urlencoded であることを期待するため、応答の本文はペイロードのマッピングに変換されます。#[payload.access_token] (Response access token (応答アクセストークン) と Response refresh token (応答更新トークン) のデフォルト値) など、DataWeave 式を使用してマッピングから値を抽出します。

Studio で、フローから HTTP の [Request] 操作を選択し、[Connector Configuration (コネクタ設定)] のプロパティエディターで、プラス記号 (+) をクリックします。
[Authentication (認証)] を [Authorization code grant type (認証コード許可種別)] に設定します。
次の項目のデフォルトのオプションを確認します。
- Response access token (応答アクセストークン): #[payload.access_token]
- Response refresh token (応答更新トークン): #[payload.refresh_token]
- Response expires in (応答有効期限): #[payload.expires_in]

OAuth 認証の [Response access token (応答アクセストークン)] 項目、[Response refresh token (応答更新トークン)] 項目、[Response expires in (応答有効期限)] 項目の設定

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

設定 XML エディターでは、responseAccessToken、responseRefreshToken、および responseExpiresIn の設定は次のように記述されます。

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

OAuth2 認証の更新トークン条件を設定する

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

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

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

Studio で、フローから HTTP の [Request] 操作を選択し、[Connector Configuration (コネクタ設定)] のプロパティエディターで、プラス記号 (+) をクリックします。
[Authentication (認証)] を [Authorization code grant type (認証コード許可種別)] に設定します。
[Request Token When (要求トークン条件)] を [Expression (式)] に設定します。
式ボックスに次の DataWeave 式を追加します。 #[payload.response.status == 'unauthorized']

OAuth 認証の [Response Token When (応答トークン条件)] 項目の設定

設定 XML エディターでは、refreshTokenWhen 設定は次のように記述されます。

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

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

OAuth 認証の HTTPS を設定する

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

Local authorization url (ローカル認証 URL)
Authorization url (認証 URL)
Redirect url (リダイレクト URL)
Token url (トークン URL)

OAuth 認証コード許可種別の HTTPS を設定する手順は、次のとおりです。

Studio で、フローから HTTP の [Request] 操作を選択し、[Connector Configuration (コネクタ設定)] のプロパティエディターで、プラス記号 (+) をクリックします。
[TLS Configuration (TLS 設定)] を [Global Reference (グローバル参照)] に設定します。
項目の横にある緑のプラス記号 (+) をクリックして新規 TLS コンテキストを作成します。
[Trust Store Configuration (トラストストア設定)] で、次の項目を設定します。
- Path (パス): your_trust_store
- Password (パスワード): your_password
[Kye Store Configuration (キーストア設定)] で、次の項目を設定します。
- Path (パス): your_keystore_path
- Key Password (キーパスワード): your_key_password
- Password (パスワード): your_password

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

[Configuration XML (設定 XML)] エディターで、tls:context、tls:trust-store、および tls:key-store の設定は次のように記述されます。

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

OAuth2 クライアントログイン情報許可種別認証を設定する

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

HTTP Connector では OAuth 2.0 のみがサポートされています。

クライアントアプリケーション (CA) は、リソースオーナー (RO) に属する保護されたリソースへのアクセスを試みるサーバーです。たとえば、Box サーバーにある Box ユーザーに属するリソースへのアクセスを試みる Mule サーバーです。

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

次の図は、CA と OAS の関係を示しています。

保護されたリソースにアクセスする手順は、次のとおりです。

CA はアプリケーションを OAS サーバーに登録する必要があります。これが行われると、OAS がログイン情報を CA に割り当て、CA はそれを後で使用して身元証明に使用できます (client ID と client secret)。OAS は Token URL も提供する必要があります。CA は、後でこのトークン URL に HTTP 要求を送信し、保護されたリソースへのアクセス時に必要な access token を取得できます。
CA は、OAS の Token URL に対して、身元を証明するためのクライアント ID が含まれる要求を実行します。応答として、OAS は CA に access token を付与します。
このアクセストークンがあると、CA は、要求にアクセストークンが含まれている限り、OAS にある保護されたリソースに自由にアクセスできるようになります。OAS が定義したポリシーに応じて、トークンがそのうち期限切れになることがあります。

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

HTTP Request 操作の OAuth2 認証コード許可種別を設定するには、[Authentication (認証)] 項目を [Client credentials grant type (クライアントログイン情報許可種別)] に設定します。

Studio で、OAuth クライアントログイン情報許可種別を使用する [HTTP Request Configuration (HTTP 要求設定)] グローバル要素を選択します。
[Authentication (認証)] を [Client credentials grant type (クライアントログイン情報許可種別)] に設定します。
次の項目を設定します。
- Client id (クライアント ID)
  アプリケーション登録時に GitHub から指定されたクライアント ID。
- Client Secret (クライアントシークレット)
  アプリケーション登録時に GitHub から指定されたクライアントシークレット。
- Scopes (スコープ)
  OAuth のスコープはセキュリティロールに似ています。
- Token URL (トークン URL)
  Mule クライアントアプリケーションはトークンをトークン URL に送信します。

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

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

クライアントログイン情報許可種別認証を設定する XML

次のコードは、XML でクライアントログイン情報許可種別認証を設定する方法を示しています。

<http:request-config name="HTTP_Request_configuration" >
	<http:request-connection host="some.api.com" port="80" >
	<http:authentication>
		<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" />
	</http:authentication>
	</http:request-connection>
</http:request-config>

OAuth2 クライアントログイン情報のパラメーターの抽出を設定する

OAuth2 認証コード許可種別に適用される、トークン URL からパラメーターを抽出する動作は、クライアントログイン情報許可種別にも適用されます。

Studio で、フローから HTTP の [Request] 操作を選択し、[Connector Configuration (コネクタ設定)] のプロパティエディターで、プラス記号 (+) をクリックします。
[Authentication (認証)] を [Client credentials grant type (クライアントログイン情報許可種別)] に設定します。
次の項目のデフォルトのオプションを確認します。
- Response access token (応答アクセストークン): #[payload.access_token]
- Response refresh token (応答更新トークン): #[payload.refresh_token]
- Response expires in (応答有効期限): #[payload.expires_in]

クライアントログイン情報許可種別の [Response access token (応答アクセストークン)] 項目、[Response refresh token (応答更新トークン)] 項目、[Response expires in (応答有効期限)] 項目の設定

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

設定 XML エディターでは、responseAccessToken、responseRefreshToken、および responseExpiresIn の設定は次のように記述されます。

<http:request-config name="HTTP_Request_Configuration"
                   host="api.box.com" port="443" basePath="/2.0">
      <http:authentication>
          <oauth:client-credentials-grant-type
              clientId="CLIENT_ID"
          		clientSecret="CLIENT_SECRET"
          		tokenUrl="http://some.api.com/api/1.0/oauth/token"
          		scopes="access_user_details, read_user_files" />
      </http:authentication>
</http:request-config>

OAuth2 クライアントログイン情報の更新アクセストークン条件を設定する

OAuth2 認証コード許可種別に適用される、トークン URL からパラメーターを抽出する動作は、クライアントログイン情報許可種別にも適用されます。

Studio で、フローから HTTP の [Request] 操作を選択し、[Connector Configuration (コネクタ設定)] のプロパティエディターで、プラス記号 (+) をクリックします。
[Authentication (認証)] を [Client credentials grant type (クライアントログイン情報許可種別)] に設定します。
[Request Token When (要求トークン条件)] を [Expression (式)] に設定します。
式ボックスに次の DataWeave 式を追加します。 #[payload.response.status == 'unauthorized']

OAuth2 クライアントログイン情報許可種別の [Response Token When (応答トークン条件)] 項目の設定

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

設定 XML エディターでは、refreshTokenWhen 設定は次のように記述されます。

<http:request-config name="HTTP_Request_Configuration"
        host="api.box.com" port="443" basePath="/2.0">
    <http:authentication>
      <oauth:client-credentials-grant-type
          clientId="CLIENT_ID"
          clientSecret="CLIENT_SECRET"
          tokenUrl="http://some.api.com/api/1.0/oauth/token"
          scopes="access_user_details, read_user_files"
        refreshTokenWhen="#[payload.response.status == 'unauthorized']" />
    </http:authentication>
</http:request-config>

トークンマネージャーを設定する

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

Studio で、フローから HTTP の [Request] 操作を選択し、[Connector Configuration (コネクタ設定)] のプロパティエディターで、プラス記号 (+) をクリックします。
[Authentication (認証)] を [Authorization code grant type (認証コード許可種別)] に設定します。
[Token manager (トークンマネージャー)] を [Edit inline (インライン編集)] に設定します。
プラス記号 (+) をクリックして、オブジェクトストアを参照する新しい設定を作成します。

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

設定 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">
        <http:authentication>
            <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" />
        </http:authentication>
    </http:request-config>

トークンマネージャー - 認証へのアクセス

トークンマネージャーを認証許可種別に関連付けたら、OAuth Module の操作を Mule アプリケーションフロー内の任意の場所で使用して、OAuth 認証からの情報にアクセスできます。

1 つのリソースオーナーでクライアントログイン情報または認証コードを使用する場合、フローでは次の OAuth Module 操作を使用します。次の操作では、トークンマネージャーから OAuth 認証情報にアクセスできます。

<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 Module 操作を使用します。

<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 認証を管理する HTTP Reuqest 操作の後にこれらの OAuth Module 操作を配置します。

関数結果

関数	結果
`<oauth:retrieve-access-token tokenManager="tokenManagerConfig" target="accessToken"/>`	`accessToken` 値には、DataWeave から `vars.accessToken` を使用してアクセスできます。
`<oauth:retrieve-access-token tokenManager="tokenManagerConfig" resourceOwnerId="Peter" target="accessToken"/>`	ID `Peter` で識別されるリソースオーナーの `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" resourceOwnerId="Peter" key="a_custom_param_name" target="customParam"/>`	リソースオーナー `Peter` のトークン URL 応答から抽出されたカスタムパラメーターには、DataWeave から `vars.customParam` を使用してアクセスできます。

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

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

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

ID Peter で識別されるリソースオーナーの 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" resourceOwnerId="Peter" key="a_custom_param_name" target="customParam"/>

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

トークンマネージャーのアクセストークンの無効化を設定する

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

Studio で、OAuth Module の Invalidate oauth context 操作をフローにドラッグします。
プロパティエディターで、OAuth 認証の管理時に HTTP Request 操作が参照するものと同じトークンマネージャーを参照するようにトークンマネージャーを設定します。
[Resource owner Id (リソースオーナー ID)] を、クリアするリソースオーナーを参照する式に設定します (例: #[vars.resourceOwnerId])。

設定 XML エディターでは、invalidate-oauth-context 設定は次のように記述されます。

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

Invalidate oauth context 操作は、トークンマネージャー内に保存されているすべての OAuth 情報をすべて削除します。

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

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

トークンマネージャーのオブジェクトストアの設定

デフォルトでは、トークンマネージャーはメモリ内オブジェクトストアを使用してログイン情報を保存します。[Object store (オブジェクトストア)] 項目を使用して、トークンマネージャーのオブジェクトストアを設定できます。

オブジェクトストアについての詳細は、カスタムオブジェクトストアの設定に関するドキュメントを参照してください。

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

複数ユーザーの代理でリソースにアクセスする必要がある場合、HTTP Connector を使用する代わりに SDK Connector を OAuth Module と組み合わせて使用します。

ガートナーが MuleSoft をリーダーとして評価

Salesforce のフルパワーを解放する API 活用術

Anypoint Platform：開発基礎 (無料)

MuleSoft Forum Japan