JSON 웹 토큰

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

신뢰 수준이 낮은 환경의 API 메서드 호출의 경우 Fleet Engine은 적절한 서비스 계정으로 서명된 JSON 웹 토큰 (JWT)을 사용해야 합니다. 신뢰도가 낮은 환경에는 스마트폰과 브라우저가 포함됩니다. JWT는 완전히 신뢰할 수 있는 환경인 서버에서 시작됩니다. JWT는 만료되거나 더 이상 유효하지 않을 때까지 서명되고 암호화된 후 후속 서버 상호작용을 위해 클라이언트에게 전달됩니다.

백엔드는 표준 애플리케이션 기본 사용자 인증 정보 메커니즘을 사용하여 Fleet Engine에 대해 인증하고 승인해야 합니다. 적절한 서비스 계정으로 서명된 JWT를 사용해야 합니다. 서비스 계정 역할 목록은 Fleet Engine 기본사항의 Fleet Engine 서비스 계정 역할을 참고하세요.

반면 백엔드는 표준 애플리케이션 기본 사용자 인증 정보 메커니즘을 사용하여 Fleet Engine에 대해 인증하고 승인해야 합니다.

API 키와 달리 JWT는 수명이 짧으며 역할이 수행하도록 승인된 작업으로만 작업을 제한합니다. JWT에 관한 자세한 내용은 위키피디아의 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 웹 토큰을 발행할 때는 vehicleid 클레임 또는 운전자의 차량 ID 값이 포함된 deliveryvehicleid 클레임이 포함되어야 합니다. 그런 다음 운전자 역할에 따라 JWT는 다른 임의의 차량 ID가 아닌 특정 차량 ID에 대해서만 액세스를 허용합니다.

Fleet Engine은 다음과 같은 비공개 소유권 주장을 사용합니다.

주문형 이동

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

예약된 작업

  • deliveryvehicleid

    전송 매체별 API를 호출할 때 사용합니다.

  • taskid

    태스크별 API를 호출할 때 사용합니다.

  • taskids

    BatchCreateTasksAPI를 호출할 때 사용합니다. 이 소유권 주장은 배열 형식이어야 하며 배열에는 요청을 완료하는 데 필요한 모든 태스크 ID가 포함되어야 합니다. delivervehicleid, trackingid 또는 taskid 소유권 주장은 포함하지 않습니다.

  • trackingid

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

다음 단계