JWTを使用したBox Node.js SDKの認証

Yuko Taniguchi

Published in

Box Developer Japan Blog

11 min readAug 16, 2023

前回の記事では、OAuth 2.0を使用したBox Node.jsの認証について説明しました。今回は、JWTを使用したもう1つの方法であるサーバー側の認証を見てみましょう。これは、Box APIで認証するための最も一般的な方法です。

JWTは、効果的にサーバー間認証を実現するよう設計されたオープンスタンダードです。

JWTを使用する場合

JWTを使用したサーバー側の認証は、以下に当てはまるアプリに最適な認証方法です。

Boxアカウントを持たないユーザーが使用する
独自のIDシステムを使用する
ユーザーにBoxを使用していることを意識させたくない
アプリケーションのBoxアカウント (サービスアカウント) 内にデータを保存し、ユーザーのBoxアカウントには保存しない

アプリの作成手順

Boxのカスタムアプリケーションを作成する
キーペアを生成してJSON構成をダウンロードする
管理コンソールでアプリを承認する
プロジェクトとSDKクライアントを初期化する
SDKクライアントを使用してファイルの情報を取得する

1. Boxのカスタムアプリケーションを作成する

前提条件: Node.js、無料のBox Individualアカウント

無料のDeveloperアカウントに関わる最近の出来事により、Boxでは、新規の無料Developerアカウントオプションを制限せざるを得なくなりました。
既存のEnterpriseアカウントをお持ちの場合は、手順に従ってサンドボックスを作成してください。

開発者コンソールで [アプリの新規作成] をクリックし、[カスタムアプリ] を選択します。

次に、ポップアップが表示され、アプリ名、簡単な説明、アプリの目的 (この場合は統合など) を入力するように求められます。

最後のフィールドでは、Boxをご利用のお客様の場合は [お客様]、組織外で使用するアプリケーションを作成する場合は [パートナー] を選択します。

手順2で、[サーバー認証 (JWTを使用)] を選択し、アプリを作成します。作成されたら、アプリの [構成] タブに移動します。

2. キーペアを生成してJSON構成をダウンロードする

キーペアを生成するには、開発者コンソールの [構成] タブに移動し、[公開キーの追加と管理] セクションまで下にスクロールします。

[公開/秘密キーペアを生成] をクリックします。この操作により、config.jsonファイルのダウンロードプロセスが開始されます。このファイルはすぐに必要になります。セキュリティ上の理由から、この操作のために、Boxアカウントで2FAを有効にしておく必要があります。

ℹ️ SDKを使用してBoxを操作する方法はいくつかあります。既定の方法ではサービスアカウントを使用します。サービスアカウントとは、独自のフォルダ構造と権限を備えた、個々のアプリケーションのBoxアカウントです。[一般設定] タブで、サービスアカウントのメールアドレスを確認できます。詳細については、ユーザータイプのガイドをご覧ください。

3. 管理コンソールでアプリを承認する

次に、新しく作成したBoxアプリを承認します。開発者コンソールで、[承認] タブに移動し、[確認して送信] ボタンをクリックします。Box Enterprise管理者に通知メールが送信されます。

管理コンソールの [アプリ] セクションに移動し、[カスタムアプリマネージャ] を選択します。そこで、新しいBoxカスタムアプリを承認できます。このプロセスの詳細な説明については、カスタムアプリの承認ガイドをご覧ください。

4. プロジェクトとSDKクライアントを初期化する

最後に、コーディング部分を開始します。新しいプロジェクトで作業している場合は、ターミナルを開き、新しいディレクトリを作成して、そこに移動します。

mkdir box-node-sdk-jwt
cd box-node-sdk-jwt

新しいプロジェクトを初期化します。

npm init

Box Node.js SDKをインストールします。

npm install --save box-node-sdk

開発者コンソールからダウンロードしたconfig.jsonファイルを必ずプロジェクトのディレクトリに含めてください。次の例のようになり、アプリ固有の値を指定する必要があります。

{
  "boxAppSettings": {
    "clientID": "abc...123",
    "clientSecret": "def...234",
    "appAuth": {
      "publicKeyID": "abcd1234",
      "privateKey": "-----BEGIN ENCRYPTED PRIVATE KEY-----\n....\n-----END ENCRYPTED PRIVATE KEY-----\n",
      "passphrase": "ghi...345"
    }
  },
  "enterpriseID": "1234567"
}

次に、index.jsファイルを作成し、config.jsonとBox SDKを要求します。最後に、SDKを初期化します。

