Salesforce Docs Portal

HTTP 要求の認証

HTTP 要求に設定する認証を使用します。「​[OAuth2 - Authorization Code]​」で説明されている GitHub OAuth2 サーバーなど、認証を必要とするサービスに、Mule Runtime (Mule) アプリケーションで HTTP Connector を使用して要求を送信する場合、認証を使用できます。この場合、Mule アプリケーションがクライアントです。一方で、不正なアクセスからの要求を API やアプリケーションで受信しないようにするには、​外部プロバイダーを使用した OAuth 2.0 アクセストークンの適用​ポリシーなどの API Manager ポリシーを使用します。

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

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

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

Anypoint Studio の HTTP グローバル要素設定の [Authentication (認証)] ドロップダウンメニューに [Expression (式)] が表示されますが、これは認証方式ではないため、認証方式として使用しないでください。

HTTP XML 認証のセットアップ

Anypoint Studio (Studio) を使用している場合、HTTP Request Connector 用の ​[Authentication (認証)]​ 項目を使用して、認証種別を選択できます。

HTTP Connector の認証の 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>

また、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>

OAuth コンポーネントの操作の使用方法については、まず「​[Create the Mule Client App]​」を参照してください。

基本認証

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

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

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

GitHub API をコールするには、まず、次のように HTTP Listener Connector をセットアップします。

基本認証 - Studio ビジュアルエディター

  1. Studio で、​[File (ファイル)]​ > ​[New (新規)]​ > ​[Mule Project (Mule プロジェクト)]​ を選択し、次のパラメーターを設定して、新規 Mule プロジェクトを作成します。

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

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

  2. [Mule Palette (Mule パレット)] で、​[HTTP]​ を選択し、​[Listener]​ 操作をクリックしてキャンバスまでドラッグします。

  3. リスナーのプロパティエディターで ​[Path (パス)]​ を ​/​ (スラッシュ) に設定します。

  4. [Connector Configuration (コネクタ設定)]​ で緑色のプラスアイコンをクリックします。

    [HTTP Listener config (HTTP リスナー設定)]​ ダイアログが表示されます。

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

    • Name (名前)​: HTTP_Listener_config

    • Protocol (プロトコル)​: HTTP

    • Host (ホスト)​: 0.0.0.0

    • Port (ポート)​: 8081

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

  7. プロパティエディターで、​[Advanced (詳細)]​ タブをクリックし、​[Allowed Methods (許可されるメソッド)]​ を ​GET​ に設定します。

  8. 変更を保存します。

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

基本認証 - HTTP Request Connector の設定

  1. [HTTP]​ > ​[Request]​ 操作を [Mule Palette (Mule パレット)] から Studio フローの [Process (プロセス)] 領域にドラッグします。

  2. プロパティエディターの ​[Connector Configuration (コネクタ設定)]​ で、緑色のプラスアイコンをクリックします。

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

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

    • Name (名前)​: HTTP_Request_configuration​。

    • Protocol (プロトコル)​: HTTPS

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

    • Port (ポート)​: 443

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

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

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

  7. [Preemptive (プリエンプティブ)]​ チェックボックスを ​[True (Default) (True (デフォルト))]​ のままにします。

    プリエンプティブオプションでは、サーバーからの要求メッセージを待たずにユーザー名とパスワードが渡されます。

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

  9. プロパティエディターで、HTTP Request Connector の次のオプションを設定します。

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

    • Path (パス)​: /user

  10. 変更を保存します。

基本認証 - JSON 形式の出力の作成

  1. [Mule Palette (Mule パレット)] で、「transform」を検索し、​[Core (コア)] > [Transform Message]​ をパレットから Request コンポーネントの右にドラッグします。

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

    %dw 2.0
output application/json
---
payload

基本認証 - アプリケーションの実行

  1. Package Explorer​ でプロジェクト名を右クリックし、​[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"`
    ...
}

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

基本認証 - XML エディター

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

...
<http:listener-config name="HTTP_Listener_config"
   doc:name="HTTP Listener config" >
    <http:listener-connection
    host="0.0.0.0"
    port="8081" />
    </http:listener-config>
    <http:request-config name="HTTP_Request_configuration"
       doc:name="HTTP Request configuration" >
        <http:request-connection
        protocol="HTTPS"
        host="api.github.com"
        port="443" >
            <http:authentication >
                <http:basic-authentication username="kahn" password="PW" />
            </http:authentication>
        </http:request-connection>
    </http:request-config>
    <flow name="myprojectFlow" >
        <http:listener doc:name="Listener"
        config-ref="HTTP_Listener_config"
        path="/"
        allowedMethods="GET"/>
        <http:request method="GET" doc:name="Request"
        config-ref="HTTP_Request_configuration"
        path="/user" />
        <ee:transform doc:name="Transform Message" >
            <ee:message >
                <ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
