O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Emitir tokens JSON Web

Este documento aborda como emitir JSON Web Tokens como parte da ativação do acesso dos seus apps da Web e para dispositivos móveis aos dados do Fleet Engine. Se ainda não tiver feito isso, leia JSON Web Tokens na seção Segurança no Fleet Engine. Com o serviço do Fleet Engine, é possível emitir JWTs de uma das seguintes maneiras:

Use a biblioteca de autorização: o Google recomenda que você use essa abordagem quando sua base de código estiver escrita em Java. Essa biblioteca lida com a emissão de JWTs para todos os cenários de caso de uso que você pode precisar com o serviço e simplifica bastante sua implementação.
Crie seus próprios JWTs: se não for possível usar nossa biblioteca JWT, você precisará criá-los na sua própria base de código. Nesta seção, mostramos vários exemplos de JWTs para cada cenário.

Como os JWTs funcionam

Para ambientes não confiáveis, como smartphones e navegadores da Web, o servidor de back-end emite JWTs que funcionam da seguinte maneira:

O código do cliente em execução em um ambiente de baixa confiança chama o código do servidor em execução em um ambiente totalmente confiável para solicitar o JWT apropriado a ser transmitido ao Fleet Engine.
Os JWTs são associados a contas de serviço. Portanto, as solicitações enviadas ao Fleet Engine são implicitamente associadas à conta de serviço que assinou o JWT.
As declarações JWT restringem ainda mais os recursos em que o cliente pode operar, como veículos, viagens ou tarefas específicas.

Usar a biblioteca de autorização para Java

Para usar a biblioteca de autorização do Fleet Engine para Java, acesse o repositório do GitHub. A biblioteca simplifica a criação de JWTs do Fleet Engine e os assina com segurança. Ele oferece o seguinte:

Declarações de dependência do projeto
Uma lista completa de todos os papéis de conta de serviço para viagens sob demanda ou tarefas programadas
Mecanismos de assinatura de token que não usam arquivos de credenciais, como representar uma conta de serviço
Anexa tokens assinados a solicitações de saída feitas de um stub gRPC ou de uma biblioteca de cliente do Google API Codegen (GAPIC)
Instruções sobre como integrar os signatários às bibliotecas de cliente do Fleet Engine

Se você emitir JWTs do seu código

Se não for possível usar a biblioteca de autorização para Java, implemente JWTs na sua própria base de código. Nesta seção, apresentamos algumas diretrizes para criar seus próprios tokens. Consulte JSON Web Tokens na seção Segurança no Fleet Engine para ver uma lista de campos e declarações de JWT. Consulte Papéis de conta de serviço para saber quais são usados pelo Fleet Engine. Consulte a seção a seguir para ver uma lista de exemplos de JWT para viagens on demand ou tarefas programadas.

Diretrizes gerais

Use contas de serviço e papéis apropriados. A conta de serviço e o papel associado garantem que o usuário que solicita o token esteja autorizado a visualizar as informações que o token permite acessar. Especificamente:
- Se você estiver assinando um JWT para ser transmitido a um dispositivo móvel, use a conta de serviço para o papel do SDK do Driver ou do Consumer. Caso contrário, o dispositivo móvel poderá alterar e acessar dados que não deveria.
- Se você estiver assinando o JWT que será usado para chamadas privilegiadas, use a conta de serviço com o papel correto de administrador do Fleet Engine ao usar o ADC ou JWTs. Caso contrário, a operação falhará.
Compartilhe apenas os tokens criados. Nunca compartilhe as credenciais usadas para criar os tokens.
Para chamadas gRPC, o mecanismo para anexar o token depende da linguagem e do framework usados para fazer a chamada. O mecanismo para especificar um token para uma chamada HTTP é incluir um cabeçalho Authorization com um token do portador cujo valor é o token.
Retornar um prazo de validade. Seu servidor precisa retornar um expiry time para o token, geralmente em segundos.
Se você precisar criar e assinar um JSON diretamente como um portador de token, em vez de usar tokens de acesso do OAuth 2.0, leia as instruções para Autorização de conta de serviço sem OAuth na documentação para desenvolvedores do Identity.

Para viagens on demand

Ao criar o payload do JWT, adicione outra declaração na seção de autorização com a chave vehicleid ou tripid definida como o valor do ID do veículo ou da viagem para que a chamada está sendo feita.

Para tarefas programadas

Quando o servidor chama outras APIs, os tokens também precisam conter a declaração apropriada. Para isso, faça o seguinte:
- Defina o valor de cada chave como *.
- Conceda ao usuário acesso a todos os taskids e deliveryvehicleids. Para isso, adicione uma declaração extra na seção de autorização com as chaves taskid e deliveryvehicleid.
- Ao usar o asterisco (*) na declaração taskids, ele precisa ser o único elemento na matriz.

Exemplos de JWT para viagens on demand

Nesta seção, apresentamos exemplos de JWT para cenários comuns se você usa viagens on demand.

Exemplo de token para uma operação de app de motorista

{
  "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"
   }
}

Exemplo de token para uma operação de aplicativo para o consumidor

{
  "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"
   }
}

Exemplos de JWT para tarefas programadas

Esta seção mostra exemplos de JWT para cenários típicos se você usa tarefas programadas.

Exemplo de token para um app de motorista

    {
      "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"
       }
    }

Exemplo de token para um aplicativo para o consumidor

    {
      "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"
       }
    }

Exemplos de JWT para operações de frota

Nesta seção, apresentamos um exemplo de JWT para um cenário típico em operações de frota.

Exemplo de token para rastrear todas as tarefas e veículos em uma frota

O exemplo a seguir é um token que rastreia todas as tarefas e veículos na frota de um app baseado na Web usado por um operador. As permissões necessárias para essas operações são maiores do que para aplicativos cliente. Consulte Configurar a biblioteca JavaScript de monitoramento de frotas para a implementação do lado do cliente que usaria esse token:

Assine o token usando o papel do Cloud IAM Fleet Engine Delivery Fleet Reader.

Observação: o token criado com esse papel concede algumas permissões às entidades do Fleet Engine. Verifique se o back-end compartilha o token apenas com usuários autenticados.

   {
      "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": "*",
       }
    }

Método de autenticação alternativo para operações do servidor de back-end

O Google recomenda o uso do ADC para autenticar operações do servidor de back-end. Se não for possível usar o ADC e você precisar usar JWTs, consulte estes exemplos.

Exemplo de token para uma operação de servidor de back-end on demand

  {
    "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": "*"
     }
  }

Exemplo de token para uma operação programada do servidor de back-end

    {
      "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": "*"
       }
    }

Exemplo de token para uma operação de criação de tarefas em lote agendada do servidor de back-end

    {
      "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": ["*"]
       }
    }

Exemplo de token para uma operação programada de servidor de back-end por veículo de entrega

    {
      "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": "*"
       }
    }

A seguir

Verifique sua configuração para criar um veículo de teste e garantir que os tokens estejam funcionando como esperado.
Para informações sobre como usar o ADC em vez de JWTs para operações de servidor de back-end, consulte a Visão geral de segurança.