OAuth V2

DevKit は、Studio 6 および Mule 3 とのみ互換性があります。Mule 4 Connector を作成するには、「Mule SDK」ドキュメントを参照してください。

このページでは、DevKit による OAuth V2 認証について詳しく説明し、API に対する認証に OAuth V2 を使用するコネクタを実装する方法について説明します。

前提条件

このドキュメントでは、読者が Anypoint Connector の基礎に精通していて、コネクタで認証を実装する準備ができていることを前提としています。読者がさまざまな認証方法に精通していて、API に対する認証に OAuth V1 を使用している可能性があることを想定しています。

OAuth V1 認証の概要や仕組みに精通していない場合、「OAuth 1.0 protocol/RFC-5849 (OAuth 1.0 プロトコル/RFC-5849)」を参照することをお勧めします。「OAuth V1」も参照してください。

必要な API 情報

サービスプロバイダの API ドキュメントから、以下の表で示している変数の正確な値を取得します。これらの変数は、認証プロセス中に使用される URL を参照します。このプロセスのステップについての詳細は、「OAuth 2 specification (OAuth 2 の仕様)」を参照してください。

変数説明

変数	説明
`accessTokenUrl`	アクセストークンを取得するための URL
`authorizationUrl`	リソースアクセスへの認証を取得するための URL

accessTokenUrl

アクセストークンを取得するための URL

authorizationUrl

リソースアクセスへの認証を取得するための URL

@OAuth2 アノテーション

コネクタで OAuth V2 認証を実装するには、@Config を新規作成する必要があります。クラスを新規作成して、@OAuth2 アノテーションを付加します。

ビルドプロセス中に、@OAuth2 アノテーションが付加されたコネクタは authorize および unauthorize という名前の自動生成された 2 つの @Processor メソッドを取得します。これらのメッセージプロセッサは、OAuth セッションの開始と終了を行います。

次の表で @OAuth2 アノテーションのすべてのパラメータについて説明します。

パラメータ Description (説明) 必須かどうか デフォルト値

パラメータ	Description (説明)	必須かどうか	デフォルト値
`friendlyName`	コネクタ設定ポップアップに表示される名前を定義します。	✓
`configElementName`	Mule アプリケーションで使用する設定の名前を定義します。		`config`
`accessTokenUrl`	アクセストークンを取得するためにサービスプロバイダによって定義される URL。	✓
`authorizationUrl`	サービスプロバイダによって定義される URL で、リソースオーナーはコンシューマに認証を許可するためにこの URL にリダイレクトされます。`config` 要素で異なる値を設定してプロセッサを設定すれば、この値を上書きできます。フローを作成するときに、`authorize` 要素で目的の値を入力すればこの値を上書きできます。	✓
`authorizationParameters`	次の形式でのアノテーションのカンマ区切りリスト。 `@OAuthAuthorizationParameter(name = "xxx", type = xxx, description = "xxx", optional = true)` 種別はコレクションまたは複合種別にはできません。
`verifierRegex`	リソースオーナーがコンシューマを認証した後で、サービスプロバイダの応答からベリファイアを抽出するための Java 正規表現。		`code=([^&]+)`
`accessTokenRegex`	サービスプロバイダの応答からアクセストークンを抽出するための Java 正規表現。		`"access_token":"([^&]+?)"`
`expirationRegex`	サービスプロバイダの応答からアクセストークンの有効期限 (秒) を抽出するための Java 正規表現。この正規表現がサービスプロバイダの応答で見つからない場合 (正規表現が間違っているかアクセストークンが期限切れにならないため)、アクセストークンは期限切れにならないものとして処理されます。		`"expires_in":([^&]+?),`
`refreshTokenRegex`	認証フロー中にコールバックから更新トークンを抽出するための Java 正規表現。		`"\"refresh_token\":\"([^&]+?)\""`
`callbackPath`	サービスプロバイダが受け入れるのが既知のリダイレクト URL のみの場合、このパラメータを、リダイレクト URL としてサービスプロバイダに登録されるドメイン (`fullDomain` 環境変数で示される) 内のパスに割り当てます。空のままにした場合 (つまり、サービスプロバイダがリダイレクト URL として任意の URL を受け入れる場合)、Mule はランダムなパスを使用します。		`<random path>`

friendlyName

コネクタ設定ポップアップに表示される名前を定義します。

✓

configElementName

Mule アプリケーションで使用する設定の名前を定義します。

config

accessTokenUrl

アクセストークンを取得するためにサービスプロバイダによって定義される URL。

✓

authorizationUrl

