コネクタの OAuth 2.0 の設定

多くのサービスで、OAuth 2.0 認証スキームを使用して、API を操作する場合のセキュリティを向上することができます。多くのコネクタで標準の OAuth 2.0 セットアップを設定することができます。

前提条件

コネクタの OAuth 2.0 を設定するには、次へのアクセス権が必要です。

  • OAuth プロバイダー (Okta、Azure AD、Google、PingFederate など)

  • Anypoint Studio

OAuth 2.0 設定項目

通常、コネクタの OAuth 2.0 では次の設定項目を使用できます。

OAuth 2.0 認証コード:

名前 説明 デフォルト値 必須

Consumer Key (コンシューマーキー)

String (文字列)

サービスプロバイダーに登録されている OAuth コンシューマーキー。

X

Consumer Secret (コンシューマーシークレット)

String (文字列)

サービスプロバイダーに登録されている OAuth コンシューマーシークレット。

X

Authorization URL (認証 URL)

String (文字列)

ユーザーがユーザーログイン情報を入力するためにリダイレクトされるサービスプロバイダーの認証エンドポイント。通常、この URL は ​/authorize​ で終わります。

X

Access Token Url (アクセストークン URL)

String (文字列)

アプリケーションにより自動的に認証コードがアクセストークンと交換される、サービスプロバイダーのアクセストークンエンドポイントの URL。

X

Scopes (スコープ)

String (文字列)

OAuth ダンス時に要求する OAuth スコープのスペース区切りリスト。この値のデフォルトはアノテーションのスコープです。

offline_access

Resource Owner ID (リソースオーナー ID)

String (文字列)

コネクタがリソースにアクセスすることを認証するリソースオーナーのアカウントの ID。

OAuth 2.0 コールバック設定:

名前 説明 デフォルト値 必須

Callback Path (コールバックパス)

String (文字列)

