Phát hành mã thông báo web JSON

Tài liệu này trình bày cách phát hành mã thông báo web JSON trong quá trình cho phép ứng dụng web và ứng dụng dành cho thiết bị di động truy cập vào dữ liệu của Công cụ cho xe. Nếu bạn chưa đọc, hãy đọc phần Mã thông báo web JSON trong phần Bảo mật trong Công cụ của Fleet. Với dịch vụ Công cụ của đội xe, bạn có thể phát hành JWT theo một trong các cách sau:

  • Sử dụng thư viện uỷ quyền – Google khuyên bạn nên sử dụng phương pháp này khi cơ sở mã được viết bằng Java. Thư viện này xử lý việc phát hành JWT cho tất cả các trường hợp sử dụng mà bạn có thể cần với dịch vụ này và đơn giản hoá đáng kể việc triển khai.
  • Tạo JWT của riêng bạn – Nếu không thể sử dụng thư viện JWT của chúng tôi, bạn sẽ cần phải tạo các JWT này vào cơ sở mã của riêng mình. Phần này cung cấp nhiều ví dụ về JWT cho từng trường hợp.

Cách hoạt động của JWT

Đối với các môi trường không đáng tin cậy, chẳng hạn như điện thoại di động và trình duyệt web, máy chủ phụ trợ của bạn sẽ phát hành JWT hoạt động như sau:

  • Mã ứng dụng của bạn chạy trong môi trường có mức độ tin cậy thấp sẽ gọi mã máy chủ chạy trong môi trường có mức độ tin cậy cao để yêu cầu JWT thích hợp chuyển đến Công cụ của đội xe.

  • JWT được liên kết với tài khoản dịch vụ, vì vậy, các yêu cầu được gửi đến Công cụ của đội xe sẽ được liên kết ngầm với tài khoản dịch vụ đã ký JWT.

  • JWT xác nhận hạn chế thêm các tài nguyên mà ứng dụng có thể hoạt động, chẳng hạn như các phương tiện, chuyến đi hoặc tác vụ cụ thể.

Sử dụng thư viện uỷ quyền cho Java

Để sử dụng thư viện uỷ quyền Fleet Engine cho Java, hãy truy cập vào kho lưu trữ GitHub. Thư viện này đơn giản hoá việc tạo JWT cho Công cụ của đội xe và ký các JWT đó một cách an toàn. API này cung cấp những tính năng sau:

  • Khai báo phần phụ thuộc dự án
  • Danh sách đầy đủ tất cả vai trò của tài khoản dịch vụ cho các chuyến đi theo yêu cầu hoặc các tác vụ theo lịch
  • Cơ chế ký mã thông báo ngoài việc sử dụng tệp thông tin xác thực, chẳng hạn như giả mạo tài khoản dịch vụ
  • Đính kèm mã thông báo đã ký vào các yêu cầu gửi đi được tạo từ một mô-đun gRPC hoặc thư viện ứng dụng Google API Codegen (GAPIC)
  • Hướng dẫn tích hợp trình ký với thư viện ứng dụng Fleet Engine

Nếu bạn phát hành JWT từ mã

Nếu không thể sử dụng thư viện uỷ quyền cho Java, bạn phải triển khai JWT trong cơ sở mã của riêng mình. Phần này cung cấp một số nguyên tắc để tạo mã thông báo của riêng bạn. Xem phần Mã thông báo web JSON trong mục Bảo mật trong Công cụ của đội xe để biết danh sách các trường và thông báo xác nhận quyền sở hữu JWT. Xem phần Vai trò của tài khoản dịch vụ để biết các vai trò của tài khoản dịch vụ mà Công cụ quản lý đội xe sử dụng. Hãy xem phần sau để biết danh sách ví dụ về JWT cho các chuyến đi theo yêu cầu hoặc tác vụ theo lịch.

Nguyên tắc chung

  • Sử dụng các vai trò và tài khoản dịch vụ thích hợp. Tài khoản dịch vụ và vai trò liên kết đảm bảo rằng người dùng yêu cầu mã thông báo được uỷ quyền để xem thông tin mà mã thông báo cấp cho họ quyền truy cập. Cụ thể:
    • Nếu ký JWT để truyền đến thiết bị di động, hãy sử dụng tài khoản dịch vụ cho vai trò Trình điều khiển hoặc SDK người dùng. Nếu không, thiết bị di động có thể thay đổi và truy cập vào dữ liệu mà thiết bị không được phép truy cập.
    • Nếu ký JWT để sử dụng cho các lệnh gọi đặc quyền, hãy sử dụng tài khoản dịch vụ có vai trò Quản trị viên công cụ của đội xe chính xác khi sử dụng ADC hoặc JWT. Nếu không, thao tác sẽ không thành công.
  • Chỉ chia sẻ mã thông báo đã tạo. Không bao giờ chia sẻ thông tin xác thực dùng để tạo mã thông báo.
  • Đối với các lệnh gọi gRPC, cơ chế đính kèm mã thông báo phụ thuộc vào ngôn ngữ và khung dùng để thực hiện lệnh gọi. Cơ chế chỉ định mã thông báo cho lệnh gọi HTTP là thêm tiêu đề Authorization có mã thông báo của phương thức mang giá trị là mã thông báo.
  • Trả về thời gian hết hạn. Máy chủ của bạn phải trả về thời gian hết hạn của mã thông báo, thường là tính bằng giây.
  • Nếu bạn cần tạo và ký trực tiếp JSON dưới dạng người mang mã thông báo thay vì sử dụng mã truy cập OAuth 2.0, hãy đọc hướng dẫn về cách Uỷ quyền tài khoản dịch vụ mà không cần OAuth trong tài liệu dành cho Nhà phát triển nhận dạng.