サービスプロバイダによって定義される URL で、リソースオーナーはコンシューマに認証を許可するためにこの URL にリダイレクトされます。config 要素で異なる値を設定してプロセッサを設定すれば、この値を上書きできます。フローを作成するときに、authorize 要素で目的の値を入力すればこの値を上書きできます。

✓

authorizationParameters

次の形式でのアノテーションのカンマ区切りリスト。

@OAuthAuthorizationParameter(name = "xxx", type = xxx, description = "xxx", optional = true)

種別はコレクションまたは複合種別にはできません。

verifierRegex

リソースオーナーがコンシューマを認証した後で、サービスプロバイダの応答からベリファイアを抽出するための Java 正規表現。

code=([^&]+)

accessTokenRegex

サービスプロバイダの応答からアクセストークンを抽出するための Java 正規表現。

"access_token":"([^&]+?)"

expirationRegex

サービスプロバイダの応答からアクセストークンの有効期限 (秒) を抽出するための Java 正規表現。この正規表現がサービスプロバイダの応答で見つからない場合 (正規表現が間違っているかアクセストークンが期限切れにならないため)、アクセストークンは期限切れにならないものとして処理されます。

"expires_in":([^&]+?),

refreshTokenRegex

認証フロー中にコールバックから更新トークンを抽出するための Java 正規表現。

"\"refresh_token\":\"([^&]+?)\""

callbackPath

サービスプロバイダが受け入れるのが既知のリダイレクト URL のみの場合、このパラメータを、リダイレクト URL としてサービスプロバイダに登録されるドメイン (fullDomain 環境変数で示される) 内のパスに割り当てます。空のままにした場合 (つまり、サービスプロバイダがリダイレクト URL として任意の URL を受け入れる場合)、Mule はランダムなパスを使用します。

<random path>

@Connector への @OAuth2 の追加

コネクタに OAuth V2 を追加する手順は、次のとおりです。

接続戦略を作成します。

@Connector(name = "oauth2connector")
public class MyConnector
{
    @ConnectionStrategy
    private OAuth2Strategy strategy;

    /**
    * YOUR CODE GOES HERE
    */
}

OAuth アクセス URL、アクセストークン URL、OAuth 戦略を追加します。

@OAuth2(authorizationUrl = "http://someUrl", accessTokenUrl = "http://someOtherUrl")
public class OAuth2Strategy
{
    /**
     * The OAuth2 consumer key
     */
    @Configurable
    @OAuthConsumerKey
    private String consumerKey;

    /**
     * The OAuth2 consumer secret
     */
    @Configurable
    @OAuthConsumerSecret
    private String consumerSecret;

    /**
    * YOUR CODE GOES HERE
    */
}

@OAuth2 クラスのプロパティ

上記のようにユーザがコネクタを使用するときに非公開コンシューマキーおよびシークレットを指定できるようにするには、戦略クラスで @Configurable インスタンスプロパティが必要です。

OAuth コンシューマキーを保持するための @OAuthConsumerKey
OAuth コンシューマシークレットを保持するための @OAuthConsumerSecret

これらのインスタンス変数に public getter および setter (非表示) があることを確認してください。

@Processor メソッドのアノテーション

保護されたリソース (@Processor アノテーションが付加されている) にアクセスするメソッドでは、String (文字列) パラメータを 1 つ追加して @OAuthAccessToken アノテーションを付加します。

@Processor
public Object accessProtectedResource(@OAuthAccessToken String accessToken, ...)
{
    /**
    * YOUR PROCESSOR CODE GOES HERE
    */
}

@OAuthAccessToken アノテーションが付加されたパラメータが含まれるメソッドが呼び出されると、次のアクティビティが開始されます。

保護されたリソースに初めてアクセスするときに、ユーザは保護されたリソースへのコンシューマのアクセス権を許可または拒否するためにサービスプロバイダの認証 URL にリダイレクトされます。
以降のアクセス要求中に、Mule はアクセストークン (@OAuthAccessToken アノテーションが付加されたパラメータ内に含まれる) をサービスプロバイダへの要求に含めます。詳細は、「Oauth 2.0 specification (Oauth 2.0 の仕様)」を参照してください。

アクセストークンの有効期限

適切な正規表現 (@OAuth2 アノテーションに expirationRegex パラメータを使用) を指定していて、API のアクセストークンの有効期限が切れた場合、Anypoint DevKit は自動的に有効期限を検出し、有効期限が切れると、再度 OAuth2 認証フローをトリガします。

クライアントクラスの変更: アクセストークンの引き渡し

