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

このガイドでは、新しいJWTアプリケーションを作成して、エンタープライズで構成する方法について説明します。

以下の手順を完了して、新しいJWTアプリケーションを作成および構成します。

  1. JWTアプリケーションの作成および構成.
  2. 公開/秘密キーペアを生成して署名し、アプリケーションの要求を認証します
  3. エンタープライズ内のアプリケーションにアクセス権限を付与します

手順1: JWTアプリケーションの作成および構成

新しいJWTアプリケーションを作成するには、以下の手順に従います。

  1. Box開発者コンソールに移動して、[アプリの新規作成]オプションをクリックします。
  2. 次のページで、ビルドするアプリケーションのタイプ(例: [カスタムアプリ])をクリックし、[次へ]ボタンをクリックします。
  3. 認証方法ページが表示されたら、[JWTを使用したOAuth 2.0]のオプションをクリックし、[次へ]ボタンをクリックします。
  4. アプリケーションに一意の名前を割り当て、[アプリの作成]ボタンをクリックし、次のページで[アプリの表示]ボタンをクリックします。

新しく作成されたJWTアプリケーションが[構成]ページに表示され、追加で設定できます。そのためには、以下の設定を調整します。

  • アプリケーションアクセス: デフォルトでは、アプリケーションはアプリケーションレベルのアクセス権限に設定されます。これは、アプリケーションで作成されるユーザーのみをアプリケーションで操作できることを意味します。エンタープライズ全体で既存のユーザーも操作するには、エンタープライズオプションを選択することが必要になる場合があります。
  • アプリケーションスコープ: これらのオプションは、アプリケーションでアクセスできるAPIエンドポイント/機能を表します。各オプションの詳細については、スコープのページを参照してください。
  • 高度な機能: これらは、アプリケーション内のユーザーを操作できる2つのオプションです。通常これらのオプションは、機能が必要でない場合を除き両方とも有効にしてください。
    • アプリそれ自体ではなく、ユーザーの代わりにアプリケーションで各ユーザーがAPIリクエストを実行できるようにアクションを実行します。
    • ユーザーが資格情報でログインする必要なく、APIにアクセスできるユーザーアクセストークンを生成します。

これらのオプションが設定されたら、次の手順に移動します。

手順2: 公開/秘密キーペアの生成

JWTアプリケーションのRSAキーペアを生成するのに使用できる方法は2つあります。

  • アプリケーションの設定中に生成される構成ファイルを使用します(推奨方法)。
  • 公開/秘密キーペアを手動で生成します。

アプリケーション構成ファイルの使用

JWTアプリケーションの作成中、構成ファイルをBoxで作成するオプションを使用できます。このオプションには、公開/秘密キーペアと、認証中に使用される他の複数のアプリケーションの詳細が含まれます。これは、Box推奨の方法です。

以下の手順を完了して、構成ファイルを生成します。

  1. 開発者コンソールからJWTアプリケーションをクリックします
  2. 左のナビゲーションから[構成]オプションをクリックします。
  3. [公開キーの追加と管理]セクションまで下にスクロールします。
  4. [公開/秘密キーペアを生成]のボタンをクリックします。

config jsonファイルのダウンロードが開始します。このファイルの内容は次のようになります。

{
  "boxAppSettings": {
    "clientID": "plb5ltfzq9bz7micz6x6p5zfnycw98e3",
    "clientSecret": "PCQNt3d6xym9JiiVGRqDpNcFryxKhfun",
    "appAuth": {
      "publicKeyID": "hs2c02ko",
      "privateKey": "-----BEGIN ENCRYPTED PRIVATE KEY-----\n
                     MkiG9RefG12qasOn\nMBQGCCqGSIb3DQMHBAj/xheVHRkNNgSC
                     BMhL9TFI/pX0EVwkT44QyEOI9DuXIIlsg\nwqYR58DkP7ItCfZdFHq8
                     3pCwLjlvuRYsYGsb2F24OsLjCna0HsnpCbe4rvpedj7QE/aO\nN0xn8
                     p\nYnhxUWQzXy7ZnzYPn1wmtcaYwx+Ialn2tukqZCEpqrFf8guOjvBl
                     aPHcMGwYJab0\n26k=\n
                     -----END ENCRYPTED PRIVATE KEY-----\n",
      "passphrase": "176183e88324823d2318b74a1f376486"
    }
  },
  "enterpriseID": "13684983"
}