payload
]]></ee:set-payload>
            </ee:message>
        </ee:transform>
    </flow>
</mule>

NTLM 認証

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

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

NTLM 認証 - Studio ビジュアルエディター

  1. [HTTP]​ > ​[Request]​ 操作を [Mule Palette (Mule パレット)] から Studio フローの [Process (プロセス)] 領域にドラッグします。この操作は HTTP Request Connector と呼ばれます。

  2. プロパティエディターの ​[Connector Configuration (コネクタ設定)]​ で、緑色のプラスアイコンをクリックします。

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

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

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

NTLM 認証 - XML エディター

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

<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="UN" password="PW" />
     </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>

ダイジェスト認証

  1. [HTTP]​ > ​[Request]​ 操作を [Mule Palette (Mule パレット)] から Studio フローの [Process (プロセス)] 領域にドラッグします。この操作は HTTP Request Connector と呼ばれます。

  2. プロパティエディターの ​[Connector Configuration (コネクタ設定)]​ で、緑色のプラスアイコンをクリックします。

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

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

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

ダイジェスト認証 - XML エディター

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

...
<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="UN"
              password="PW" />
        </http:authentication>
    </http:request-connection>
</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 アカウントが必要です。

認証のセットアップ

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

    authentication in http requests 75e03

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

  3. 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 Listener Connector、HTTP Request Connector、およびプレーンテキストを JSON に変換する DataWeave (Transform) コンポーネントで構成されます。HTTP Request Connector で、認証サーバーへのアクセスを設定します。

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

  • ​Local authorization URL (ローカル認証 URL)

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

  • Authorization URL (認証 URL)

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

  • Token URL (トークン URL)

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

以下のセクションでは、Mule クライアントアプリケーションに GitHub 認証サーバーへのアクセスを設定する手順について説明します。

OAuth 2 認証 - Studio ビジュアルエディター

  1. [HTTP]​ > ​[Request]​ 操作を [Mule Palette (Mule パレット)] から Studio フローの [Process (プロセス)] 領域にドラッグします。この操作は HTTP Request Connector と呼ばれます。

  2. [Package Explorer] を展開し、​pom.xml​ ファイルをダブルクリックします。

  3. <dependencies>​ セクションの最後で、​</dependencies>​ ステートメントの前に次のステートメントを追加し、HTTP Request Connector の OAuth オプションを有効化します。

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

  4. プロパティエディターの ​[Connector Configuration (コネクタ設定)]​ で、緑色のプラスアイコンをクリックします (または、設定をすでに作成している場合は [編集] アイコンをクリックします)。

  5. [Authentication (認証)]​ 項目を ​[Authorization code grant type (認証コード許可種別)]​ に設定します。

  6. 次の必須項目を入力します。

    • External callback url (外部コールバック URL)​: http://myapp.mycompany.com:8082/callback

      OAuth 認証サーバーはこの URL を使用して認証コードを Mule サーバーに提供します。これで、Mule サーバーはアクセストークンを取得できます。これは、ローカルのアドレスではなく、外部に表示できるコールバックアドレスである必要があります。

    • Local authorization url (ローカル認証 URL)​: https://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

      次の省略可能な項目も設定できます。

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

      この値は、GitHub にアプリケーションを登録したときに ​[External callback URL (外部コールバック URL)]​ に設定した値と同じです。これは、リモートホストから ​externalCallbackUrl​ に送信された要求を受信するために Mule が作成するサーバーの設定です。外部と内部のコールバック URL は同じです。一方は、ランタイムでサーバーを作成するための設定であり (内部)、もう一方はそのサーバーがインターネットでどのように表示されるかを示します (外部)。

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

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

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

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

      authentication in http requests c2070

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

  8. 変更を保存します。

OAuth 2 認証 - XML エディター

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

  • clientId​ と ​clientSecret​。

    アプリケーションの登録時に 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">
    <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>
localAuthorizationUrl​ 値は、GitHub にアプリケーションを登録したときに ​[External callback URL (外部コールバック URL)]​ に設定した値と同じです。これは、リモートホストから ​externalCallbackUrl​ に送信された要求を受信するために Mule が作成するサーバーの設定です。外部と内部のコールバック URL は同じです。一方は、ランタイムでサーバーを作成するための設定であり (内部)、もう一方はそのサーバーがインターネットでどのように表示されるかを示します (外部)。

OAuth 2 認証 - 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"`
    ...
}

OAuth 2 認証 - スコープの使用

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

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

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

