JSON ウェブトークンを発行する

このドキュメントでは、ウェブベースとモバイルベースのアプリが Fleet Engine データにアクセスできるようにする際の JSON Web Token の発行方法について説明します。まだ確認していない場合は、Fleet Engine のセキュリティの JSON Web Token をご覧ください。Fleet Engine サービスでは、次のいずれかの方法で JWT を発行できます。

  • 認証ライブラリを使用する - コードベースが Java で記述されている場合は、この方法を使用することをおすすめします。このライブラリは、サービスで必要となるすべてのユースケース シナリオで JWT の発行を処理し、実装を大幅に簡素化します。
  • 独自の JWT を作成する - Google の JWT ライブラリを使用できない場合は、独自のコードベースに JWT をビルドする必要があります。このセクションでは、各シナリオの JWT のさまざまな例を示します。

JWT の仕組み

モバイル スマートフォンやウェブブラウザなどの信頼できない環境では、バックエンド サーバーは次のように動作する JWT を発行します。

  • 信頼性の低い環境で実行されているクライアント コードは、完全に信頼できる環境で実行されているサーバー コードを呼び出して、Fleet Engine に渡す適切な JWT をリクエストします。

  • JWT はサービス アカウントに関連付けられているため、Fleet Engine に送信されるリクエストは、JWT に署名したサービス アカウントに暗黙的に関連付けられます。

  • JWT のクレームは、クライアントが操作できるリソース（特定の車両、ルート、タスクなど）をさらに制限します。

Java の認可ライブラリを使用する

Java 用の Fleet Engine 認可ライブラリを使用するには、GitHub リポジトリをご覧ください。このライブラリを使用すると、Fleet Engine JWT の作成が簡素化され、安全に署名できます。次の機能を提供します。

  • プロジェクトの依存関係の宣言
  • オンデマンド ルートまたはスケジュール設定されたタスクのすべてのサービス アカウントのロールの完全なリスト
  • 認証情報ファイルを使用する以外のトークン署名メカニズム（サービス アカウントの権限借用など）
  • gRPC スタブまたは Google API Codegen（GAPIC）クライアント ライブラリから送信されるアウトバウンド リクエストに署名付きトークンを添付します。
  • 署名者を Fleet Engine クライアント ライブラリと統合する手順

コードから JWT を発行する場合

Java 用認可ライブラリを使用できない場合は、独自のコードベースに JWT を実装する必要があります。このセクションでは、独自のトークンを作成するためのガイドラインをいくつか示します。JWT フィールドとクレームのリストについては、Fleet Engine のセキュリティのJSON Web Token をご覧ください。Fleet Engine で使用されるサービス アカウントのロールについては、サービス アカウントのロールをご覧ください。オンデマンド ルートまたはスケジュール設定されたタスクの JWT の例については、次のセクションをご覧ください。

一般的なガイドライン

  • 適切なサービス アカウントとロールを使用する。サービス アカウントと関連付けられたロールにより、トークンをリクエストするユーザーに、トークンによってアクセス権が付与される情報を表示する権限が付与されます。詳細は以下のとおりです。
    • モバイル デバイスに渡す JWT に署名する場合は、Driver SDK ロールまたは Consumer SDK ロールのサービス アカウントを使用します。そうしないと、モバイル デバイスがアクセスすべきでないデータにアクセスしたり、変更したりする可能性があります。
    • 特権呼び出しに使用する JWT に署名する場合は、ADC または JWT を使用するときに、適切な Fleet Engine 管理者ロールを持つサービス アカウントを使用します。一致しない場合、オペレーションは失敗します。
  • 作成したトークンのみを共有する。トークンの作成に使用した認証情報を共有しないでください。
  • gRPC 呼び出しの場合、トークンを接続するメカニズムは、呼び出しに使用される言語とフレームワークによって異なります。HTTP 呼び出しにトークンを指定するメカニズムは、値がトークンであるベアラートークンを含む Authorization ヘッダーを含めることです。
  • 有効期限を返します。サーバーは、トークンの有効期限を返す必要があります（通常は秒単位）。
  • OAuth 2.0 アクセス トークンを使用するのではなく、トークン ベアラとして JSON を直接作成して署名する必要がある場合は、Identity デベロッパー ドキュメントの OAuth を使用しないサービス アカウントの認可の手順をご覧ください。

