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 cho trang web theo chuẩn JSON trong quá trình cho phép các ứng dụng dựa trên web và thiết bị di động truy cập vào dữ liệu của Fleet Engine. Nếu bạn chưa làm việc này, hãy đọc bài viết Mã thông báo web JSON trong phần Bảo mật trong Fleet Engine. Với dịch vụ Fleet Engine, bạn có thể phát hành JWT theo một trong những 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 toàn bộ mã nguồn của bạn đượ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ụ và đơn giản hoá đáng kể việc triển khai của bạn.
  • 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 xây dựng các JWT này vào toàn bộ mã nguồn 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 khách chạy trong môi trường có độ tin cậy thấp sẽ gọi mã máy chủ chạy trong môi trường hoàn toàn đáng tin cậy để yêu cầu JWT thích hợp truyền đến Fleet Engine.

  • 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 Fleet Engine sẽ được liên kết ngầm định với tài khoản dịch vụ đã ký JWT.

  • Xác nhận quyền sở hữu JWT hạn chế hơn nữa 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 nhiệm vụ cụ thể.

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

Để sử dụng thư viện uỷ quyền của 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 của Fleet Engine và ký chúng một cách an toàn. Thành phần này cung cấp những thông tin sau:

  • Khai báo phần phụ thuộc của dự án
  • Danh sách đầy đủ tất cả vai trò của tài khoản dịch vụ cho chuyến đi theo yêu cầu hoặc việc cần làm theo lịch
  • Các cơ chế ký mã thông báo không sử dụng tệp thông tin xác thực, chẳng hạn như mạo danh 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 từ một mã giả lập 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ã của mình

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 toàn bộ mã nguồn 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. Hãy xem phần Mã thông báo cho trang web theo chuẩn JSON trong mục Bảo mật trong Fleet Engine để biết danh sách các trường và thông báo xác nhận quyền sở hữu của 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à Fleet Engine sử dụng. Hãy xem phần sau để biết danh sách các ví dụ về JWT cho chuyến đi theo yêu cầu hoặc nhiệm vụ theo lịch.

Nguyên tắc chung

  • Sử dụng tài khoản dịch vụ và vai trò phù 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 để chuyển đến thiết bị di động, hãy sử dụng tài khoản dịch vụ cho vai trò SDK Tài xế hoặc SDK Người tiêu 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ó quyền truy cập.
    • Nếu ký JWT để 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 Fleet Engine 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. Tuyệt đối không chia sẻ thông tin đăng nhập dùng để tạo mã thông báo.
  • Đối với 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 được dùng để thực hiện lệnh gọi. Cơ chế để chỉ định một mã thông báo cho lệnh gọi HTTP là thêm tiêu đề Authorization có mã thông báo truy cập có 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 cho 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 một JSON dưới dạng mã thông báo mang, thay vì sử dụng mã truy cập OAuth 2.0, hãy đọc hướng dẫn về Uỷ quyền tài khoản dịch vụ không có OAuth trong Tài liệu dành cho nhà phát triển về danh tính.

Đố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 quyền sở hữu bổ sung trong phần uỷ quyền có khoá vehicleid hoặc tripid được đặt thành giá trị của mã xe hoặc mã chuyến đi mà lệnh gọi đang được thực hiện.

Đối với nhiệm vụ đã 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 tin xác nhận quyền sở hữu 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 việc này, bạn cần thêm một thông báo xác nhận quyền sở hữu 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 chuyến đi theo yêu cầu

Phần này cung cấp các 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 hoạt động của ứng dụng dành cho tài xế

{
  "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 hoạt động của ứng dụng dành cho người 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 các nhiệm vụ theo 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 tác vụ theo lịch.

Mã thông báo mẫu cho ứng dụng của tài xế

    {
      "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 của người 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 điển hình trong hoạt động của đội xe.

Mã thông báo mẫu để theo dõi tất cả nhiệm vụ và xe trong một đội xe

Ví dụ sau đây là mã thông báo theo dõi tất cả nhiệm vụ và xe trong đội xe từ một ứng dụng chạy trên nền tảng web mà người vận hành sử dụng. Các quyền cần thiết cho những thao tác này cao hơn so với các ứng dụng khách. Hãy xem bài viết Thiết lập Thư viện theo dõi đội xe 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ò 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": "*",
       }
    }

Phương pháp 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 cá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 một thao tác theo yêu cầu của máy chủ phụ trợ

  {
    "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 hoạt động theo lịch của máy chủ phụ trợ

    {
      "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ụ theo lô 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": ["*"]
       }
    }

Mã thông báo mẫu cho hoạt động theo lịch của máy chủ phụ trợ cho mỗi xe giao hàng

    {
      "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 để có thể tạo một phương tiện thử nghiệm và đảm bảo mã thông báo hoạt động như dự kiến
  • Để biết thông tin về cách 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.