はじめに
iPaaSであるWorkatoには、標準でBoxコネクタが用意されています。しかし、標準コネクタは主に OAuth 2.0（ユーザーコンテキスト） を前提としており、以下のケースで制約が生じることがあります。
- サービスアカウント（App Users）として、特定の個人に依存せず自動化したい
- 管理者が任意のユーザーの代理として操作したい（As-User機能の柔軟な利用）
本記事では、WorkatoのConnector SDKを使用して、「OAuth2.0」と「サーバー認証(JWT)」を設定画面で選択に応じて切り替え可能にする実装パターンを紹介します。
| 比較項目 | OAuth2.0 | サーバー認証(JWT) |
|---|---|---|
| 接続の安定性 | 不安定。ユーザーのパスワード変更で切れる可能性あり。 | 安定。鍵を更新しない限り有効。 |
| 退職リスク | あり。接続した個人に依存する。 | なし。システムアカウントとして自立。 |
| Boxライセンス | 既存ユーザー枠を利用。 | サービスアカウントとして存在。 |
↓実装画像↓
実装のポイント解説
今回のカスタムコネクタにおける最大の特長は、以下の点です。
- 認証方式を選択させる仕組み: ユーザーが設定画面で認証方式を選択できるUIを提供。
- サーバー認証(JWT)の実装ロジック: Workato内部でOpenSSLを使用し、Box API仕様に準拠した署名を実施。
- 任意ユーザーへの代理(As-User)機能: As-Userヘッダーをアクションごとに指定可能にする。
1. 認証方式を選択させる仕組み
Workato SDKの multi 認証タイプを利用すると、ユーザーの入力に応じて認証フローを選択に応じて切り替えられます。
接続設定の定義 (Connection Fields)
ユーザーに認証タイプを選ばせるためのフィールド auth_type を定義します。
これにより、ユーザーが「OAuth2.0」を選べばクライアントID/Secretの入力欄が、「JWT」を選べば秘密鍵などの入力欄が表示されるようになり、UXを損なわずに高度な機能を実装できます。
#接続設定の定義のイメージ
connection: {
fields: [
{
name: "auth_type",
control_type: "select",
pick_list: [["OAuth2", "oauth2"], ["JWT", "jwt"]],
extends_schema: true
}
],
# ここでauth_typeの値に応じて分岐させる
authorization: {
type: "multi",
selected: lambda do |connection|
connection["auth_type"]
end,
options: {
# OAuth2.0を選択した場合の設定
oauth2: {
type: "oauth2",
# ... (標準的なOAuth設定)
},
# JWTを選択した場合の設定
jwt: {
type: "custom",
# ... (後述するJWT設定)
}
}
}
}
2. サーバー認証(JWT)の実装ロジック
Boxのサーバー認証(JWT)を行うためには、以下のステップをコード内で実行する必要があります。
- 暗号化された秘密鍵をパスフレーズで復号する。
- Boxが要求するクレームを含むJSONを作成する。
- RSA(RS256)アルゴリズムで署名し、JWTアサーションを生成する。
- 生成したアサーションをBoxのトークンエンドポイントに送信し、アクセストークンを取得する。
ポイント
- 秘密鍵のサニタイズ: ユーザーが入力フォームやJSON設定ファイルから秘密鍵を貼り付けた際、改行コード（\n）が適切に処理されないと署名エラーになります。.gsub('\n', "\n") などの処理が必要です。
- 複合処理: BoxのprivateKeyは暗号化されています。OpenSSL::PKey::RSAで複合する必要があります。
- JTI: JTI(JWT ID) は、トークンの一意性を保証するためのものです。同じ JTIを持つリクエストを再利用（リプレイ攻撃）されるのを防ぐため、多くのAPIサーバーでは一度使ったJTIを短時間キャッシュし、拒否する仕組みになっています。SecureRandom を使用してJTIを生成し、リプレイ攻撃を防いでいます。
3. 任意ユーザーへの代理(As-User)機能
JWT認証（特に管理者権限）を使用する場合、特定ユーザーの代わりに操作を行うAs-User ヘッダーを使用できます。これを各アクションの input_fields で定義できるようにします。
# 入力スキーマに追加ヘッダー用の定義をマージするイメージ
additional_header: {
fields: lambda do |connection, config_fields, object_definitions|
[
{
name: "additional-header",
type: "object",
properties: [
{ name: "as-user", label: "As-User ID", optional: true, sticky: true }
]
}
]
end
}
まとめ
WorkatoのConnector SDKで multi 認証タイプを活用することで、標準コネクタではカバーしきれない柔軟な運用が可能なコネクタが作成できます。
特にBoxのようなエンタープライズ製品では、認証方式の制約がプロジェクトのボトルネックになりやすいため、この実装パターンをストックしておくと、実装の幅が大きく広がります。
参考リンク
Workato Connector SDK Documentation
Box Developer Documentation - JWT Authentication