RSAキーペアはPEM形式であることが必要です。

次の完全なヘッダーとフッターが含まれることを確認してください。 '-----BEGIN PUBLIC KEY-----'と'-----END PUBLIC KEY-----'

ファイルに含まれる情報は、JWT認証プロセスの実行中に使用されます。

手動でのキーの生成

公開/秘密キーペアを生成する2番目の方法は、キーを手動で生成してから、JWTアプリケーションにアタッチします。

ターミナルウィンド/コマンドプロンプトから以下のコマンドを実行します。

openssl genrsa -des3 -out private.pem 2048
openssl rsa -in private.pem -outform PEM -pubout -out public.pem

Windowsシステムの場合

Cygwinパッケージをインストールし、これを使用して上記のOpenSSL RSAキーペアのコマンドを実行します。

次に、以下の手順を実行して、公開キーをJWTアプリケーションに追加します。

  1. 開発者コンソールからJWTアプリケーションをクリックします
  2. 左のナビゲーションから[構成]オプションをクリックします。
  3. [公開キーの追加と管理]セクションまで下にスクロールします。
  4. [公開キーの追加と管理]のボタンをクリックします。
  5. ウィンドウが開いたら、手動で生成した公開キーファイルの内容全体を貼り付けます。

手順3: エンタープライズ内のアプリケーションへのアクセス権限を付与します。

エンタープライズの所有者ではない場合

Enterpriseアカウントを所有していない場合(Boxアカウントが会社によって作成された場合など)、エンタープライズの管理者が以下の手順でアプリケーションを有効にし、アプリの認証に必要なすべての詳細情報を提供できるようにします。

エンタープライズの管理者をご存知でない場合には、Boxのアカウント設定ページで下部へスクロールしてください。管理者の連絡先が設定されていれば、[管理者の連絡先]に連絡先情報が表示されます。

キーが生成されたら、エンタープライズ管理者がBox Enterprise内でJWTアプリケーションを認証する必要があります。

エンタープライズ管理コンソールにアクセスし、以下の手順を使用して、アプリケーションへのアクセス権限を付与します。

  1. エンタープライズ管理コンソールのBusiness設定を開きます。
  2. ページ上部のナビゲーションの[アプリ]リンクをクリックします。
  1. [カスタムアプリケーション]セクションまで下にスクロールし、[新しいアプリケーションを承認]ボタンをクリックします。
  2. APIキーを求められたら、最初の手順で作成したJWTアプリケーションのクライアントIDを入力します。

クライアントIDの場所

クライアントIDを取得するには、開発者コンソールに移動して、JWTアプリケーションを選択します。JWTアプリケーションが開いたら、左のナビゲーションの[構成]に移動して、[OAuth 2.0資格情報]セクションまで下にスクロールします。クライアントIDが表示されます。

一般的なエラー

公開キー入力の一般的なエラーには、"不十分な暗号化"や"無効な形式"があります。

不十分な暗号化とは、よりビット数が多い暗号化アルゴリズムを使用する必要があるということです。無効な形式とは、公開キーの形式が正しいPEMフォーマットではないことを示しています。

アプリケーションのスコープを変更するタイミング

JWTスコープを変更した場合、変更内容を反映させるには、エンタープライズ内のアプリケーションを必ず再承認する必要があります。

エンタープライズの所有者ではない場合

エンタープライズの所有者ではない場合、以下の方法でアプリケーションを再度承認するようにエンタープライズ管理者に依頼する必要があります。管理者の連絡先を見つけるには、手順3の同様の呼び出し操作に記載されている指示に従ってください。

アプリケーションを再承認するには、以下の手順を使用します。

  1. エンタープライズ管理コンソールのBusiness設定を開きます。
  2. ページ上部のナビゲーションの[アプリ]リンクをクリックします。
  3. [カスタムアプリケーション]セクションまで下にスクロールし、JWTアプリケーション名の右側の楕円ボタンをクリックします。
  4. メニューから、[アプリを再承認]を選択して、新しいスコープ権限を取得します。

次のステップ