(付録) JWT認証を使用したBox CLI

ガイド ツール CLI (付録) JWT認証を使用したBox CLI

(付録) JWT認証を使用したBox CLI

これまで、Box CLIのクイックスタートガイドでは、JWTアプリケーションまたはサーバー認証アプリケーションの設定フローについて説明してきましたが、新しくOAuth 2.0バージョンのBox CLIをリリースしたため、新機能の使用についてガイドを更新しました。当初のJWTの設定手順については、引き続きサーバー認証アプリケーションを使用したい方のために、こちらに移動しました。

JWTアプリケーションの設定

サーバー認証を使用したCLIを使用するには、まず、開発者コンソールでBoxアプリケーションを作成します。CLIはAPI呼び出しを実行する際にバックグラウンドでこのアプリケーションを使用できます。CLIを既存のJWTアプリケーションに関連付ける場合は、この手順を省略できます。ただし、少なくとも、以下のスコープがアプリケーションの [構成] タブで設定されていることを確認してください。

  • Boxに格納されているすべてのファイルとフォルダの読み取り
  • Boxに格納されているすべてのファイルとフォルダへの書き込み
  • [すべてのファイル] ページの左側にあるナビゲーションパネルから、開発者コンソールを開きます。今回Box APIを使用するのが初めてで、このオプションがまだ使用できない場合は、こちらをクリックするとこのオプションをアカウントに追加できます。
  • [アプリの新規作成] > [カスタムアプリ] > [サーバー認証 (JWT使用)] の順にクリックし、アプリケーションに名前を付けて、[アプリの作成] をクリックします。

サーバー認証 (JWT使用) は、使用する前に必ず管理者の承認が必要になります。

アプリケーションの構成

これにより、アプリケーションの設定ページが表示され、そこで、そのアクセスや権限を選択する必要があります。アプリケーションの認証タイプが原因で、管理者の承認が必要になることにもう一度注意してください。

少なくとも、以下のスコープが必要です。

  • Boxに格納されているすべてのファイルとフォルダの読み取り
  • Boxに格納されているすべてのファイルとフォルダへの書き込み

アプリケーションアクセスとして、[アプリアクセスのみ] または [アプリ + Enterpriseアクセス] のいずれかを選択できます。

アプリケーションの承認

API呼び出しを正常に実行する前に、サーバー認証を利用するすべてのアプリケーションを管理コンソールで承認する必要があります。これは、すべてのJWTアプリケーションにはサービスアカウントがあるためです。サービスアカウントは、アプリケーションのスコープに基づいて管理者アクションを実行できます。

開発者と管理者向けの手順については、Boxの承認ガイドを参照してください。

スコープ、アプリケーションアクセス、トークン、権限がどのように連携しているかの詳細については、Boxのセキュリティメカニズムに関する記事を参照してください。

設定の変更がこのアプリケーションに対して行われた場合は、その変更を有効にするためにこのアプリケーションを再承認する必要があります。

アプリケーションが使用できる状態になっているかどうかを確認するには、開発者コンソールの [承認] タブを表示します。状態とステータスはそれぞれ、[有効] と [承認済み] になっているはずです。

承認済みのアプリ

必要なデータのダウンロード

CLIでは、API呼び出しを実行するために、ローカルに保存されている構成ファイルが必要です。

構成ファイルをダウンロードするには、開発者コンソールの [構成] タブにアクセスし、[公開/秘密キーペアを生成] をクリックします。これにより、アプリケーションの構成ファイルを自動的にダウンロードする前に2FA認証が行われます。詳細については、Boxのガイドを参照してください。

セキュリティ上の理由により、公開/秘密キーペアを生成するには、Boxアカウントで2FAを有効にする必要があります。

EnterpriseID_publicKeyID_config.jsonという形式のデフォルトの名前が付いているダウンロード済みファイルをコンピュータ上で探します。この名前をそのまま使用しても、変更してもかまいません。このガイドでは、ファイルの名前をconfig.jsonに変更することを想定しています。

誤って削除または移動されることがない場所にファイルを配置することが重要です。ファイルが削除または移動された場合は、手順2を繰り返してCLIを再構成する必要があります。

CLIのインストールと構成

Windows用およびmacOS用のインストーラが提供されていますが、その他の環境でCLIを構築する場合はRawソースコードを利用できます。

Windows用およびmacOS用インストーラ

お使いのマシンに最新のCLIをインストールするには、最新リリースに対応する最新の.exe (Windowsの場合) または.pkg (macOSの場合) をダウンロードします。

最新のCLIインストーラをダウンロード

LinuxとNodeのインストール

さらに、CLIは、任意のプラットフォーム (Linuxなど) にNodeパッケージとしてインストールすることができます。このためには、Node JSをマシンにインストールしておく必要があります。

npm install --global @box/cli

ソースコード

CLIのソースコードは、GitHubで提供されています。

構成コマンドの実行

ここで、手順1でダウンロードした構成ファイルを指すよう、CLIを構成する必要があります。

CLIの構成図

ターミナルまたはコマンドラインを開き、box configure:environments:add PathToConfigFileHereコマンドを実行します。ここでは、PathToConfigHereconfig.jsonファイルのパスに置き換えます。

例: box configure:environments:add /Users/ExampleUser/Documents/CLI/config.json

Finder/エクスプローラからターミナル/コマンドラインウィンドウにcsvファイルをドラッグすると、パスを自動で入力できます。

構成の確認

うまく構成されているか確認するには、コマンドbox users:getを使用します。

次のように、成功を示すレスポンスには、アクセストークンに関連付けられたサービスアカウントユーザーの詳細が示されます。

Type: user
ID: ''0123456789''
Name: Box CLI - Quickstart Example
Login: AutomationUser_123456_8jSo6Lqvko@boxdevedition.com
Created At: '2020-01-01T09:45:01-07:00'
Modified At: '2021-03-01T09:30:05-07:00'
Language: en
Timezone: America/Los_Angeles
Space Amount: 999999999999999
Space Used: 6291500
Max Upload Size: 16106127360
Status: active
Job Title: ''
Phone: ''
Address: example+user@box.com
Avatar URL: ''
Notification Email: []

デフォルトでは、JWTアプリケーションはサービスアカウントのアクセストークンを自動的に取得します。デフォルトユーザーの変更は可能ですが、このガイドでは変更しないことを想定しています。

次の手順