No momento, a solução da frota de última milha está disponível apenas para clientes selecionados. Entre em contato com a equipe de vendas para saber mais.

Esta página foi traduzida pela API Cloud Translation.

Autenticação e autorização

Nesta seção, explicamos os conceitos de autenticação e autorização com relação à integração com o Fleet Engine.

É possível configurar os recursos fornecidos pela Last Mile Fleet Solution com o Console do Google Cloud. Os SDKs do Fleet Engine exigem o uso de JSON Web Tokens (JWTs) assinados por uma conta de serviço apropriada.

Visão geral

Os back-ends de clientes que autenticam e autorizam no Fleet Engine precisam usar mecanismos padrão do Application Default Credentials.

O Fleet Engine também recebe chamadas originadas de ambientes de baixa confiança, como smartphones e navegadores. Para proteger as chaves secretas da conta de serviço adequadas apenas para ambientes confiáveis, os back-ends dos clientes precisam gerar JSON Web Tokens (JWT) assinados com outras declarações específicas do Fleet Engine, que podem ser emitidas para ambientes não confiáveis, como smartphones.

Princípios de design de autenticação

O fluxo de autenticação do Fleet Engine incorpora os princípios de design a seguir.

Os papéis do IAM definem um conjunto de permissões nos recursos permitidos para um principal. Por exemplo, os papéis de administrador podem fazer tudo com o Application Default Credentials, enquanto o papel de Motorista não confiável* só pode atualizar a localização do veículo e está restrito ao uso de JWTs para autenticação e autorização.
Para ambientes não confiáveis, as declarações JWT restringem ainda mais as entidades em que o autor da chamada pode operar. Podem ser tarefas específicas ou veículos de entrega.
O código em execução em um ambiente de baixa confiança precisa primeiro chamar o código em execução em um ambiente confiável para emitir um JWT.
O Fleet Engine executa as seguintes verificações de segurança nas chamadas de API de um recurso:
1. O principal de chamada tem as permissões apropriadas (por meio da atribuição de papel) para a ação no recurso.
2. Para papéis não administradores, as declarações JWT transmitidas na solicitação fornecem a permissão necessária para o recurso.

Fluxo de autenticação

O diagrama de sequência a seguir demonstra esses detalhes do fluxo de autenticação.

O administrador da frota cria contas de serviço.
O administrador da frota atribui papéis específicos do IAM às contas de serviço.
O administrador da frota configura o back-end com as contas de serviço e o Application Default Credentials.
O app cliente solicita um JWT do back-end do cliente. O solicitante pode ser o app Driver, o app para consumidor ou um app de monitoramento.
O back-end do cliente assina e emite um JWT para a respectiva conta de serviço. O app cliente recebe o JWT.
O app cliente usa o JWT para se conectar ao Fleet Engine e ler ou modificar dados, dependendo dos papéis do IAM atribuídos a ele durante a fase de configuração.

Diagrama de sequência de autenticação

Configuração do projeto do Cloud

Para configurar o projeto na nuvem, primeiro crie o projeto e, em seguida, crie as contas de serviço.

Para criar seu projeto do Google Cloud:

Criar um projeto do Google Cloud usando o console do Google Cloud.
Usando o painel de APIs e serviços, ative a API Local Rides and Deliveries.

Contas de serviço e papéis do IAM

A conta de serviço é um tipo especial de conta usado por um aplicativo, em vez de uma pessoa. Normalmente, uma conta de serviço é usada para criar JWTs que concedem diferentes conjuntos de permissões, dependendo do papel. Para reduzir a possibilidade de abuso, crie várias contas de serviço, cada uma com o conjunto mínimo de papéis necessários ().

A Last Mile Fleet Solution usa os seguintes papéis:

Papel	Descrição
Usuário de motorista confiável de entrega do Fleet Engine `roles/fleetengine.deliveryTrustedDriver`	Concede permissão para criar e atualizar tarefas e veículos de entrega, incluindo a atualização do local do veículo de entrega e do status ou resultado da tarefa. Os tokens emitidos por uma conta de serviço com esse papel normalmente são usados nos dispositivos móveis do motorista de entrega ou nos servidores de back-end.
Usuário de motorista não confiável de entrega do Fleet Engine `roles/fleetengine.deliveryUntrustedDriver`	Concede permissão para atualizar o local do veículo de entrega. Os tokens emitidos por uma conta de serviço com esse papel normalmente são usados nos dispositivos móveis do seu motorista de entrega.
Usuário consumidor de entrega do Fleet Engine `roles/fleetengine.deliveryConsumer`	Concede permissão para pesquisar tarefas usando um ID de acompanhamento e para ler, mas não atualizar, as informações da tarefa. Os tokens gerados por uma conta de serviço com esse papel normalmente são usados no navegador da Web de um consumidor de entrega.
Administrador de entrega do Fleet Engine `roles/fleetengine.deliveryAdmin`	Concede permissão de leitura e gravação para recursos de entrega. Os principais com esse papel não precisam usar JWTs, mas sim o Application Default Credentials. As declarações JWT personalizadas são ignoradas. Esse papel precisa ser restrito a ambientes confiáveis (back-end do cliente).
~~Superusuário de entrega do Fleet Engine~~ (DESCONTINUADO) `roles/fleetengine.deliverySuperUser`	Concede permissão a todos os veículos de entrega e APIs de tarefas. Os tokens emitidos por uma conta de serviço com esse papel geralmente são usados nos seus servidores de back-end.
Leitor de frota de entrega do Fleet Engine `roles/fleetengine.deliveryFleetReader`	Concede permissão para ler tarefas e veículos de entrega e pesquisar tarefas usando um ID de acompanhamento. Os tokens gerados por uma conta de serviço com esse papel normalmente são usados no navegador da Web de um operador de frota de entrega.

As organizações que fornecem dispositivos gerenciados por TI corporativa podem aproveitar a flexibilidade oferecida pela função de usuário de motorista confiável do Fleet Engine e optar por integrar algumas ou todas as interações do Fleet Engine ao app para dispositivos móveis.

As organizações que oferecem suporte a políticas "Traga seu próprio dispositivo" precisam optar pela segurança da função de usuário de motorista não confiável do Fleet Engine e confiar apenas no app para dispositivos móveis para enviar atualizações de localização do veículo ao Fleet Engine. Todas as outras interações precisam ser originadas dos servidores de back-end do cliente.

Os SDKs do driver e do consumidor são criados com base nesses papéis padrão. No entanto, é possível criar papéis personalizados que permitam que um conjunto arbitrário de permissões seja agrupado. Os SDKs do driver e do consumidor vão exibir mensagens de erro quando uma permissão necessária estiver ausente. Como resultado, é altamente recomendável usar o conjunto padrão de papéis apresentado acima em vez de papéis personalizados.

Como criar uma conta de serviço

É possível criar uma conta de serviço usando a guia IAM & Admin > Service Accounts no Console do Google Cloud. Na lista suspensa "Papel", selecione "Mecanismo de frota" e atribua um dos papéis à conta de serviço. É recomendável indicar a conta associada a cada função. Por exemplo, dê um nome significativo à conta de serviço.

Por conveniência, se você precisar criar JWTs para clientes não confiáveis, adicione usuários ao papel de criador do token da conta de serviço para que eles criem tokens com as ferramentas de linha de comando gcloud.

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

Em que my-user@example.com é o e-mail usado para autenticação com a gcloud (gcloud auth list --format='value(account)').

Biblioteca de autenticação do Fleet Engine

O Fleet Engine usa JWTs para restringir o acesso às APIs do Fleet Engine em ambientes não confiáveis. A biblioteca de autenticação do Fleet Engine, disponível no GitHub, simplifica a construção de JWTs do Fleet Engine e os assina com segurança.

A biblioteca oferece os seguintes benefícios:

Simplifica o processo de criação de tokens do Fleet Engine.
Fornece mecanismos de assinatura de token que não usam arquivos de credenciais (como a representação de uma conta de serviço).

Criar um JSON Web Token (JWT) para autorização

Quando você não usa a biblioteca de autenticação do Fleet Engine, os JWTs precisam ser criados diretamente na sua base de código. Isso exige que você tenha um conhecimento profundo sobre os JWTs e a relação deles com o Fleet Engine. É por isso que recomendamos usar a biblioteca de autenticação do Fleet Engine.

