Emitir tokens JSON Web

Este documento aborda como emitir JSON Web Tokens como parte da ativação do acesso de apps da Web e móveis aos dados do Fleet Engine. Se ainda não fez 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:

  • Usar a biblioteca de autorização: o Google recomenda essa abordagem quando a base de código é escrita em Java. Essa biblioteca processa a emissão de JWTs para todos os cenários de uso que você pode precisar com o serviço e simplifica muito a implementação.
  • Crie seus próprios JWTs: se não for possível usar nossa biblioteca JWT, será necessário criar esses JWTs na sua própria base de código. Esta seção apresenta os 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 para transmitir ao Fleet Engine.

  • Os JWTs são associados a contas de serviço. Portanto, as solicitações enviadas ao Fleet Engine são associadas implicitamente à conta de serviço que assinou o JWT.

  • As declarações do JWT restringem ainda mais os recursos em que o cliente pode operar, como veículos, viagens ou tarefas específicos.

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 construçã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 da conta de serviço para viagens sob demanda ou tarefas programadas
  • Mecanismos de assinatura de token diferentes do uso de arquivos de credencial, como a representação de uma conta de serviço
  • Anexa tokens assinados a solicitações de saída feitas em um stub do gRPC ou 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 código

Se não for possível usar a biblioteca de autorização para Java, será necessário implementar JWTs na sua própria base de código. Esta seção apresenta algumas diretrizes para criar seus próprios tokens. Consulte JSON Web Tokens na seção Segurança no Fleet Engine para conferir uma lista de campos e declarações de JWT. Consulte Papéis de contas de serviço para saber quais são os papéis de conta de serviço usados pelo Fleet Engine. Consulte a seção a seguir para conferir uma lista de exemplos de JWT para viagens sob demanda ou tarefas programadas.

Diretrizes gerais

  • Usar contas de serviço e papéis adequados. A conta de serviço e a função associada garantem que o usuário que solicita o token esteja autorizado a acessar as informações a que o token concede acesso. Especificamente:
    • Se você assinar um JWT para ser transmitido a um dispositivo móvel, use a conta de serviço para a função de SDK do motorista ou do consumidor. Caso contrário, o dispositivo móvel poderá alterar e acessar dados a que não deveria ter acesso.
    • Se você assinar o JWT para ser usado em chamadas privilegiadas, use a conta de serviço com a função de administrador do Fleet Engine correta ao usar o ADC ou JWTs. Caso contrário, a operação falha.
  • Compartilhe apenas os tokens criados. Nunca compartilhe as credenciais usadas para criar os tokens.
  • Para chamadas gRPC, o mecanismo de anexação do token depende da linguagem e do framework usados para fazer a chamada. O mecanismo para especificar um token em uma chamada HTTP é incluir um cabeçalho Authorization com um token de portador cujo valor é o token.
  • Retorna um prazo de validade. Seu servidor precisa retornar um tempo de expiração para o token, normalmente 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 de identidade.

Para viagens sob demanda

  • Ao criar o payload do JWT, adicione uma declaração extra 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 a qual a chamada está sendo feita.

Para tarefas agendadas

  • Quando o servidor chama outras APIs, os tokens também precisam conter a declaração adequada. Para isso, faça o seguinte:
    • Defina o valor de cada chave como *.
    • Conceda ao usuário acesso a todas as taskids e deliveryvehicleids. Para fazer 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 sob demanda

Esta seção apresenta exemplos de JWT para cenários comuns se você usa viagens sob demanda.

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 app do 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 fornece um exemplo 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 app do 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

Esta seção apresenta 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 clientes. Consulte Configurar a biblioteca de rastreamento de frotas do JavaScript para a implementação do lado do cliente que usaria esse token:

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

   {
      "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 de servidor de back-end

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

Exemplo de token para uma operação de servidor de back-end sob demanda

  {
    "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 de servidor de back-end programada

    {
      "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 de servidor de back-end programada

    {
      "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 um servidor de back-end programado por operação de 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