JSON Web Tokens
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Um JSON Web Token (JWT) é um padrão da Web aberto usado para autenticar e autorizar trocas de informações entre um cliente e um servidor. Quando um usuário de app
faz login pela primeira vez com as credenciais de função adequadas, o servidor cria
e retorna um JWT codificado e assinado digitalmente para uso em solicitações subsequentes.
Esse processo autentica o usuário e autoriza o acesso a rotas, serviços e recursos com base na função da conta.
O Fleet Engine exige o uso de JSON Web Tokens (JWTs) para chamadas de método da API
de ambientes de baixa confiança: smartphones e navegadores.
Um JWT é originado no seu servidor, assinado, criptografado e transmitido ao cliente
para interações subsequentes com o servidor até expirar ou não ser mais válido.
Detalhes importantes
Ao contrário das chaves de API, os JWTs têm curta duração e limitam as operações apenas àquelas que
a função está autorizada a realizar. Para mais informações sobre JWTs, consulte
JSON Web Tokens na Wikipédia. Para mais detalhes sobre papéis de acesso, consulte
Papéis da conta de serviço neste guia.
Elementos JWT
Os JWTs contêm um cabeçalho e uma seção de declaração. A seção de cabeçalho contém informações como a chave privada obtida de contas de serviço e o algoritmo de criptografia. A seção de declaração contém informações como o horário de criação e o tempo de vida do JWT, os serviços a que ele declara ter acesso e outras informações de autorização para restringir o acesso, por exemplo, o ID do veículo de entrega.
A tabela a seguir fornece detalhes descritivos sobre os campos JWT em geral, bem como informações específicas sobre onde encontrar os valores desses campos no seu projeto do Google Cloud do Fleet Engine.
Campos de cabeçalho JWT
Campo |
Descrição |
alg |
O algoritmo a ser usado. `RS256`. |
typ |
O tipo de token. `JWT`. |
criança |
O ID da chave privada da sua conta de serviço. Você encontra esse valor no campo
private_key_id do arquivo JSON da conta de serviço. Use uma chave de uma conta de serviço com o nível correto de permissões. |
Campos de declarações do JWT
Campo |
Descrição |
iss |
O endereço de e-mail da sua conta de serviço, encontrado no campo
client_email do arquivo JSON da conta de serviço. |
sub |
O endereço de e-mail da sua conta de serviço, encontrado no campo
client_email do arquivo JSON da conta de serviço. |
aud |
O SERVICE_NAME da sua conta de serviço, neste caso https://fleetengine.googleapis.com/ |
iat |
O carimbo de data/hora em que o JWT foi criado, especificado em segundos
decorridos desde 00:00:00 UTC, January 1, 1970. Defina 10 minutos para a defasagem.
Se o carimbo de data/hora estiver muito distante no passado ou no futuro, o servidor poderá informar um erro. |
exp |
O carimbo de data/hora em que o JWT expira, especificado em segundos decorridos
desde 00:00:00 UTC, January 1, 1970. A solicitação falha se o carimbo de data/hora for mais de uma hora no futuro. |
autorização |
Dependendo do caso de uso, pode conter deliveryvehicleid, trackingid, taskid ou taskids.
Se você especificar taskids, o escopo de autorização precisará ser uma matriz em uma das seguintes formas:
"taskids": ["task_id_one","task_id_two"]
ou
"taskids": ["*"] |
Declarações JWT do Fleet Engine
O Fleet Engine usa declarações particulares. O uso de declarações particulares garante que apenas clientes autorizados possam acessar os próprios dados.
Por exemplo, quando seu servidor emite um JSON Web Token para um dispositivo móvel de um motorista, ele precisa conter a declaração vehicleid ou deliveryvehicleid com o valor do ID do veículo desse motorista. Em seguida,
dependendo da função do motorista, os JWTs permitem o acesso apenas ao ID do veículo específico
e não a qualquer outro ID de veículo arbitrário.
O Fleet Engine usa as seguintes declarações particulares:
Viagens sob demanda
-
vehicleid:
- O Driver SDK sempre usa essa declaração, seja em uma viagem ou em um veículo. O back-end do Fleet Engine garante que o veículo esteja associado à viagem solicitada antes de fazer a modificação.
-
O JWT pode abranger operações de veículo e de viagem, mesmo que não seja necessário, o que pode simplificar a implementação da assinatura do JWT.
-
tripid:
- O SDK do consumidor sempre usa essa declaração.
-
O JWT pode abranger operações de veículo e de viagem,
mesmo que não seja necessário, o que pode simplificar a implementação
da assinatura do token.
Tarefas agendadas
-
deliveryvehicleid
Use ao chamar APIs por veículo de entrega.
-
taskid
Usado ao chamar APIs por tarefa.
-
taskids
Use ao chamar
BatchCreateTasksAPI. Essa declaração precisa estar no formato de matriz, e a matriz precisa conter todos os IDs de tarefa necessários para concluir a solicitação. Não inclua declarações de delivervehicleid,
trackingid ou taskid.
-
trackingid
Use ao chamar o
GetTaskTrackingInfoAPI. A declaração precisa corresponder ao ID de rastreamento na solicitação. Não inclua declarações de delivervehicleid,
taskid ou taskids.
A seguir
Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2025-08-31 UTC.
[null,null,["Última atualização 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."]]
