このドキュメントでは、ウェブベースとモバイルベースのアプリが 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 に署名する場合は、ドライバまたはコンシューマ SDK のロールのサービス アカウントを使用します。アクセス権がない場合、モバイル デバイスは、アクセス権のないデータを変更したり、アクセスしたりする可能性があります。
- 特権呼び出しに使用する JWT に署名する場合は、ADC または JWT を使用するときに、適切な Fleet Engine 管理者ロールを持つサービス アカウントを使用します。それ以外の場合、オペレーションは失敗します。
- 作成したトークンのみを共有する。トークンの作成に使用された認証情報は共有しないでください。
- gRPC 呼び出しの場合、トークンを関連付けるメカニズムは、呼び出しに使用される言語とフレームワークによって異なります。HTTP 呼び出しにトークンを指定するメカニズムは、値がトークンであるベアラートークンを含む
Authorizationヘッダーを含めることです。 - 有効期限を返します。サーバーは、トークンの有効期限を返す必要があります（通常は秒単位）。
- OAuth 2.0 アクセス トークンを使用せずに、トークン署名者として JSON を直接作成して署名する必要がある場合は、Identity Developer のドキュメントにある 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 ReaderCloud 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": "*",
}
}
バックエンド サーバー オペレーションの代替認証方法
Google では、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": "*" } }