Autenticação e autorização

Esta página é destinada apenas a clientes que têm uma licença antiga do Maps APIs for Work ou do Maps API for Business. Esta página não se aplica a clientes com o novo Google Maps APIs Premium Plan, disponibilizado em janeiro de 2016.

IDs de cliente e assinaturas

Para clientes do Google Maps APIs for Work, as APIs de imagem (Static Maps API e Street View Image API) aceitam um ID de cliente e uma assinatura exclusiva para autenticação.

ID de cliente e assinatura

Ao usar as APIs de imagem com uma licença do Google Maps APIs for Work, são necessários dois parâmetros de autenticação além dos parâmetros padrão:

  • Seu Id de cliente. Para acessar os recursos especiais do Google Maps APIs for Work, você deve fornecer um ID de cliente ao acessar qualquer biblioteca ou serviço da API. Ao se cadastrar no Google Maps APIs for Work, você receberá este ID de cliente pelo Google Cloud Support Portal. Todos os IDs de cliente começam com um prefixo gme-. Passe o seu ID de cliente como o valor do parâmetro client.

  • Uma assinatura exclusiva, gerada usando a chave criptográfica privada. Passe essa assinatura como o valor do parâmetro signature. Veja abaixo mais informações sobre como gerar a assinatura, na seção sobre assinaturas digitais.

Static Maps API:

    <img src="https://maps.googleapis.com/maps/api/staticmap
      ?center=-15.800513,-47.91378
      &zoom=11
      &size=300x300
      &client=YOUR_CLIENT_ID
      &signature=SIGNATURE">

Street View Image API:

    <img src="https://maps.googleapis.com/maps/api/streetview
      ?location=40.720032,-73.988354
      &size=400x400
      &fov=90&heading=235&pitch=10
      &client=YOUR_CLIENT_ID
      &signature=SIGNATURE">

Não é permitido incluir um parâmetro key na solicitação.

Assinatura digitais para clientes do Google Maps APIs for Work

As solicitações de clientes do Google Maps APIs for Work às APIs de imagem exigem uma assinatura digital, gerada por meio de uma chave criptográfica privada fornecida a você no e-mail de boas-vindas.

O processo de assinatura combina um URL e a chave usando um algoritmo criptográfico. A assinatura única gerada permite que os nossos servidores verifiquem se os sites que geram solicitações usando seu ID de cliente têm autorização para fazê-lo. A assinatura também é exclusiva por URL, garantindo que as solicitações que usam seu ID de cliente não possam ser modificadas sem exigir a geração de uma nova assinatura.

Sua chave criptográfica privada

A chave criptográfica de assinatura de URL privada será emitida com seu ID de cliente e é uma “chave secreta compartilhada” entre você e a Google. Essa chave de assinatura é somente sua e é exclusiva para o seu ID de cliente. Por isso, mantenha-a confidencial. Essa chave não deve ser passada dentro de solicitações, armazenada em sites nem postada em fórum público. Qualquer pessoa que tiver em mãos essa chave de assinatura pode fazer solicitações usando a sua identidade.

Observação: Essa chave criptográfica de assinatura privada não é igual às chaves de API emitidas pelo Google API Console.

Caso tenha perdido sua chave criptográfica privada, acesse o Google Cloud Support Portal e clique em Maps: Manage Client ID para recuperá-la.

Gerar uma assinatura digital

Tentar acessar as APIs de imagem com uma assinatura inválida resultará em um erro HTTP 403 (acesso negado). Ao converter aplicativos para usar a assinatura de URL, não deixe de testar as assinaturas para garantir que eles iniciem uma solicitação válida. Mas antes, você deve verificar se o URL original é válido e se você gerou as assinaturas corretas.

Siga estas etapas para criar uma assinatura digital para sua solicitação:

  1. Gere o URL da solicitação sem a assinatura, sem esquecer de incluir o parâmetro client. Observe que todo caractere não padrão precisará ser codificado para URL:

    Static Maps API: https://maps.googleapis.com/maps/api/staticmap?center=40.714%2c%20-73.998&zoom=12&size=400x400&client=clientID

    Street View Image API: https://maps.googleapis.com/maps/api/streetview?location=41.403609,2.174448&size=456x456&client=clientID

    Observação: todos os serviços do Google exigem a codificação de caracteres UTF-8 (que inclui ASCII implicitamente). Se seus aplicativos operarem usando outros conjuntos de caracteres, gere os URLs usando UTF-8 e codifique-os para URL.

  2. Remova a parte do domínio da solicitação, deixando apenas o caminho e a consulta:

    Static Maps API: /maps/api/staticmap?center=40.714%2c%20-73.998&zoom=12&size=400x400&client=clientID

    Street View Image API: /maps/api/streetview?location=41.403609,2.174448&size=456x456&client=clientID

  3. Recupere sua chave privada, que é codificada em Base64 modificado para URLs, e assine o URL acima usando o algoritmo HMAC-SHA1. Pode ser necessário decodificar essa chave no formato binário original dela. Observe que, na maioria das bibliotecas criptográficas, a assinatura gerada estará em formato binário.

    Observação: a Base64 modificada para URLs substitui os caracteres + e / da Base64 padrão por - e _, respectivamente, para que essas assinaturas Base64 não precisem mais de codificação para URL.

  4. Codifique a assinatura binária resultante usando a Base64 modificada para URLs para convertê-la em algo que possa ser passado em um URL.

  5. Vincule essa assinatura ao URL dentro de um parâmetro signature:

    Static Maps API:https://maps.googleapis.com/maps/api/staticmap?center=40.714%2c%20-73.998&zoom=12&size=400x400&client=clientID&signature=base64signature

    Street View Image API:https://maps.googleapis.com/maps/api/streetview?location=41.403609,2.174448&size=456x456&client=clientID&signature=base64signature

