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

Esta seção explica os conceitos de autenticação e autorização com em relação à integração com o Fleet Engine.

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

Visão geral

Os back-ends do cliente que autenticam e autorizam no Fleet Engine devem usar padrão Application Default Credenciais de segurança.

O Fleet Engine também recebe chamadas originadas de ambientes de baixa confiança como smartphones e navegadores. Para proteger apenas chaves secretas da conta de serviço adequados para ambientes confiáveis, espera-se que os back-ends gerem JSON Web Tokens (JWT) assinado com outras declarações específicas do Fleet Engine que podem ser emitidos 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 conjunto de permissões nos recursos permitidos para um principal. Por exemplo, o Os papéis de administrador têm permissão para fazer tudo com o padrão do aplicativo As credenciais, enquanto o papel de driver não confiável* só pode ser atualizado local de veículos 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 que o sobre o qual o autor da chamada possa 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 no seu 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 para um recurso:
1. O principal de chamada tem as permissões apropriadas (pelo papel atribuição) para a ação no recurso.
2. Para papéis não administradores, as declarações JWT transmitidas na solicitação fornecem o 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 Application Default Credentials.
O app cliente solicita um JWT do back-end do cliente. O requerente poderia do motorista, do consumidor ou de monitoramento.
O back-end do cliente assina e emite um JWT para o respectivo serviço do Compute Engine. O app cliente recebe o JWT.
O app cliente usa o JWT para se conectar ao Fleet Engine para leitura ou modificação dados, dependendo dos papéis do IAM atribuídos durante a fase de configuração.

Diagrama de sequência de autenticação

Configuração do projeto do Cloud

Para configurar seu projeto na nuvem, primeiro crie seu projeto e depois criar 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 obrigatório ().

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

Papel	Descrição
Usuário 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 da tarefa ou resultado. Tokens criados por uma conta de serviço com este papel normalmente são usados nos dispositivos móveis do motorista ou no nos servidores de back-end.
Usuário de driver não confiável de entrega do Fleet Engine `roles/fleetengine.deliveryUntrustedDriver`	Concede permissão para atualizar o local do veículo de entrega. Tokens criados por uma conta de serviço com esse papel geralmente são usados na sua entrega e os dispositivos móveis dos motoristas.
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. Tokens criados por uma conta de serviço com esse papel geralmente são usadas em uma navegador da Web do cliente.
Administrador de entrega do Fleet Engine `roles/fleetengine.deliveryAdmin`	Concede permissão de leitura e gravação para recursos de entrega. Diretores com esse papel não precisam usar JWTs. Em vez disso, devem usar Default Credentials. As declarações JWT personalizadas são ignoradas. Esse papel deve ser restritos 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. Tokens criados por uma conta de serviço com esse papel geralmente são usadas no back-end servidores.
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. Tokens criados por uma conta de serviço com este função normalmente são usadas no navegador da Web de um operador de frota de entregas.

Organizações que fornecem aos entregadores dispositivos gerenciados por a TI corporativa pode aproveitar a flexibilidade oferecida pelo Fleet Engine Função de Usuário de Motorista Confiável e optar por integrar parte ou todo o Fleet Engine e interações no app para dispositivos móveis.

Organizações que oferecem suporte a políticas de "Traga seu próprio dispositivo" devem optar pela da função de motorista não confiável do Fleet Engine e contar apenas com o app para dispositivos móveis que envie atualizações de localização do veículo ao Fleet Engine. Todos os outros as interações devem se originar 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 permitem que um conjunto arbitrário de permissões seja agrupado. Os SDKs do driver e do consumidor vão exibir mensagens de erro quando um a permissão necessária está ausente. Por isso, é altamente recomendável usando 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 o IAM & Admin > Service Accounts no console do Google Cloud. Na lista suspensa Papel, selecione Fleet Engine e atribuir um dos papéis à conta de serviço. É bom para indicar a conta associada a cada função. Por exemplo, dê um nome significativo à conta de serviço.

