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 (JWT) như một phần của việc 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 chưa làm 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 cơ sở mã 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ụ này và giúp đơn giản hoá đáng kể quá trình 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ích hợp các thư viện 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 JWT hoạt động

Đố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 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 có độ tin cậy cao để yêu cầu JWT thích hợp chuyể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 gửi đến Fleet Engine sẽ được liên kết ngầm với tài khoản dịch vụ đã ký JWT.

  • Các khai báo JWT 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 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 Fleet Engine cho Java, hãy truy cập vào kho lưu trữ GitHub. Thư viện này giúp đơn giản hoá việc tạo JWT Fleet Engine và ký chúng một cách an toàn. Thư viện này cung cấp những nội dung sau:

  • Khai báo phần phụ thuộc dự án
  • Danh sách đầy đủ tất cả cá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 nhiệm vụ đã lên lịch
  • Cơ chế ký mã thông báo khác với việc sử dụng tệp thông tin đăng nhập, 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 được thực hiện từ một mã giả lập gRPC hoặc thư viện ứng dụng Google API Codegen (GAPIC)
  • Hướng dẫn về cách 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 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. Hãy xem bài viết Mã thông báo web JSON trong phần Bảo mật trong Fleet Engine để biết danh sách các trường và khai báo JWT. Hãy xem bài viết 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 các chuyến đi theo yêu cầu hoặc nhiệm vụ đã lên lịch.

Nguyên tắc chung

  • Sử dụng tài khoản dịch vụ và vai trò thích hợp. Tài khoản dịch vụ và vai trò được 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 Trình điều khiển hoặc 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 phép truy cập.
    • Nếu ký JWT để sử dụng cho các lệnh gọi có đặ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ẻ các 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 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 được 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à đưa tiêu đề Authorization vào mã thông báo người mang 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 người 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ụ mà không cần OAuth trong tài liệu dành cho Nhà phát triển Identity.

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

  • Khi tạo tải trọng JWT, hãy thêm một khai báo bổ sung trong phần uỷ quyền có khoá vehicleid hoặc tripid được đặt thành giá trị của mã nhận dạng phương tiện hoặc mã nhận dạng 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 khai báo thích hợp. Để thực hiện 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. Để thực hiện việc này, bạn hãy thêm một khai báo bổ sung trong phần uỷ quyền có các khoá taskid và deliveryvehicleid.
    • Khi sử dụng dấu hoa thị (*) trong khai báo taskids, đây 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 các ví dụ về JWT cho các trường hợp phổ biến nếu bạn sử dụng các chuyến đi theo yêu cầu.

Mã thông báo ví dụ cho một thao tác của ứ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 ví dụ cho một thao tác của ứng dụng 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 nhiệm vụ đã lên lịch

Phần này cung cấp ví dụ về JWT cho các trường hợp điển hình nếu bạn sử dụng nhiệm vụ đã lên lịch.

Mã thông báo ví dụ 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 ví dụ cho ứng dụng người 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 các hoạt động của đội xe

Phần này cung cấp ví dụ về JWT cho một trường hợp điển hình trong các hoạt động của đội xe.

Mã thông báo ví dụ để theo dõi tất cả các nhiệm vụ và phương tiện trong một đội xe

Ví dụ sau đây là một mã thông báo theo dõi tất cả các nhiệm vụ và phương tiện trong đội xe từ một ứng dụng dựa trên web do một nhà điều hành sử dụng. Các quyền cần thiết cho các hoạt động này lớn hơn so với các ứng dụng. Hãy xem phần 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ẽ sử dụng mã thông báo này:

  • Ký mã thông báo bằng vai trò Cloud IAM 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ợ

Google khuyên 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 không thể sử dụng ADC và cần sử dụng JWT, hãy tham khảo các ví dụ này.

Mã thông báo ví dụ cho một hoạt động của 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 ví dụ cho một hoạt động của máy chủ phụ trợ đã lên 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 ví dụ cho một hoạt động của máy chủ phụ trợ đã lên lịch để tạo hàng loạt nhiệm vụ

    {
      "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 ví dụ cho một hoạt động của máy chủ phụ trợ đã lên lịch cho mỗi phương tiện 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 quá trình thiết lập để bạn có thể tạo một phương tiện thử nghiệm và đảm bảo mã thông báo của bạn đang hoạt động như dự định
  • Để 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 bài viết Tổng quan về bảo mật.