Para ver exemplos de formas de se implementar assinatura de URL usando código no servidor, veja Exemplo de código para assinatura de URL.

Exemplo de código para assinatura de URL

As seções a seguir mostram como implementar a assinatura de URL usando código de servidor. URLs devem ser sempre assinados no servidor para evitar a exposição da sua chave criptográfica para os usuários.

Python

O exemplo abaixo usa bibliotecas Python padrão para assinar um URL. (Faça o download do código.)

#!/usr/bin/python
# -*- coding: utf-8 -*-
""" Signs a URL using a URL signing secret """

import hashlib
import hmac
import base64
import urlparse

def sign_url(input_url=None, secret=None):
  """ Sign a request URL with a URL signing secret.

      Usage:
      from urlsigner import sign_url

      signed_url = sign_url(input_url=my_url, secret=SECRET)

      Args:
      input_url - The URL to sign
      secret    - Your URL signing secret

      Returns:
      The signed request URL
  """

  if not input_url or not secret:
    raise Exception("Both input_url and secret are required")

  url = urlparse.urlparse(input_url)

  # We only need to sign the path+query part of the string
  url_to_sign = url.path + "?" + url.query

  # Decode the private key into its binary format
  # We need to decode the URL-encoded private key
  decoded_key = base64.urlsafe_b64decode(secret)

  # Create a signature using the private key and the URL-encoded
  # string using HMAC SHA1. This signature will be binary.
  signature = hmac.new(decoded_key, url_to_sign, hashlib.sha1)

  # Encode the binary signature into base64 for use within a URL
  encoded_signature = base64.urlsafe_b64encode(signature.digest())

  original_url = url.scheme + "://" + url.netloc + url.path + "?" + url.query

  # Return signed URL
  return original_url + "&signature=" + encoded_signature

if __name__ == "__main__":
  input_url = raw_input("URL to Sign: ")
  secret = raw_input("URL signing secret: ")
  print "Signed URL: " + sign_url(input_url, secret)

Java

O exemplo abaixo usa a classe java.util.Base64 disponível desde o JDK 1.8. Versões mais antigas podem precisar usar o Apache Commons ou similar. (Faça o download do código.)

import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.net.URI;
import java.net.URISyntaxException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;  // JDK 1.8 only - older versions may need to use Apache Commons or similar.
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;

public class UrlSigner {

  // Note: Generally, you should store your private key someplace safe
  // and read them into your code

  private static String keyString = "YOUR_PRIVATE_KEY";
  
  // The URL shown in these examples is a static URL which should already
  // be URL-encoded. In practice, you will likely have code
  // which assembles your URL from user or web service input
  // and plugs those values into its parameters.
  private static String urlString = "YOUR_URL_TO_SIGN";

  // This variable stores the binary key, which is computed from the string (Base64) key
  private static byte[] key;
  
  public static void main(String[] args) throws IOException,
    InvalidKeyException, NoSuchAlgorithmException, URISyntaxException {
    
    BufferedReader input = new BufferedReader(new InputStreamReader(System.in));
    
    String inputUrl, inputKey = null;

    // For testing purposes, allow user input for the URL.
    // If no input is entered, use the static URL defined above.    
    System.out.println("Enter the URL (must be URL-encoded) to sign: ");
    inputUrl = input.readLine();
    if (inputUrl.equals("")) {
      inputUrl = urlString;
    }
    
    // Convert the string to a URL so we can parse it
    URL url = new URL(inputUrl);
 
    // For testing purposes, allow user input for the private key.
    // If no input is entered, use the static key defined above.   
    System.out.println("Enter the Private key to sign the URL: ");
    inputKey = input.readLine();
    if (inputKey.equals("")) {
      inputKey = keyString;
    }
    
    UrlSigner signer = new UrlSigner(inputKey);
    String request = signer.signRequest(url.getPath(),url.getQuery());
    
    System.out.println("Signed URL :" + url.getProtocol() + "://" + url.getHost() + request);
  }
  