OAuth 2 カスタムパラメーター - Studio ビジュアルエディター

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

  2. [Authentication (認証)]​ で ​[Authorization code grant type (認証コード許可種別)]​ を選択します。このオプションが表示されていない場合、OAuth オプションを有効にするように ​pom.xml ファイルを設定します​。

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

    • External Callback URL (外部コールバック URL) = ​http://myapp.mycompany.com:8082/callback

    • Local Authorization URL (ローカル認証 URL) = ​http://localhost:8082/login

    • AuthorizationUrl = ​https://github.com/login/oauth/authorize

    • client ID (クライアント ID) = GitHub アカウントからクライアント ID を取得します

    • client Secret (クライアントシークレット) = GitHub アカウントからクライアントシークレットを取得します

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

      Local Authorization URL​ 値は、GitHub にアプリケーションを登録したときに ​External callback URL​ に設定した値と同じです。これは、リモートホストから ​externalCallbackUrl​ に送信された要求を受信するために Mule が作成するサーバーの設定です。外部と内部のコールバック URL は同じです。一方は、ランタイムでサーバーを作成するための設定であり (内部)、もう一方はそのサーバーがインターネットでどのように表示されるかを示します (外部)。

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

OAuth 2 カスタムパラメーター - XML エディター

この例には、この API 固有のパラメーターを定義する 2 つの ​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>

リダイレクト URI の上書き

このセクションでは、リダイレクト URI (外部 ​redirect_uri​) を上書きできます。

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

[External Callback URL (外部コールバック URL)] 属性 (XML の ​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 要求は必要な情報の抽出方法を判断できます。

  • Response access token (応答アクセストークン)​: JSON 項目の名前が ​access_token

  • Response refresh token (応答更新トークン)​: JSON 項目の名前が ​refresh_token

  • Response expires in (応答有効期限)​: JSON 項目の名前が ​expires_in

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

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

パラメーターの抽出 - 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">
      <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>

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

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

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

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

更新 - Studio ビジュアルエディター

[Authentication (認証)]​ > ​[Authorization code grant type (認証コード許可種別)]​ で、​[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">
    <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 ログイン情報に適用します。

  • ローカル認証 URL

  • 認証 URL

  • リダイレクト URL

  • トークン URL

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

HTTPS - Studio ビジュアルエディター

  1. [TLS Configuration (TLS 設定)]​ 項目で、​[Global Reference (グローバル参照)]​ を選択します。

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

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

[TLS Configuration (TLS 設定)]​ 項目で、OAuth ログイン情報をエンコードします。

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

oauth:authorization-code-grant-type​ 要素の ​tlsContextFactory​ 属性は、OAuth ログイン情報をエンコードする ​<tls:context​ 要素を参照します。

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

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

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

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

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

oauth danceposta simple

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

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

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

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

OAuth2 - 設定

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

OAuth2 - Studio ビジュアルエディター

  1. Studio で、OAuth クライアントログイン情報許可種別を使用する [HTTP Request Configuration (HTTP 要求設定)] グローバル要素を選択します。

  2. [Authentication (認証)]​ で ​[Client credentials grant type (クライアントログイン情報許可種別)]​ を選択します。

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

    • [Client Id (クライアント ID)]​ および ​[Client Secret (クライアントシークレット)]​。アプリケーションの登録時に OAS から提供された値を使用します。

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

    • OAS が公開する ​[Token URL (トークン URL)]​。

OAuth2 - XML エディター

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

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

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

  • OAS が公開する ​tokenUrl​。

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

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

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

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

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

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

トークンマネージャー設定

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

トークンマネージャー設定 - Studio ビジュアルエディター

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

  2. [Authentication (認証)]​ で ​[Client credentials grant type (クライアントログイン情報許可種別)]​ を選択します。

  3. フォームの [Advanced (詳細)] セクションで、​[Token Manager (トークンマネージャー)]​ を ​[Global 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">
        <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 で提供される操作をフロー内の任意の場所で使用して、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 Request Connector の後にこれらの操作を配置して使用します。

関数 結果

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

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

<oauth:retrieve-access-token tokenManager="tokenManagerConfig" resourceOwnerId="Perter" 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="Perter" key="a_custom_param_name" target="customParam"/>

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

トークンマネージャー - アクセストークンの無効化

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

トークンマネージャー - Studio ビジュアルエディター

  1. OAuth コンポーネントの ​[Invalidate OAuth Context]​ 操作をキャンバスにドラッグします。

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

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

トークンマネージャー - XML エディター

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

OAuth コンポーネント​の Invalidate OAuth Context* 操作は、トークンマネージャー内に保存されているすべての OAuth 情報をクリーンアップします。

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

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

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

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

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

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

関連情報