Đối với chuyến đi theo yêu cầu

  • Khi tạo tải trọng JWT, hãy thêm một thông báo xác nhận bổ sung trong phần uỷ quyền bằng cách đặt khoá vehicleid hoặc tripid thành giá trị của mã nhận dạng xe hoặc mã chuyến đi mà lệnh gọi đang được thực hiện.

Đối với việc cần làm đã lên lịch

  • Khi máy chủ của bạn gọi các API khác, mã thông báo cũng phải chứa thông báo xác nhận quyền thích hợp. Để làm việc này, bạn có thể làm như sau:
    • Đặt giá trị của mỗi khoá thành *.
    • Cấp cho người dùng quyền truy cập vào tất cả taskids và deliveryvehicleids. Để làm điều này, bạn thêm một thông báo xác nhận bổ sung trong phần uỷ quyền bằng các khoá taskid và deliveryvehicleid.
    • Khi sử dụng dấu hoa thị (*) trong thông báo xác nhận quyền sở hữu taskids, dấu hoa thị phải là phần tử duy nhất trong mảng.

Ví dụ về JWT cho các chuyến đi theo yêu cầu

Phần này cung cấp ví dụ về JWT cho các trường hợp phổ biến nếu bạn sử dụng chuyến đi theo yêu cầu.

Mã thông báo mẫu cho thao tác trong ứng dụng trình điều khiển

{
  "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"
   }
}

Mã thông báo mẫu cho thao tác trong ứng dụng tiêu dùng

{
  "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"
   }
}

Ví dụ về JWT cho tác vụ được lên lịch

Phần này cung cấp ví dụ về JWT cho các trường hợp thông thường nếu bạn sử dụng các tác vụ theo lịch.

Mã thông báo mẫu cho ứng dụng trình điều khiển

    {
      "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"
       }
    }

Mã thông báo mẫu cho ứng dụng tiêu dùng

    {
      "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"
       }
    }

Ví dụ về JWT cho hoạt động của đội xe

Phần này cung cấp một ví dụ về JWT cho một tình huống thông thường trong hoạt động của đội xe.

Ví dụ về mã thông báo để theo dõi tất cả công việc và xe trong một đội xe

Ví dụ sau đây là một mã thông báo theo dõi tất cả công việc và xe trong đoàn xe từ một ứng dụng dựa trên web mà người vận hành sử dụng. Các quyền cần thiết cho các thao tác này lớn hơn so với các ứng dụng khách. Hãy xem phần Thiết lập Thư viện theo dõi đội xe bằng JavaScript để biết cách triển khai phía máy khách sử dụng mã thông báo này:

  • Ký mã thông báo bằng vai trò IAM trên đám mây Fleet Engine Delivery Fleet Reader.

   {
      "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": "*",
       }
    }

Phương thức xác thực thay thế cho các hoạt động của máy chủ phụ trợ

Bạn nên sử dụng ADC để xác thực hoạt động của máy chủ phụ trợ. Nếu bạn không thể sử dụng ADC và cần sử dụng JWT, hãy tham khảo các ví dụ sau.

Mã thông báo mẫu cho thao tác máy chủ phụ trợ theo yêu cầu

  {
    "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": "*"
     }
  }

Mã thông báo mẫu cho một thao tác máy chủ phụ trợ theo lịch

    {
      "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": "*"
       }
    }

Mã thông báo mẫu cho thao tác tạo tác vụ hàng loạt của máy chủ phụ trợ theo lịch

    {
      "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": ["*"]
       }
    }

Ví dụ về mã thông báo cho một máy chủ phụ trợ theo lịch hoạt động trên mỗi xe phân phối

    {
      "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": "*"
       }
    }

Bước tiếp theo

  • Xác minh chế độ thiết lập để bạn có thể tạo xe thử nghiệm và đảm bảo rằng mã thông báo của bạn đang hoạt động như dự kiến
  • Để biết thông tin về việc sử dụng ADC thay vì JWT cho các hoạt động của máy chủ phụ trợ, hãy xem phần Tổng quan về bảo mật.