Anypoint DevKit での OAuth V2 のサポートにより、@Connector で OAuth2 がサポートされます。ただし、場合によってはクライアントクラスに実際に Web サービスをコールするときに要求と一緒にアクセストークンを渡すロジックを含める必要があります。OAuth2 は正式で厳格な規格ではないため、要求と一緒にアクセストークンが渡される方法の詳細は API の実装によって異なります。

API プロバイダでは、トークンをサービスに渡す方法を示したサンプルコードが用意されています。クライアントクラスを実装するときは、API プロバイダのサンプルコードを参照用に使用してください。

たとえば、サービスで OAuth 2.0 認証をサポートしており、クライアントがクエリパラメータとしてアクセストークンを渡すことを想定しているとします。次の例は、Devkit を使用してこれを実行する方法を示しています。

コネクタはパラメータとして accessToken をクライアントクラスの操作 client.usersGetList() に渡します。

@OAuthProtected
@Processor
public UsersListResponse usersGetList(
    @Optional @Default("self") String userId,
    @Optional @Default("") String group,
    @Optional @Default("") String location)
  throws Oauth2ConnectorExampleTokenExpiredException,
         Oauth2ConnectorExampleException {
        return client.usersGetList(accessToken, userId, group, location);
    }

他にもクライアントレベルで同様の変更が必要なサービスがありますが、トークンをヘッダーとして送信するなど、細部に違いがあります。また、この例では Jersey クライアントを使用した RESTful Web サービスでの OAuth 2 の使用を示しています。SOAP ベースの Web サービスでは、クライアントクラスの変更は似ているものの、細部が異なります。

OAuth2 認証済みコネクタの使用

コネクタの認証

リソースオーナーが保護されたリソースへのアクセス権をコネクタに付与しないと、コンシューマは認証を必要とする操作を実行できません。認証要求を受信すると、Mule はリソースオーナーのブラウザをサービスプロバイダの認証ページにリダイレクトします。それ以降、保護されたリソースにアクセスしようとすると、@OAuthAccessToken アノテーションが付加されたパラメータが入力されます。Mule はアクセストークンをサービスプロバイダへの要求に含めます。

<connector:config-oauth name="oauth2" consumerKey="[ckey]" consumerSecret="[csec]"/>
...
<flow name="authorize">
  <http:listener config-ref="config" path="/authorize">
  <connector:authorize config-ref="oauth2"/>
</flow>

コネクタの設定

サービスプロバイダから指定されたようにアプリケーションの apiKey コンシューマキーおよび apiSecret コンシューマシークレットを渡して、コネクタを設定します。

...
<oauth2module:config apiKey="${api.key}" apiSecret="${api.secret}"/>
...

コールバックのカスタマイズ

ユーザが保護されたリソースへのアクセス権を付与した場合、サービスプロバイダは HTTP コールバックを行います。

このコールバックでは、認証コードが渡されます。Mule は後でこれを使用してアクセストークンを取得します。コールバックを処理するために、Mule は動的に HTTP インバウンドエンドポイントを作成し、続いてエンドポイントの URL をサービスプロバイダに渡します。そのため、HTTP コールバックを行うために特定の設定を行う必要はありません。

デフォルトでは、Mule はホストおよびポート (fullDomain 環境変数および http.port によって決定される) を使用してサービスプロバイダに送信する URL を構築します。ホストおよびポートにデフォルト以外の値を使用する必要がある場合は、設定を追加します。

<connector:config-oauth name="oauth2" consumerKey="[ckey]" consumerSecret="[csec]">
  <connector:oauth-callback-config domain="SOME_DOMAIN" localPort="SOME_PORT" path="SOME_PATH"/>
</connector:config-oauth>

Secure Socket Layer (SSL) の追加

Mule が OAuth コールバックを処理するために HTTP リスナ要求を自動的に起動する場合、デフォルトでは HTTP Connector を使用します。サービスプロバイダが HTTPS を必要とする場合、独自の HTTPS Connector を渡すように Mule を設定できます。

...
<http:listener-config name="configuration" protocol="HTTPS"
  host="localhost" port="8081">
  <https:tls-key-store path="keystore.jks" keyPassword="mule2015"
    storePassword="mule2015"/>
</http:listener-config>
...
<connector:config-oauth name="oauth2" apiKey="${api.key}" apiSecret="${api.secret}">
  <connector:oauth-callback-config domain="localhost" localPort="${http.port}" remotePort="${http.port}" async="true" connector-ref="httpsConnector"/>
</connector:config-oauth>
...

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

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

Anypoint Platform：開発基礎 (無料)

MuleSoft Forum Japan