No Fleet Engine, os JWTs oferecem autenticação de curta duração e garantem que os dispositivos só possam modificar veículos ou tarefas para os quais estão autorizados. Os JWTs contêm um cabeçalho e uma seção de declaração. A seção do cabeçalho contém informações como a chave privada a ser usada (recebida das 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 do token, o tempo de vida do token, os serviços aos quais o token está reivindicando acesso e outras informações de autorização para reduzir o escopo do acesso, por exemplo, o código do veículo de entrega.

Uma seção de cabeçalho JWT contém os seguintes campos:

Field	Descrição
`alg`	O algoritmo a ser usado. "RS256".
`typ`	O tipo de token. "JWT".
`kid`	ID da chave privada da conta de serviço. Esse valor está 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.

Uma seção de declarações JWT contém os seguintes campos:

Field	Descrição
`iss`	Endereço de e-mail da sua conta de serviço.
`sub`	Endereço de e-mail da sua 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 token foi criado, especificado em segundos desde 00:00:00 UTC, 1o de janeiro de 1970. Aguarde 10 minutos para o desvio. Se o carimbo de data/hora estiver muito no passado ou no futuro, o servidor poderá informar um erro.
`exp`	O carimbo de data/hora de expiração do token, especificado em segundos desde 00:00:00 UTC, 1o de janeiro de 1970. A solicitação falhará se o carimbo de data/hora tiver mais de uma hora no futuro.
`authorization`	Dependendo do caso de uso, pode conter "deliveryvehicleid", "trackingid", "taskid" ou "taskids".

Criar um token JWT se refere a assiná-lo. Para instruções e exemplos de código para criar e assinar o JWT, consulte Autorização da conta de serviço sem OAuth. Em seguida, é possível anexar um token gerado a chamadas gRPC ou outros métodos usados para acessar o Fleet Engine.

Declarações JWT

A Last Mile Fleet Solution usa reivindicações particulares. O uso de declarações particulares garante que apenas clientes autorizados possam acessar os próprios dados. Por exemplo, quando o back-end emite um JSON Web Token para o dispositivo móvel de um motorista de entrega, esse token precisa conter a declaração deliveryvehicleid com o valor do ID do veículo de entrega desse motorista. Em seguida, dependendo da função do motorista, os tokens permitem acesso apenas para o ID do veículo de entrega específico, e não para qualquer outro ID arbitrário.

A Last Mile Fleet Solution usa as seguintes reivindicações particulares:

deliveryvehicleid: use ao chamar APIs por veículo de entrega.
taskid: use ao chamar APIs por tarefa.
taskids: use ao chamar BatchCreateTasksAPI. Essa declaração precisa estar em formato de matriz, e a matriz precisa conter todos os IDs de tarefas necessários para concluir a solicitação. Não inclua declarações delivervehicleid, trackingid ou taskid.
trackingid: use ao chamar o GetTaskTrackingInfoAPI. A declaração precisa corresponder ao ID de acompanhamento na solicitação. Não inclua declarações delivervehicleid, taskid ou taskids.

O token também precisa conter a declaração apropriada quando você estiver chamando APIs do seu servidor de back-end, mas é possível usar o valor especial de um asterisco ("*") para declarações deliveryvehicleid, taskid e trackingid. O asterisco ("*") também pode ser usado na declaração taskids, mas precisa ser o único elemento na matriz.

Se você quiser 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 sobre Autorização da conta de serviço sem OAuth na documentação do desenvolvedor de identidade.

O mecanismo para anexar o token a uma chamada gRPC 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 de autorização com um token do portador cujo valor seja o token, conforme indicado nas notas de autorização para casos de uso individuais de rastreamento de envio ou desempenho de frota.

O exemplo a seguir mostra um token para uma operação por tarefa do seu 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": "*"
       }
    }

O exemplo a seguir mostra um token para uma operação de tarefas de criação em lote 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": ["*"]
       }
    }

O exemplo a seguir mostra um token para uma operação por veículo de entrega proveniente do seu 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": {
         "deliveryvehicleid": "*"
       }
    }

O exemplo a seguir mostra um token para clientes usuários finais:

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

O exemplo a seguir mostra um token para seu aplicativo de driver:

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

No campo kid do cabeçalho, especifique o ID da chave privada da conta de serviço. Esse valor está no campo private_key_id do arquivo JSON da conta de serviço.
Nos campos iss e sub, especifique o endereço de e-mail da sua conta de serviço. Esse valor está no campo client_email do arquivo JSON da conta de serviço.
No campo aud, especifique https://SERVICE_NAME/.
No campo iat, especifique o carimbo de data/hora em que o token foi criado, em segundos decorridos desde 00:00:00 UTC, 1o de janeiro de 1970. Aguarde 10 minutos para o desvio. Se o carimbo de data/hora estiver muito no passado ou no futuro, o servidor poderá informar um erro.
No campo exp, especifique o carimbo de data/hora de quando o token expira, em segundos, a partir de 1o de janeiro de 1970, 00:00:00 UTC. O valor recomendado é iat + 3.600.

Ao assinar o token que será transmitido para um dispositivo móvel ou usuário final, use o arquivo de credenciais para o papel de Motorista de entrega ou Consumidor. Caso contrário, o dispositivo móvel ou o usuário final poderá alterar ou visualizar informações às quais não deveria ter acesso.