OAuth 対応コネクタまたはモジュールの設定

ユーザーが OAuth 対応コネクタやモジュールをどのように使用できるかも重要です。SDK は OAuth プロトコルの複雑さを可能な限り隠しますが、OAuth ダンスなどは隠せません。この問題に対して SDK は、すべての OAuth Module の使用方法を標準化して、ユーザーエクスペリエンスを簡素化することに努めています。

このセクションでは、ユーザーがモジュールを使用するための手順について説明します。

合成パラメーター

接続プロバイダーで明示的に定義されているすべての設定に加えて、SDK はいくつかのパラメーターを追加して、適切な動作を挿入します。

パラメーター名必須式デフォルト値説明

パラメーター名	必須	式	デフォルト値	説明
`resourceOwnerId`	いいえ	SUPPORTED	なし	ユーザーは、関連付けられているアクセストークンと更新トークンを所有するテナントの ID を指定することでマルチテナントをサポートできます。認証ダンスを実行すると、この値によって取得されているトークンの ID が提供されます。コンポーネントで新しい接続が必要な場合は、使用するデフォルトのオーナー ID として使用されます。
`consumerKey`	はい	NOT_SUPPORTED	なし	サービスプロバイダーに登録されている OAuth `consumerKey`。
`consumerSecret`	はい	NOT_SUPPORTED	なし	サービスプロバイダーに登録されている OAuth `consumerSecret`。
`authorizationUrl`	いいえ	NOT_SUPPORTED	`@AuthorizationCode アノテーションで提供されている値。	サービスプロバイダーの認証 URL。
`accessTokenUrl`	いいえ	NOT_SUPPORTED	`@AuthorizationCode` アノテーションで提供されている値。	サービスプロバイダーのアクセストークン URL。
`state`	いいえ	REQUIRED	なし	OAuth ダンスの開始時に送信し、トークンコールバックによってサービスプロバイダーから返される文字列値。ダンスの開始とトークンのコールバックを相関させるために使用します。この属性の最も一般的なユースケースはマルチテナントです。
`scope`	いいえ	NOT_SUPPORTED	`@AuthorizationCode` アノテーションで提供されている値。	OAuth ダンス時に要求する OAuth スコープ。指定しない場合、デフォルトのアノテーションの範囲になります。
`listenerConfig`	はい	NOT_SUPPORTED	なし	アクセストークンコールバックエンドポイントをキャッチするリスナーの作成に使用する `<http:listener-config />` への参照。
`callbackPath`	はい	NOT_SUPPORTED	なし	アクセストークンコールバックエンドポイントのパス。
`authorizePath`	はい	NOT_SUPPORTED	なし	OAuth ダンスをトリガーするローカル HTTP エンドポイントのパス。
`externalCallbackUrl`	いいえ	NOT_SUPPORTED	なし	コールバックエンドポイントがプロキシの背後にあるか、直接 URL 以外でアクセスする必要がある場合、このパラメーターを使用して OAuth プロバイダーに、コールバックへのアクセスに使用すべき URL を指示します。
`resourceOwnerId`	YES	SUPPORTED	なし	各コンポーネントが他を参照しない場合に使用する必要がある `resourceOwnerId`。
`objectStore`	いいえ	NOT_SUPPORTED	なし	各リソースオーナー ID のデータの保存に使用するオブジェクトストアへの参照。指定しない場合、Runtime は自動的にデフォルトのオブジェクトストアをプロビジョニングします。
`before`	いいえ	NOT_SUPPORTED	なし	OAuth ダンスを開始する直前に実行するフローの名前 (事前フローを参照)。
`after`	いいえ	NOT_SUPPORTED	なし	`accessToken` が受信された直後に実行するフローの名前 (事後フローを参照)。

resourceOwnerId

いいえ

SUPPORTED

なし

ユーザーは、関連付けられているアクセストークンと更新トークンを所有するテナントの ID を指定することでマルチテナントをサポートできます。認証ダンスを実行すると、この値によって取得されているトークンの ID が提供されます。コンポーネントで新しい接続が必要な場合は、使用するデフォルトのオーナー ID として使用されます。

consumerKey

はい

NOT_SUPPORTED

なし

サービスプロバイダーに登録されている OAuth consumerKey。

consumerSecret

はい

NOT_SUPPORTED

なし

サービスプロバイダーに登録されている OAuth consumerSecret。

authorizationUrl

いいえ

NOT_SUPPORTED

`@AuthorizationCode アノテーションで提供されている値。

サービスプロバイダーの認証 URL。

accessTokenUrl

いいえ

NOT_SUPPORTED

@AuthorizationCode アノテーションで提供されている値。

サービスプロバイダーのアクセストークン URL。

state

いいえ

REQUIRED

なし

OAuth ダンスの開始時に送信し、トークンコールバックによってサービスプロバイダーから返される文字列値。ダンスの開始とトークンのコールバックを相関させるために使用します。この属性の最も一般的なユースケースはマルチテナントです。

scope

いいえ

NOT_SUPPORTED

@AuthorizationCode アノテーションで提供されている値。

OAuth ダンス時に要求する OAuth スコープ。指定しない場合、デフォルトのアノテーションの範囲になります。

listenerConfig

はい

NOT_SUPPORTED

なし

アクセストークンコールバックエンドポイントをキャッチするリスナーの作成に使用する <http:listener-config /> への参照。

callbackPath

はい

NOT_SUPPORTED

なし

アクセストークンコールバックエンドポイントのパス。

authorizePath

はい

NOT_SUPPORTED

なし

OAuth ダンスをトリガーするローカル HTTP エンドポイントのパス。

externalCallbackUrl

いいえ

NOT_SUPPORTED

なし