Para facilitar, se você precisar criar JWTs para clientes não confiáveis, adicionar os usuários ao papel de criador de token da conta de serviço permite 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 autenticar 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 e ambientes de teste. A biblioteca de autenticação do Fleet Engine, disponível na GitHub, simplifica a construção de JWTs do Fleet Engine e assiná-los 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 diferentes do uso de arquivos de credenciais (como representar uma conta de serviço.

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

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

No Fleet Engine, os JWTs oferecem autenticação de curta duração e garantir que os dispositivos modifiquem apenas veículos ou tarefas que tem autorização para isso. 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 chave privada a ser usada (recebida de contas de serviço) e a criptografia algoritmo. A seção "Claim" contém informações como o horário de criação do token, o time to live (TTL) e os serviços aos quais o token é reivindicar acesso e outras informações de autorização para reduzir o escopo; acesso por exemplo, o ID do veículo de entrega.

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

Campo	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. É possível encontrar 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.

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

Campo	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`	Carimbo de data/hora em que o token foi criado, especificado em segundos decorridos desde 00:00:00 UTC, 1o de janeiro de 1970. Aguarde 10 minutos para o desvio. Se o o carimbo de data/hora estiver muito distante no passado ou no futuro, o servidor poderá informar um erro.
`exp`	Carimbo de data/hora de expiração do token, especificado em segundos decorridos desde 00:00:00 UTC, 1o de janeiro de 1970. A solicitação falhará se o carimbo de data/hora for 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. Depois, é 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 reivindicações particulares garante que apenas autorizados possam acessar os próprios dados. Por exemplo, quando seu back-end emitir um JSON Web Token para o dispositivo móvel de um motorista de entrega, esse token deverá conter a declaração deliveryvehicleid com o valor da entrega do motorista. ID do veículo. Depois, dependendo da função do motorista, os tokens permitem acesso apenas para o ID do veículo para envio específico e nenhum 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. Esta reivindicação deve ser em forma de matriz, que deve conter todos os IDs de tarefas necessários para concluir a solicitação. Não inclua delivervehicleid, trackingid ou taskid reivindicações.
trackingid: use ao chamar o GetTaskTrackingInfoAPI. A reivindicação deve correspondem ao ID de acompanhamento na solicitação. Não inclua delivervehicleid, taskid ou taskids reivindicações.

O token também precisa conter a declaração adequada quando você chama APIs do servidor de back-end, mas é possível usar o valor especial de um asterisco, ("*") para reivindicaçõ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 portador de token, em vez de usando tokens de acesso do OAuth 2.0, leia as instruções 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 a estrutura usada para fazer a chamada. Mecanismo para especificar um token a uma chamada HTTP é incluir um cabeçalho de autorização com um token do portador cujo valor é o token, conforme observado nas notas de autorização para usuários rastreamento de envio ou desempenho da frota em diferentes casos de uso de negócios.

O exemplo a seguir mostra um token para uma operação por tarefa da sua 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 criação de tarefas em lote da sua 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 da 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 campo privado o ID da chave. Esse valor está no campo private_key_id da 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 da sua conta de serviço arquivo JSON.
No campo aud, especifique https://SERVICE_NAME/.
No campo iat, especifique o carimbo de data/hora de quando o token foi criado. em segundos desde 1o de janeiro de 1970, às 00:00:00 UTC. Aguarde 10 minutos quanto a distorção. Se o carimbo de data/hora estiver muito no passado ou no futuro, o de rede pode informar um erro.
No campo exp, especifique o carimbo de data/hora de quando o token expira. em segundos desde 01:00:00 UTC, 1o de janeiro de 1970. O valor recomendado é iat + 3.600.

Ao assinar o token que será transmitido para um dispositivo móvel ou usuário final, verifique se para usar o arquivo de credenciais do 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 podem ter acesso.