const config = require('./config.json');
const BoxSDK = require('box-node-sdk');

const sdk = BoxSDK.getPreconfiguredInstance(config);
const client = sdk.getAppAuthClient('enterprise');

5. SDKクライアントを使用してファイルの情報を取得する

前述のとおり、デフォルトの設定を使用し、Boxに保存されているコンテンツにサービスアカウントを使用してアクセスします。

ℹ️ 特定のユーザーに代わって操作を実行する必要がある場合は、こちらのガイドで詳細を確認してください。

開発者コンソールの [構成] タブでサービスアカウントIDを確認できますが、index.jsファイルにリクエストを追加することでターミナルに詳細を記録することもできます。

// continue the index.js file

client.users.get(client.CURRENT_USER_ID)
  .then(currentUser => {
    console.log(currentUser)
  });

ターミナルで次のコマンドを実行して、SDKが正しく認証されているかどうかを確認します。

node index.js

アカウントの種類、ID、名前、ログインなど、サービスアカウントに関連する一連の詳細を取得する必要があります。

ℹ️ デフォルトでは、ほとんどのサービスアカウントに10 GBのストレージが割り当てられます。サービスアカウントに割り当てられたストレージ容量を更新するには、ユーザーを更新エンドポイントに対してAPI呼び出しを実行し、space_amount本文パラメータを使用して希望する値をバイト単位で渡します。
さらに、付与されたスコープに応じて、サービスアカウントは管理者の操作を実行できる場合があります。

Boxに保存されている特定のファイルまたはフォルダへのアクセス権限をサービスアカウントに付与するには、ウェブアプリで直接その処理を実行します。

ファイルがサービスアカウントと共有されたら、ファイルの情報を取得するリクエストを実行できます。ファイルまたはフォルダのIDは、BoxウェブアプリのURLで確認できます。

https://app.box.com/folder/{folderID}
https://app.box.com/file/{fileID}

fileIDを正確な値に置き換えます。

// continue the index.js file

client.files.get('fileID')
 .then(file => {
    console.log(file)
 });

ターミナルでもう一度次のスクリプトを実行します。

node index.js

以上です。✨Box Node.js SDKを使用した最初のファイルリクエストが完成しました。この操作のその他のオプションについては、SDKのドキュメントを確認してください。

{
   type: 'file',
   id: '11111',
   file_version: 
   { type: 'file_version',
    id: '22222',
    sha1: 'exampleValue' },
   sequence_id: '1',
   etag: '1',
   sha1: 'exampleValue',
   name: 'file.png',
   description: '',
   size: 106833,
   path_collection: 
   { total_count: 2,
    entries: 
    [ { type: 'folder',
     id: '0',
     sequence_id: null,
     etag: null,
     name: 'All Files' },
     { type: 'folder',
     id: '33333',
     sequence_id: '0',
     etag: '0',
     name: 'Collaborated Folder' } ] },
   created_at: '2016-11-16T22:01:44-08:00',
   modified_at: '2016-11-16T22:01:51-08:00',
   trashed_at: null,
   purged_at: null,
   content_created_at: '2016-10-29T18:33:50-07:00',
   content_modified_at: '2016-10-29T18:33:50-07:00',
   created_by: 
   { type: 'user',
    id: '44444',
    name: 'Owner',
    login: 'owner@example.com' },
   modified_by: 
   { type: 'user',
    id: '44444',
    name: 'Owner',
    login: 'owner@example.com' },
   owned_by: 
   { type: 'user',
    id: '44444',
    name: 'Owner',
    login: 'owner@example.com' },
   shared_link: null,
   parent: 
   { type: 'folder',
    id: '33333',
    sequence_id: '0',
    etag: '0',
    name: 'Collaborated Folder' },
   item_status: 'active' 
}

次の段階に進みましょう

📚 Box Node.js SDKのドキュメントを参照してください。

💻 ユーザー向けのカスタムアプリの構築: まず、開発者コンソールで追加のCORS設定を確認してください。

📥 / 📤 SDKを使用したファイルのダウンロードまたはアップロード: 開発者コンソールで忘れずにアプリケーションスコープの設定を調整してください。

🔑 以前のブログ記事で、Box Node.jsと認証方法としてOAuth 2.0を使用したサンプルアプリを確認できます。

🦄 Box Platformの上級者から学びたい場合

サポートや知識共有のためのBox Developer Community (英語のみ) にご参加ください。