コールバックエンドポイントがプロキシの背後にあるか、直接 URL 以外でアクセスする必要がある場合、このパラメーターを使用して OAuth プロバイダーに、コールバックへのアクセスに使用すべき URL を指示します。

resourceOwnerId

YES

SUPPORTED

なし

各コンポーネントが他を参照しない場合に使用する必要がある resourceOwnerId。

objectStore

いいえ

NOT_SUPPORTED

なし

各リソースオーナー ID のデータの保存に使用するオブジェクトストアへの参照。指定しない場合、Runtime は自動的にデフォルトのオブジェクトストアをプロビジョニングします。

before

いいえ

NOT_SUPPORTED

なし

OAuth ダンスを開始する直前に実行するフローの名前 (事前フローを参照)。

after

いいえ

NOT_SUPPORTED

なし

accessToken が受信された直後に実行するフローの名前 (事後フローを参照)。

式の使用について

上記の表には、式を受け入れる多くの合成パラメーターが示されています。式を使用することで、通常のパラメーターで式を使用するのと同じ効果が得られ、動的なパラメーター設定を可能にします。

OAuth 接続 DSL

生成される DSL は次のようになります。

<sfdc:config name="salesforce">
    <sfdc:oauth-connection display="PAGE" immediate="FALSE" prompt="CONSENT">
        <sfdc:oauth-authorization-code consumerKey="${sfdc.consumerkey}" consumerSecret="${sfdc.consumersecret}" authorizationUrl="http://..."
accessTokenUrl="http://..."/
localAuthorizationUrl="http://localhost:8080/.." scope="this that and those" resourceOwnerId="#[ownerId]"
before="myBeforeFlow" after="myAfterFlow" />
        <sfdc:oauth-callback-config listenerConfig="myHttpListener" callbackPath="/callback" authorizePath="/authorize" />
        <sfdc:oauth-store-config objectStore="oauthObjectStore" />
</sfdc:config>

他のすべてのプロバイダーと同様に、通常パラメーターと OAuth パラメーターはすべて接続プロバイダーレベルで示されています。
認証コード許可種別に関連したパラメーター (consumerKey、consumerSecret、authorizationUrl、accessTokenUrl、localAuthorizationHost、localAuthorizationPort、localAuthorizationPath、before、after、scope、defaultResourceOwnerId) は、<oauth-authorization-code> という子要素に配置されます。
コールバックに関連したパラメーターは、<oauth-callback-config> という子要素に配置されます。
オブジェクトストアに関連したパラメーターは、<oauth-store-config> という子要素に配置されます。

ダンス前後のカスタムロジック

OAuth ダンスを開始する直前やダンスが完了した直後に、エンドユーザーが何らかのランダムロジックを実行する必要が生じることがよくあります。たとえば、指定されたオーナー ID が正常にオンボードされたことを外部システムに通知したり、活動ログを保存したり、といったユースケースです。

認証プロセスは、自動的に作成されるエンドポイントをヒットすることでトリガーされるため、<oauth-authorization-code> 子要素には before パラメーターと after パラメーターがあります。

これらの省略可能なパラメーターは、OAuth ダンスの前または後に呼び出す <flow> の名前を指定します。

事前フロー

事前フローは、OAuth ダンスが開始される直前に実行されます。フローに送信されるイベントのペイロードは、AuthorizationCodeRequest のインスタンスであり、次のような不変の POJO となります。

public interface AuthCodeRequest {

  /**
   * @return The id of the user being authenticated
   */
  String getResourceOwnerId();

  /**
   * @return The scopes that were requested
   */
  Optional<String> getScopes();

  /**
   * @return The OAuth state that was sent
   */
  Optional<String> getState();

  /**
   * @return The external callback url that the user configured or {@link Optional#empty()} if none was provided
   */
  Optional<String> getExternalCallbackUrl();
}

ユーザーは、必要に応じてカスタムロジックをこのフローで自由に実行できます。特に、フロー変数を設定するのに便利です (「事後フロー」参照)。

事後フロー

事後フローは、アクセストークンを受け取って格納した直後に実行されます。このフローは、事前フローの結果に相当するイベント (事前フローが定義されていない場合は空のイベント) で実行されますが、ペイロードは ConnectionProvider に挿入されたのと同じ AuthorizationCodeState オブジェクトに置換されます。ただし、設定されている変数はそのまま残ります (事前フローが定義されていない場合は空になる)。

カスタム ObjectStore の設定

取得したアクセストークンは ObjectStore に保存されます。デフォルトでは、SDK はトークンをアプリケーションのデフォルトストアに保存しますが、ユーザーは次のようにカスタムオブジェクトストアを定義することもできます。

<os:object-store name="tokenStore" (1)
   entryTtl="1"
   entryTtlUnit="HOURS"
   maxEntries="100"
   persistent="true"
   expirationInterval="30"
   expirationIntervalUnit="MINUTES" />

<sfdc:config name="salesforce">
    <sfdc:oauth-connection display="PAGE" immediate="FALSE" prompt="CONSENT">
        <sfdc:oauth-authorization-code consumerKey="${sfdc.consumerkey}" consumerSecret="${sfdc.consumersecret}"
        authorizationUrl="http://..." accessTokenUrl="http://..."/
        localAuthorizationUrl="http://localhost:8080/.." />
        <sfdc:oauth-callback-config listenerConfig="myHttpListener" callbackPath="/callback" authorizePath="/authorize" />
        <sfdc:oauth-store-config objectStore="tokenStore" /> (2)
</sfdc:config>

1	カスタムストアを定義します。
2	モジュールの設定からそのストアを参照します。

次のステップ

OAuth 対応コネクタまたはモジュールでの OAuth ダンスの実行