  public UrlSigner(String keyString) throws IOException {
    // Convert the key from 'web safe' base 64 to binary
    keyString = keyString.replace('-', '+');
    keyString = keyString.replace('_', '/');
    System.out.println("Key: " + keyString);
    // Base64 is JDK 1.8 only - older versions may need to use Apache Commons or similar.
    this.key = Base64.getDecoder().decode(keyString);
  }

  public String signRequest(String path, String query) throws NoSuchAlgorithmException,
    InvalidKeyException, UnsupportedEncodingException, URISyntaxException {
    
    // Retrieve the proper URL components to sign
    String resource = path + '?' + query;
    
    // Get an HMAC-SHA1 signing key from the raw key bytes
    SecretKeySpec sha1Key = new SecretKeySpec(key, "HmacSHA1");

    // Get an HMAC-SHA1 Mac instance and initialize it with the HMAC-SHA1 key
    Mac mac = Mac.getInstance("HmacSHA1");
    mac.init(sha1Key);

    // compute the binary signature for the request
    byte[] sigBytes = mac.doFinal(resource.getBytes());

    // base 64 encode the binary signature
    // Base64 is JDK 1.8 only - older versions may need to use Apache Commons or similar.
    String signature = Base64.getEncoder().encodeToString(sigBytes);
    
    // convert the signature to 'web safe' base 64
    signature = signature.replace('+', '-');
    signature = signature.replace('/', '_');
    
    return resource + "&signature=" + signature;
  }
}

C#

O exemplo abaixo usa a biblioteca System.Security.Cryptography padrão para assinar uma solicitação de URL. Observe que é preciso converter a codificação Base64 padrão para implementar uma versão compatível com URL. (Faça o download do código.)

using System;
using System.Collections.Generic;
using System.Security.Cryptography;
using System.Text;
using System.Text.RegularExpressions;
using System.Web;

namespace SignUrl {

  public struct GoogleSignedUrl {

    public static string Sign(string url, string keyString) {
      ASCIIEncoding encoding = new ASCIIEncoding();

      // converting key to bytes will throw an exception, need to replace '-' and '_' characters first.
      string usablePrivateKey = keyString.Replace("-", "+").Replace("_", "/");
      byte[] privateKeyBytes = Convert.FromBase64String(usablePrivateKey);

      Uri uri = new Uri(url);
      byte[] encodedPathAndQueryBytes = encoding.GetBytes(uri.LocalPath + uri.Query);

      // compute the hash
      HMACSHA1 algorithm = new HMACSHA1(privateKeyBytes);
      byte[] hash = algorithm.ComputeHash(encodedPathAndQueryBytes);

      // convert the bytes to string and make url-safe by replacing '+' and '/' characters
      string signature = Convert.ToBase64String(hash).Replace("+", "-").Replace("/", "_");
            
      // Add the signature to the existing URI.
      return uri.Scheme+"://"+uri.Host+uri.LocalPath + uri.Query +"&signature=" + signature;
    }
  }

  class Program {

    static void Main() {
    
      // Note: Generally, you should store your private key someplace safe
      // and read them into your code

      const string keyString = "YOUR_PRIVATE_KEY";
  
      // The URL shown in these examples is a static URL which should already
      // be URL-encoded. In practice, you will likely have code
      // which assembles your URL from user or web service input
      // and plugs those values into its parameters.
      const  string urlString = "YOUR_URL_TO_SIGN";
      
      string inputUrl = null;
      string inputKey = null;
    
      Console.WriteLine("Enter the URL (must be URL-encoded) to sign: ");
      inputUrl = Console.ReadLine();
      if (inputUrl.Length == 0) {
        inputUrl = urlString;
      }     
    
      Console.WriteLine("Enter the Private key to sign the URL: ");
      inputKey = Console.ReadLine();
      if (inputKey.Length == 0) {
        inputKey = keyString;
      }
      
      Console.WriteLine(GoogleSignedUrl.Sign(inputUrl,inputKey));
    }
  }
}

Solucionar problemas de autenticação

Se sua solicitação for inválida ou fornecer uma assinatura inválida, a API de imagem retornará um erro HTTP 403 (acesso negado).

Para solucionar os problemas de URLs individuais, use o depurador de assinaturas de URL. Ele permite que você valide rapidamente o URL e a assinatura gerada por seu aplicativo.

Como alternativa, os clientes do Google Maps APIs for Work podem resolver problemas de URLs específicos acessando o Google Cloud Support Portal e selecionando Resources > Google Maps APIs for Work online tools > URL Signing Debugger for Web Service and Image APIs.