オンデマンド配車の場合

  • JWT ペイロードを作成するときに、認可セクションに追加のクレームを追加し、キー vehicleid または tripid を、呼び出しが行われる車両 ID またはルート ID の値に設定します。

スケジュール設定されたタスクの場合

  • サーバーが他の API を呼び出す場合、トークンには適切なクレームも含まれている必要があります。手順は次のとおりです。
    • 各キーの値を * に設定します。
    • すべての taskids と deliveryvehicleids へのアクセス権をユーザーに付与します。これを行うには、認可セクションにキー taskid と deliveryvehicleid を使用して追加のクレームを追加します。
    • taskids クレームでアスタリスク（*）を使用する場合は、アスタリスクが配列内の唯一の要素である必要があります。

オンデマンド ルートの JWT の例

このセクションでは、オンデマンド ルートを使用する一般的なシナリオの JWT の例を示します。

ドライバー アプリ オペレーションのトークンの例

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_driver_service_account"
}
.
{
  "iss": "driver@yourgcpproject.iam.gserviceaccount.com",
  "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "driver_12345"
   }
}

コンシューマ アプリ オペレーションのトークンの例

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "tripid": "trip_54321"
   }
}

スケジュール設定されたタスクの JWT の例

このセクションでは、スケジュールされたタスクを使用する一般的なシナリオの JWT の例を示します。

ドライバー アプリのトークンの例

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_delivery_driver_service_account"
    }
    .
    {
      "iss": "driver@yourgcpproject.iam.gserviceaccount.com",
      "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "driver_12345"
       }
    }

コンシューマ向けアプリのトークンの例

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_delivery_consumer_service_account"
    }
    .
    {
      "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "trackingid": "shipment_12345"
       }
    }

フリート オペレーションの JWT の例

このセクションでは、フリート運用の一般的なシナリオの JWT の例を示します。

フリート内のすべてのタスクと車両を追跡するトークンの例

次の例は、オペレーターが使用するウェブベースのアプリから、フリート内のすべてのタスクと車両を追跡するトークンです。これらのオペレーションに必要な権限は、クライアント アプリケーションの場合よりも多くなります。このトークンを使用するクライアントサイドの実装については、JavaScript フリート トラッキング ライブラリを設定するをご覧ください。

  • Fleet Engine Delivery Fleet Reader Cloud IAM ロールを使用してトークンに署名します。

   {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_consumer_service_account"
    }
    .
    {
      "iss": "superuser@yourgcpproject.iam.gserviceaccount.com",
      "sub": "superuser@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "scope": "https://www.googleapis.com/auth/xapi",
      "authorization": {
         "taskid": "*",
         "deliveryvehicleid": "*",
       }
    }

バックエンド サーバー オペレーションの代替の認証方法

バックエンド サーバー オペレーションの認証には ADC を使用することをおすすめします。ADC を使用できず、JWT を使用しなければならない場合は、次の例をご覧ください。

オンデマンド バックエンド サーバー オペレーションのトークンの例

  {
    "alg": "RS256",
    "typ": "JWT",
    "kid": "private_key_id_of_provider_service_account"
  }

  {
    "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
    "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
    "aud": "https://fleetengine.googleapis.com/",
    "iat": 1511900000,
    "exp": 1511903600,
    "authorization": {
       "vehicleid": "*",
       "tripid": "*"
     }
  }

スケジュール設定されたバックエンド サーバー オペレーションのトークンの例

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskid": "*"
       }
    }

バックエンド サーバーのスケジュール設定されたバッチ作成タスク オペレーションのトークンの例

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskids": ["*"]
       }
    }

配信車両ごとのスケジュール設定されたバックエンド サーバー オペレーションのトークンの例

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "*"
       }
    }

次のステップ

  • 設定を確認して、試用車両を作成し、トークンが想定どおりに動作していることを確認します。
  • バックエンド サーバー オペレーションで JWT の代わりに ADC を使用する方法については、セキュリティの概要をご覧ください。