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 da Fleet Engine. Se ainda não fez isso já, leia JSON Web Tokens na seção Segurança na Fleet Engine. Com o serviço da 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 caso de uso que você pode precisar com o serviço e simplifica muito a implementação.
• Criar seus próprios JWTs: se não for possível usar nossa biblioteca de JWT, será necessário criar esses JWTs na sua própria base de código. Esta seção fornece 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 a ser transmitido à Fleet Engine.

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

• As declarações de 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 da Fleet Engine para Java, acesse o repositório do GitHub. A biblioteca simplifica a criação de JWTs da Fleet Engine e os assina com segurança. Ela 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 que não usam arquivos de credenciais, como a representação de 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 da Fleet Engine

Se você emitir JWTs do seu código

Se não for possível usar a biblioteca de autorização para Java, você precisará implementar JWTs na sua própria base de código. Esta seção fornece algumas diretrizes para criar seus próprios tokens. Consulte JSON Web Tokens na seção Segurança na Fleet Engine para conferir uma lista de campos e declarações de JWT. Consulte Papéis da conta de serviço roles para conferir os papéis da conta de serviço usados pela 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

• 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 a que o token concede acesso. Especificamente:
  • Se você estiver assinando um JWT a ser transmitido a um dispositivo móvel, use a conta de serviço para o papel do 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ê estiver assinando o JWT a ser usado para chamadas privilegiadas, use a conta de serviço com o papel correto de administrador da Fleet Engine ao usar 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 de anexação do token depende da linguagem e da estrutura usadas para fazer a chamada. O mecanismo para especificar um token para uma chamada HTTP é incluir um cabeçalho Authorization com um token de portador cujo valor seja o token.
• Retorne um prazo de validade. O servidor precisa retornar um expiry time 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 OAuth 2.0, leia as instruções para autorização de conta de serviço sem OAuth na documentação do desenvolvedor 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 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 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 fornece exemplos de JWT para cenários comuns se você usar viagens sob demanda.

Exemplo de token para uma operação de app do 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 exemplos de JWT para cenários típicos se você usar tarefas programadas.

Exemplo de token para um app do 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 fornece um exemplo de JWT para um cenário típico em operações de frota.

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

O exemplo a seguir é um token que acompanha todas as tarefas e veículos da frota de um app da 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 de rastreamento de frota do JavaScript 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.

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

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

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

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

    {
      "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 a configuração para criar um veículo de teste e garantir que os tokens estejam funcionando conforme o 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.