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 클레임을 포함하지 않습니다.
다음 단계
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-31(UTC)
[null,null,["최종 업데이트: 2025-08-31(UTC)"],[[["\u003cp\u003eJSON Web Tokens (JWTs) are required for API calls to Fleet Engine from low-trust environments like smartphones and browsers, providing authentication and authorization.\u003c/p\u003e\n"],["\u003cp\u003eJWTs are digitally signed by a service account on your server, a trusted environment, and passed to the client for secure communication with Fleet Engine.\u003c/p\u003e\n"],["\u003cp\u003eJWTs contain header and claim sections with information about the private key, encryption algorithm, token lifespan, and authorized access scopes like vehicle or trip IDs.\u003c/p\u003e\n"],["\u003cp\u003eFleet Engine utilizes private claims within JWTs to ensure data security and limit access to specific resources based on assigned roles and vehicle or task IDs.\u003c/p\u003e\n"],["\u003cp\u003eUnlike API keys, JWTs are short-lived and restrict operations to those permitted by the associated service account role, enhancing security.\u003c/p\u003e\n"]]],[],null,["# JSON Web Tokens\n\nA JSON Web Token (JWT) is an open web standard that's used for authenticating\nand authorizing information exchanges between a client and a server. When an app\nuser first signs in with the appropriate role credentials, the server creates\nand returns an encoded, digitally-signed JWT for use with subsequent requests.\nThis process both authenticates the user and authorizes them to access routes,\nservices, and resources based on their account role.\n\nFleet Engine requires the use of **JSON Web Tokens** (JWTs) for API method calls\nfrom **low-trust environments**: smartphones and browsers.\n\nA JWT originates on your server, is signed, encrypted, and passed to the client\nfor subsequent server interactions until it expires or is no longer valid.\n\n**Key details**\n\n- Use [Application Default Credentials](https://google.aip.dev/auth/4110) to authenticate and authorize against Fleet Engine.\n- Use an appropriate service account to sign JWTs. See [Fleet Engine serviceaccount](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts#fleet_engine_service_account_roles) roles in **Fleet Engine Basics**.\n\nUnlike API keys, JWTs are short lived and limit operations to only those that\nthe role is authorized to perform. For more information on JWTs, see\n[JSON Web Tokens](https://en.wikipedia.org/wiki/JSON_Web_Token) on Wikipedia. For detail on access roles, see\n[Service account roles](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts) in this guide.\n\nJWT elements\n------------\n\nJWTs contain a header and a claim section. The header section contains\ninformation such as the private key obtained from service accounts, and the\nencryption algorithm. The claim section contains information such as the JWT's\ncreate time, time to live, the services that the JWT claims\naccess to, and other authorization information to scope access; for\nexample, the delivery vehicle ID.\n\nThe following table provides descriptive details about JWT fields in general,\nas well as specific information about where you can find the values for these\nfields in your Fleet Engine Cloud project.\n\n| **Field** | **Description** |\n|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| alg | The algorithm to use. \\`RS256\\`. |\n| typ | The type of token. \\`JWT\\`. |\n| kid | Your service account's private key ID. You can find this value in the `private_key_id` field of your service account JSON file. Make sure to use a key from a service account with the correct level of permissions. |\n[JWT header fields]\n\n| **Field** | **Description** |\n|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| iss | Your service account's email address, found in the `client_email` field of your service account JSON file. |\n| sub | Your service account's email address, found in the `client_email` field of your service account JSON file. |\n| aud | Your service account's `SERVICE_NAME`, in this case `https://fleetengine.googleapis.com/` |\n| iat | The timestamp when the JWT was created, specified in seconds elapsed since 00:00:00 `UTC, January 1, 1970`. Allow 10 minutes for skew. If the timestamp is too far in the past, or in the future, the server might report an error. |\n| exp | The timestamp when the JWT expires, specified in seconds elapsed since `00:00:00 UTC, January 1, 1970`. The request fails if the timestamp is more than one hour in the future. |\n| authorization | Depending on the use case, may contain `deliveryvehicleid`, `trackingid`, `taskid`, or `taskids`. If specifying taskids, the authorization scope must be an array in one of the following forms: `\"taskids\": [\"task_id_one\",\"task_id_two\"]` or `\"taskids\": [\"*\"]` |\n[JWT claims fields]\n\n### Fleet Engine JWT claims\n\nFleet Engine uses private claims. Using private claims ensures that only\nauthorized clients can access their own data.\n\nFor example, when your server issues a JSON Web Token for a driver's mobile\ndevice, it should contain either the `vehicleid` claim or the\n`deliveryvehicleid` claim with the value of that driver's vehicle ID. Then,\ndepending on the driver role, JWTs enable access only for the specific vehicle\nID and not any other arbitrary vehicle ID.\n\nFleet Engine uses the following private claims: \n\n### On-demand trips\n\n- **`vehicleid`** :\n - The Driver SDK always uses this claim, whether operating on a trip or vehicle. The Fleet Engine backend assures that the vehicle is associated with the requested trip before doing the modification.\n - The JWT can cover both vehicle and trip operations, even if not required, which may simplify the JWT signing implementation.\n- **`tripid`** :\n - The Consumer SDK always uses this claim.\n - The JWT can cover both vehicle and trip operations, even if not required, which may simplify the token signing implementation.\n\n### Scheduled tasks\n\n- `deliveryvehicleid`\n\n Use when calling per-delivery-vehicle\n APIs.\n- `taskid`\n\n Use when calling per-task APIs.\n- `taskids`\n\n Use when calling\n `BatchCreateTasksAPI`. This claim must be in array form,\n and the array should contain all task IDs necessary to complete the\n request. Don't include `delivervehicleid`,\n `trackingid`, or `taskid` claims.\n- `trackingid`\n\n Use when calling the\n `GetTaskTrackingInfoAPI`. The claim must match the tracking\n ID in the request. Don't include `delivervehicleid`,\n `taskid`, or `taskids` claims.\n\nWhat's next\n-----------\n\n- Read about [Fleet Engine security design](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/security-design) to understand the complete authentication flow.\n- Learn how to [Issue JSON Web Tokens](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/issue-jwt) from your server."]]