OAuth プロバイダーでユーザーが正常に認証された後、ユーザーのブラウザーがリダイレクトされるサーバーパス。通常、コールバックパスは ​/callback​ です。この設定では、​HTTP リスナー​セットアップを使用してコールバックパス (​http://0.0.0.0:{port}/callback​ など) を作成します。

X

Authorize Path (認証パス)

String (文字列)

ユーザーが OAuth ダンスを開始するサーバーパス。通常、認証パスは ​/authorize​ です。

X

External Callback Url (外部コールバック URL)

String (文字列)

OAuth プロバイダーで認証が正常に終了した場合にユーザーのブラウザーがリダイレクトされる、サーバー上の公開されている完全な URL。この項目で ​[Callback path (コールバックパス)]​ 項目を上書きすることができます (​http://my.server.com/callback​ など)。

OAuth 2.0 フロー概要

Anypoint Connector では、OAuth 2.0 ダンスには [Authorization Code Grant (認証コード許可)] フローが使用されます。次の手順は、コネクタの OAuth 2.0 を設定するための一般的なフローを示しています。

  1. ブラウザーで、OAuth ダンスを開始するために ​[Authorize Path (認証パス)]​ 項目で指定されたパスに移動します。たとえば、コネクタを ​localhost​ で実行しており、パスが ​/authorize​ に設定され、ポートが ​8080​ に設定されている場合、​http://localhost:8080/authorize​ に移動します。

  2. [Authorization URL (認証 URL)]​、​[Scopes (スコープ)]​、​[Resource Owner ID (リソースオーナー ID)]​、および ​[Callback Path (コールバックパス)]​ 項目の値を指定します。OAuth プロバイダーで認証要求を受け入れるには、次の条件が満たされている必要があります。

    • [Authorization URL (認証 URL)]​ にユーザーのブラウザーから到達できる。

    • [Scopes (スコープ)]​ で指定されたスコープがサポートされている。

    • [Resource Owner ID (リソースオーナー ID)]​ (指定されている場合) が OAuth プロバイダーに登録されている。

    • フル ​[Callback Path (コールバックパス)]​ が OAuth プロバイダーに登録されている。

  3. OAuth プロバイダーで受け入れられるユーザー名、パスワード、および他のログイン情報 (2FA 要求など) を入力します。認証が正常に終了したら、アプリケーションがアカウントにアクセスするための許可が OAuth プロバイダーにより求められる場合があります。通常、これは初めての認証時に求められます。

  4. OAuth プロバイダーでユーザーが認証され、コネクタへのアクセスが認証されたら、ユーザーの Web ブラウザーは、OAuth プロバイダーに登録されたコールバック URL (​http://localhost:8080/callback​ など) にリダイレクトされます。

    フローを実行しているユーザーにサーバーとエンドポイントへのアクセス権があることを確認します。ない場合、認証の承認がコネクタに到達しません。

    ローカルでのテストでは ​localhost​ を使用できますが、本番環境とクラウドデプロイメントでは ​localhost​ を使用できません。たとえば、コネクタアプリケーションが ​http://my.server.com​ で実行されている場合、​http://my.server.com/callback​ 値を使用して ​[External Callback Url (外部コールバック URL)]​ 項目を指定する必要があります。​http://my.server.com/callback​ URL も OAuth プロバイダーに登録する必要があります。

  5. ユーザーのブラウザーがコールバック URL に正常に到達した場合、コネクタは、​[Access Token URL (アクセストークン URL)]​ 項目で設定された URL を使用して、自動的にアクセストークンと交換される認証コードを取得します。このトークンの有効期間は長く、トークンはコネクタによって無期限に自動更新されます (OAuth プロバイダーで許可されている場合)。

コネクタが完全に認証されました。OAuth プロバイダーで発行された新しいアクセストークンを受け入れるすべてのサービスをコネクタで使用できます。

例: Gmail Connector の OAuth 2.0 の設定方法

次の例は、Gmail Connector の OAuth 2.0 を設定する方法を示しています。

OAuth プロバイダーの設定

Gmail Connector の OAuth プロバイダーを設定するには、Google Cloud コンソールを使用できます。次の手順は、OAuth プロバイダーを設定する方法を示しています。

Gmail API を以前に有効にしていない場合、新しいプロジェクトを作成し、​[Enabled APIs & Services (API とサービスを有効化)]​ メニューセクションで Gmail API を有効にする必要があります。
  1. 新しいクライアント (コネクタアプリケーション) を Google OAuth 2.0 に追加します。これを行うには、​[APIs & Services (API とサービス)] > [Credentials (ログイン情報)] > [Create Credentials (ログイン情報を作成)] > [OAuth Client ID (OAuth クライアント ID)]​ に移動します。

  2. [Web Application (Web アプリケーション)]​ 項目を使用して、新しい Web アプリケーションを作成します。

  3. 名前 (​OAuthDemoApp​ など) を入力します。

  4. [Authorized redirect URIs (認証済みリダイレクト URI)]​ 項目に​「\http://127.0.0.1:8080/callback」​の URL を入力します。

  5. [Create (作成)]​ をクリックし、後で使用する場合に備えて新しいクライアント ID とクライアントシークレットをコピーします。

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

コネクタの設定

Anypoint Studio または XML を使用して OAuth 2.0 でコネクタを設定します。

Anypoint Studio を使用したコネクタの設定

次の手順は、Anypoint Studio を使用して OAuth 2.0 でコネクタを設定する方法を示しています。

  1. Studio で Mule プロジェクトを作成します。

  2. [Mule Palette (Mule パレット)] ビューで、​[(X) Search in Exchange ((X) Exchange 内を検索)]​ をクリックします。

  3. [Add Dependencies to Project (連動関係をプロジェクトに追加)]​ で、検索項目に​「gmail」​と入力します。

  4. [Available modules (使用可能なモジュール)]​ で ​[Gmail Connector - Mule 4]​ をクリックします。

  5. [Add (追加)]​ をクリックします。

  6. [Finish (完了)]​ をクリックします。

  7. OAuth 2.0 認証コードを設定します。新しい Gmail Connector 接続を作成し、前のセクションのクライアント ID とクライアントシークレットをそれぞれ ​[Consumer Key (コンシューマーキー)]​ と ​[Consumer Secret (コンシューマーシークレット)]​ として使用します。​[Resource Owner ID (リソースオーナー ID)]​ 項目は空のままにすることができます。

    Gmail Connector の ​[Authorization URL (認証 URL)]​、​[Access Token URL (アクセストークン URL)]​、および ​[Scopes (スコープ)]​ 項目の値は事前入力されているため、これ以上のアクションは不要です。ただし、Okta や Ping などのサードパーティ OAuth プロバイダーを使用する別のコネクタをセットアップしている場合は、それぞれの ​[Authorization URL (認証 URL)]​、​[Access Token URL (アクセストークン URL)]​、および ​[Scopes (スコープ)]​ 項目を使用する必要があります。
    Gmail Connector 設定ウィンドウ
  8. OAuth 2.0 コールバック設定を定義します。新しい ​[HTTP Listener (HTTP リスナー)]​ をメッセージフローにドラッグし、​[Protocol (プロトコル)]​ を ​[HTTP (Default) (HTTP (デフォルト))]​ に設定し、​[Host (ホスト)]​ を ​[localhost]​ に設定し、​[Port (ポート)]​ を ​[8080]​ に設定します。

    HTTP リスナー設定ウィンドウ
  9. この ​HTTP リスナー​を Gmail Connector 接続設定で選択します。

  10. [Callback path (コールバックパス)]​ を ​[callback]​ に設定し、​[Authorize path (認証パス)]​ を ​[authorize]​ に設定します。​[External Callback Url (外部コールバック URL)]​ 項目は空のままにすることができます。

    Gmail OAuth 2.0 コールバック設定ウィンドウ
  11. アプリケーションを実行します。

XML を使用したコネクタの設定

次の手順は、XML を使用して OAuth 2.0 でコネクタを設定する方法を示しています。

  1. 次の連動関係を pom.xml に追加します。

    <dependency>
        <groupId>com.mulesoft.connectors</groupId>
        <artifactId>mule4-gmail-connector</artifactId>
        <version>1.0.5</version>
        <classifier>mule-plugin</classifier>
    </dependency>
  2. OAuth 2.0 認証コードを設定します。新しい Gmail Connector 接続を作成し、前のセクションのクライアント ID とクライアントシークレットをそれぞれ ​[Consumer Key (コンシューマーキー)]​ と ​[Consumer Secret (コンシューマーシークレット)]​ として使用します。​[Resource Owner ID (リソースオーナー ID)]​ 項目は空のままにすることができます。

    Gmail Connector の ​[Authorization URL (認証 URL)]​、​[Access Token URL (アクセストークン URL)]​、および ​[Scopes (スコープ)]​ 項目の値は事前入力されているため、これ以上のアクションは不要です。ただし、Okta や Ping などのサードパーティ OAuth プロバイダーを使用する別のコネクタをセットアップしている場合は、それぞれの ​[Authorization URL (認証 URL)]​、​[Access Token URL (アクセストークン URL)]​、および ​[Scopes (スコープ)]​ 項目を使用する必要があります。
    Gmail Connector 設定ウィンドウ
  3. OAuth 2.0 コールバック設定を定義します。新しい ​[HTTP Listener (HTTP リスナー)]​ 設定を作成し、​[Protocol (プロトコル)]​ を ​[HTTP (Default) (HTTP (デフォルト))]​ に設定し、​[Host (ホスト)]​ を ​[localhost]​ に設定し、​[Port (ポート)]​ を ​[8080]​ に設定します。

    この ​HTTP リスナー​の XML は次のようになります。

    <http:listener-config name="HTTP_Listener_config" >
    		<http:listener-connection host="localhost" port="8080" />
    </http:listener-config>
  4. この ​HTTP リスナー​を Gmail Connector 接続設定で選択します。

  5. [Callback path (コールバックパス)]​ を ​[callback]​ に設定し、​[Authorize path (認証パス)]​ を ​[authorize]​ に設定します。​[External Callback Url (外部コールバック URL)]​ 項目は空のままにすることができます。

    Gmail Connector の OAuth 2.0 コールバック設定の XML を次に示します。

    <gmail:config name="Gmail_Connector_Config" >
        <gmail:oauth2c-connection >
            <gmail:oauth-authorization-code consumerKey="YOUR_CLIENT_ID" consumerSecret="YOUR_CLIENT_SECRET" />
            <gmail:oauth-callback-config listenerConfig="HTTP_Listener_config" callbackPath="callback" authorizePath="authorize"/>
        </gmail:oauth2c-connection>
    </gmail:config>
  6. アプリケーションを実行します。

OAuth ダンスの実行

OAuth ダンスを実行し、アプリケーションがコネクタを介して Gmail アカウントにアクセスすることを認証します。次の手順は、OAuth ダンスを実行する方法を示しています。

  1. ブラウザーで、OAuth ダンスを開始するために ​[Authorize Path (認証パス)]​ 項目で指定されたパスに移動します。この例では、パスは ​http://localhost:8080/authorize​ です。すべてが正しく設定されたら、Google 認証画面が表示されます。ここで、ユーザーアカウントを選択し、アプリケーションがアカウントにアクセスすることを許可します。Google では、承認を必要とする権限のリストが表示されます。次に例を示します。

    Gmail でアカウントにアクセスする許可をユーザーに求めるウィンドウ
    この権限は、Gmail Connector 接続設定で定義された ​[Scopes (スコープ)]​ 項目によって異なります。デフォルトを受け入れることができますが、アクセス権を制限する必要がある場合は不要なスコープを削除することができます。たとえば、​https://www.googleapis.com/auth/gmail.send​ スコープを削除すると、コネクタでは新しいメールをアカウントから送信できなくなりますが、これにより、​Send Message​ や ​Send Draft​ 操作を使用する機能など、コネクタの機能が制限されます。
  2. [Allow (許可)]​ をクリックします。OAuth プロバイダーにより ​http://127.0.0.1:8080/callback​ にリダイレクトされます。これは、OAuth プロバイダーで設定したリダイレクト URI であり、コネクタ設定内で開かれます。OAuth ダンスが正常に終了したら、ブラウザーに ​[Successfully retrieved access token (アクセストークンを正常に取得しました)]​ というメッセージが表示されます。これは、コネクタが完全に認証され、コネクタで Gmail アカウントを使用する準備が整ったことを意味します。

    Anypoint Studio を再起動しない限り、またはアクセストークンが期限切れにならない限り、アプリケーションを再度認証する必要はありません。OAuth プロバイダーで更新トークンフローが有効になっている場合、アクセストークンが自動的に更新されます。Google ではこれが自動的にサポートされるため、トークンは無期限に更新されます。

    再起動しても認証を保持する必要がある場合、Gmail Connector 接続設定でオブジェクトストアを設定できます。

コネクタのテスト

コネクタが機能するようになり認証されました。これで、コネクタを使用してフローをテストできます。次の手順は、一部のメールを取得する方法を示しています。

  1. [HTTP Listener (HTTP リスナー)]​ をフローにドラッグします。​[Path (パス)]​ を ​/messages​ に設定します。

  2. [List Message]​ 操作をフローにドラッグします。必須項目は ​[User Id (ユーザー ID)]​ のみです。これには、アクセスするユーザーのメールアドレスが含まれます。たとえば、これは、1 つの会社アカウントの下で複数のユーザーが登録されている企業のメールサーバーで役立ちます。自分のメインアカウントからメールを直接取得するには、​[User Id (ユーザー ID)]​ を ​[me (自分)]​ に設定します。必要に応じて、​[Max Results (最大結果数)]​ を低い数に設定することもできます。

  3. プロジェクトを再起動します。

  4. http://localhost:8080/messages​ に移動します。メッセージ ID とスレッド ID の JSON 形式のリストが表示されます。​Get Message​ または ​Get Thread​ 操作を使用して、これらのメッセージまたはスレッドの詳細を取得できます。

この例の XML

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

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

<mule xmlns:gmail="http://www.mulesoft.org/schema/mule/gmail" 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/gmail http://www.mulesoft.org/schema/mule/gmail/current/mule-gmail.xsd">
	<http:listener-config name="HTTP_Listener_config" >
		<http:listener-connection host="localhost" port="8080" />
	</http:listener-config>
	<gmail:config name="Gmail_Connector_Config">
		<gmail:oauth2c-connection >
			<gmail:oauth-authorization-code consumerKey="300484156412-lnrscnoef6d4tbla0itv4b7pej0dpr3j.apps.googleusercontent.com" consumerSecret="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" scopes="https://mail.google.com/ https://www.googleapis.com/auth/gmail.addons.current.action.compose https://www.googleapis.com/auth/gmail.addons.current.message.action https://www.googleapis.com/auth/gmail.addons.current.message.readonly https://www.googleapis.com/auth/gmail.compose https://www.googleapis.com/auth/gmail.insert https://www.googleapis.com/auth/gmail.labels https://www.googleapis.com/auth/gmail.modify https://www.googleapis.com/auth/gmail.readonly"/>
			<gmail:oauth-callback-config listenerConfig="HTTP_Listener_config" callbackPath="callback" authorizePath="authorize"/>
		</gmail:oauth2c-connection>
	</gmail:config>

	<flow name="oauthFlow" >
		<http:listener config-ref="HTTP_Listener_config" path="/messages"/>
		<gmail:gmailusersmessageslist config-ref="Gmail_Connector_Config" userIdUriParam="me" maxResultsQueryParam="5"/>
	</flow>
</mule>