JSON 웹 토큰 발행

이 문서에서는 웹 및 모바일 기반 앱이 Fleet Engine 데이터에 액세스할 수 있도록 설정하는 과정에서 JSON 웹 토큰을 발급하는 방법을 설명합니다. 아직 읽지 않았다면 Fleet Engine의 보안 섹션의 JSON 웹 토큰을 읽어보세요. Fleet Engine 서비스를 사용하면 다음 방법 중 하나로 JWT를 발급할 수 있습니다.

  • 승인 라이브러리 사용: 코드베이스가 Java로 작성된 경우 이 방법을 사용하는 것이 좋습니다. 이 라이브러리는 서비스에 필요할 수 있는 모든 사용 사례 시나리오에 대한 JWT 발급을 처리하고 구현을 크게 간소화합니다.
  • 자체 JWT 만들기: Google의 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 웹 토큰을 참고하세요. Fleet Engine에서 사용하는 서비스 계정 역할은 서비스 계정 역할을 참고하세요. 온디맨드 여정 또는 예약된 작업의 JWT 예시 목록은 다음 섹션을 참고하세요.

일반 가이드라인

  • 적절한 서비스 계정 및 역할 사용 서비스 계정 및 연결된 역할은 토큰을 요청하는 사용자에게 토큰이 부여하는 액세스 권한이 있는 정보를 볼 권한이 있는지 확인합니다. 구체적으로는 다음과 같습니다.
    • 모바일 기기에 전달할 JWT에 서명하는 경우 드라이버 또는 소비자 SDK 역할의 서비스 계정을 사용합니다. 그렇지 않으면 모바일 기기에서 액세스해서는 안 되는 데이터를 변경하고 액세스할 수 있습니다.
    • 권한 있는 호출에 사용할 JWT에 서명하는 경우 ADC 또는 JWT를 사용할 때 올바른 Fleet Engine 관리자 역할이 있는 서비스 계정을 사용합니다. 그렇지 않으면 작업이 실패합니다.
  • 생성된 토큰만 공유 토큰을 만드는 데 사용된 사용자 인증 정보를 공유하지 마세요.
  • gRPC 호출의 경우 토큰을 연결하는 메커니즘은 호출에 사용된 언어와 프레임워크에 따라 다릅니다. HTTP 호출에 토큰을 지정하는 메커니즘은 값이 토큰인 베어러 토큰과 함께 Authorization 헤더를 포함하는 것입니다.
  • 만료 시간을 반환합니다. 서버는 토큰의 만료 시간을 반환해야 합니다(일반적으로 초 단위).
  • OAuth 2.0 액세스 토큰을 사용하는 대신 토큰 보유자로 직접 JSON을 만들고 서명해야 하는 경우 ID 개발자 문서에서 OAuth 없이 서비스 계정 승인 안내를 참고하세요.

주문형 차량

  • JWT 페이로드를 만들 때 호출이 이루어지는 차량 ID 또는 여정 ID 값으로 설정된 키 vehicleid 또는 tripid를 사용하여 승인 섹션에 추가 클레임을 추가합니다.

예약된 작업

  • 서버가 다른 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"
       }
    }

Fleet 작업용 JWT 예시

이 섹션에서는 차량 관리 작업의 일반적인 시나리오에 대한 JWT 예를 제공합니다.

전체 차량의 모든 작업과 차량을 추적하는 토큰의 예

다음 예는 운영자가 사용하는 웹 기반 앱에서 전체 차량의 모든 작업과 차량을 추적하는 토큰입니다. 이러한 작업에 필요한 권한은 클라이언트 애플리케이션에 필요한 권한보다 큽니다. 이 토큰을 사용하는 클라이언트 측 구현은 JavaScript Fleet Tracking Library 설정을 참고하세요.

  • 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를 사용하는 방법은 보안 개요를 참고하세요.