はじめに

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