JWT認証を使用したBox CLI

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

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

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

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

アプリケーションの構成

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

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

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

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

アプリケーションの承認

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

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

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

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

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

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

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

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

CLIのインストールと構成

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

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

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

LinuxとNodeのインストール

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

npm install --global @box/cli

ソースコード

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

構成コマンドの実行

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

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

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

構成の確認

うまく構成されているか確認するには、コマンド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: []

次の手順

• コード例をGitHubのコマンドページで確認できます。
• OAuth 2.0のクイックスタートの2番目の手順に進み、コマンドの使用方法のチュートリアルを確認することもできます。