JSON 웹 토큰

JSON 웹 토큰 (JWT)은 클라이언트와 서버 간의 정보 교환을 인증하고 승인하는 데 사용되는 개방형 웹 표준입니다. 앱 사용자가 적절한 역할 사용자 인증 정보로 처음 로그인하면 서버는 후속 요청에 사용할 인코딩되고 디지털 서명된 JWT를 만들어 반환합니다. 이 프로세스는 사용자를 인증하고 계정 역할에 따라 경로, 서비스, 리소스에 액세스할 수 있는 권한을 부여합니다.

Fleet Engine에서는 신뢰도가 낮은 환경(스마트폰 및 브라우저)에서 API 메서드를 호출할 때 JSON 웹 토큰(JWT)을 사용해야 합니다.

JWT는 서버에서 생성되고 서명, 암호화되어 만료되거나 더 이상 유효하지 않을 때까지 후속 서버 상호작용을 위해 클라이언트에 전달됩니다.

주요 세부정보

API 키와 달리 JWT는 수명이 짧고 역할이 실행할 수 있는 작업으로만 작업을 제한합니다. JWT에 대한 자세한 내용은 Wikipedia의 JSON 웹 토큰을 참고하세요. 액세스 역할에 대한 자세한 내용은 이 가이드의 서비스 계정 역할을 참고하세요.

JWT 요소

JWT에는 헤더와 클레임 섹션이 포함됩니다. 헤더 섹션에는 서비스 계정에서 가져온 비공개 키, 암호화 알고리즘과 같은 정보가 포함됩니다. 클레임 섹션에는 JWT의 생성 시간, 수명, JWT가 액세스 권한을 주장하는 서비스, 액세스 범위를 지정하는 기타 승인 정보(예: 배송 차량 ID)와 같은 정보가 포함됩니다.

다음 표에서는 일반적인 JWT 필드에 관한 설명과 Fleet Engine Cloud 프로젝트에서 이러한 필드의 값을 찾을 수 있는 위치에 관한 구체적인 정보를 제공합니다.

JWT 헤더 필드

필드

설명

alg

사용할 알고리즘입니다. `RS256`.

typ

토큰 유형입니다. `JWT`.

어린이

서비스 계정의 비공개 키 ID입니다. 이 값은 서비스 계정 JSON 파일의 private_key_id 필드에서 확인할 수 있습니다. 올바른 수준의 권한이 있는 서비스 계정의 키를 사용해야 합니다.
JWT 클레임 필드

필드

설명

iss

서비스 계정의 이메일 주소입니다. 서비스 계정 JSON 파일의 client_email 필드에 있습니다.

sub

서비스 계정의 이메일 주소입니다. 서비스 계정 JSON 파일의 client_email 필드에 있습니다.

aud

서비스 계정의 SERVICE_NAME(이 경우 https://fleetengine.googleapis.com/)

iat

JWT가 생성된 타임스탬프로, 00:00:00 UTC, January 1, 1970 이후 경과된 시간(초)으로 지정됩니다. 보정값은 10분이 허용됩니다. 타임스탬프가 너무 먼 과거 또는 미래인 경우 서버에서 오류를 보고할 수 있습니다.

exp

JWT가 만료되는 타임스탬프로, 00:00:00 UTC, January 1, 1970 이후 경과된 시간(초)으로 지정됩니다. 타임스탬프가 1시간 이상 미래인 경우 요청이 실패합니다.

승인

사용 사례에 따라 deliveryvehicleid, trackingid, taskid 또는 taskids이 포함될 수 있습니다.

taskid를 지정하는 경우 승인 범위는 다음 형식 중 하나의 배열이어야 합니다.

"taskids": ["task_id_one","task_id_two"]

또는

"taskids": ["*"]

Fleet Engine JWT 클레임

Fleet Engine은 비공개 클레임을 사용합니다. 비공개 클레임을 사용하면 승인된 클라이언트만 자체 데이터에 액세스할 수 있습니다.

예를 들어 서버에서 운전자의 모바일 기기에 JSON 웹 토큰을 발급하는 경우 해당 운전자의 차량 ID 값이 포함된 vehicleid 클레임 또는 deliveryvehicleid 클레임이 포함되어야 합니다. 그런 다음, 드라이버 역할에 따라 JWT는 특정 차량 ID에만 액세스를 허용하고 다른 임의 차량 ID에는 액세스를 허용하지 않습니다.

Fleet Engine은 다음 비공개 클레임을 사용합니다.

주문형 이동

  • vehicleid:
    • 드라이버 SDK는 이동 또는 차량에서 작동하는지 여부와 관계없이 항상 이 클레임을 사용합니다. Fleet Engine 백엔드는 수정하기 전에 차량이 요청된 여정과 연결되어 있는지 확인합니다.
    • JWT는 필수는 아니지만 차량 및 이동 작업 모두를 포함할 수 있으므로 JWT 서명 구현을 간소화할 수 있습니다.
  • tripid:
    • Consumer SDK는 항상 이 클레임을 사용합니다.
    • JWT는 필요하지 않더라도 차량 및 여행 작업을 모두 포함할 수 있으므로 토큰 서명 구현을 간소화할 수 있습니다.

예약된 작업

  • deliveryvehicleid

    배송 차량별 API를 호출할 때 사용합니다.

  • taskid

    작업별 API를 호출할 때 사용합니다.

  • taskids

    BatchCreateTasksAPI 호출 시 사용합니다. 이 클레임은 배열 형식이어야 하며 배열에는 요청을 완료하는 데 필요한 모든 작업 ID가 포함되어야 합니다. delivervehicleid, trackingid 또는 taskid 클레임을 포함하지 않습니다.

  • trackingid

    GetTaskTrackingInfoAPI를 호출할 때 사용합니다. 클레임은 요청의 추적 ID와 일치해야 합니다. delivervehicleid, taskid 또는 taskids 클레임을 포함하지 않습니다.

다음 단계