Penandatanganan Permintaan Client ID

Penting: Paket Premium Google Maps Platform tidak lagi tersedia untuk pendaftar atau pelanggan baru.

Tanda tangan digital

Cara kerja tanda tangan digital

Tanda tangan digital dibuat menggunakan rahasia penandatanganan URL atau kunci kriptografis, yang tersedia di Konsol Google Cloud. Rahasia ini pada dasarnya adalah kunci pribadi, yang hanya dibagikan antara Anda dan Google, dan bersifat unik untuk client ID Anda.

Proses penandatanganan menggunakan algoritma enkripsi untuk menggabungkan URL dan rahasia bersama Anda. Tanda tangan unik yang dihasilkan memungkinkan server kami untuk memverifikasi bahwa situs yang membuat permintaan dengan menggunakan client ID Anda telah diberi otorisasi untuk melakukannya.

Menandatangani permintaan

Lakukan langkah-langkah berikut untuk menandatangani permintaan Anda:

Langkah 1: Dapatkan rahasia penandatanganan URL
Langkah 2: Buat permintaan yang tidak ditandatangani
Langkah 3: Buat permintaan yang ditandatangani

Langkah 1: Dapatkan rahasia penandatanganan URL

Untuk mendapatkan rahasia penandatanganan URL project Anda:

Buka halaman Client ID di Cloud Console.
Kolom Kunci berisi rahasia penandatanganan URL Client ID Anda saat ini.

Jika Anda perlu membuat ulang rahasia penandatanganan URL client ID, hubungi dukungan.

Langkah 2: Buat permintaan yang tidak ditandatangani

Karakter yang tidak tercantum dalam tabel di bawah harus dienkode ke URL:

Ringkasan Karakter URL yang Valid

Kumpulan	karakter	Penggunaan URL
Alfanumerik	a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9	String teks, penggunaan skema (`http`), port (`8080`), dll.
Tanpa fungsi khusus	- _ . ~	String teks
Dengan fungsi khusus	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	Karakter kontrol dan/atau String Teks

Hal yang sama berlaku untuk setiap karakter dalam kumpulan Dengan fungsi khusus, jika karakter tersebut diteruskan dalam string teks. Untuk info selengkapnya, lihat Karakter khusus.

Buat URL permintaan yang tidak ditandatangani tanpa tanda tangan.

Pastikan Anda juga menyertakan client ID dalam parameter client. Contoh:

https://maps.googleapis.com/maps/api/staticmap?center=Z%C3%BCrich&size=400x400&client=YOUR_CLIENT_ID

Membuat permintaan yang ditandatangani

Untuk tujuan pemecahan masalah, Anda dapat membuat tanda tangan digital secara otomatis menggunakan widget Tanda tangani URL sekarang yang tersedia.

Untuk permintaan yang dibuat secara dinamis, Anda membutuhkan penandatanganan sisi server, yang memerlukan beberapa langkah perantara tambahan

Apa pun langkah yang diambil, Anda akan membuat URL permintaan dengan parameter signature yang ditambahkan ke bagian akhir. Contoh:

https://maps.googleapis.com/maps/api/staticmap?center=Z%C3%BCrich&size=400x400&client=YOUR_CLIENT_ID
&signature=BASE64_SIGNATURE

Hapus bagian host dan skema protokol dari URL, sehingga hanya jalur dan kueri yang tersisa:

/maps/api/staticmap?center=Z%C3%BCrich&size=400x400&client=YOUR_CLIENT_ID

Rahasia penandatanganan URL yang ditampilkan dienkode menggunakan Base64 yang dimodifikasi untuk URL.

Karena sebagian besar library kriptografis memerlukan kunci dalam format byte mentah, Anda mungkin harus mendekode rahasia penandatanganan URL ke format mentah aslinya sebelum menandatangani.
Tanda tangani permintaan yang dihapus di atas menggunakan HMAC-SHA1.
Karena sebagian besar library kriptografis menghasilkan tanda tangan dalam format byte mentah, Anda harus mengonversi tanda tangan biner yang dihasilkan menggunakan Base64 yang dimodifikasi untuk URL agar tanda tangan tersebut dapat dikonversi menjadi sesuatu yang dapat yang diteruskan dalam URL.

Catatan: Base64 yang dimodifikasi untuk URL akan mengganti karakter + dan / dari Base64 standar dengan - dan _, sehingga semua Base64 ini tidak perlu lagi dienkode ke URL.
Tambahkan tanda tangan yang dienkode menggunakan Base64 ke URL permintaan asli yang tidak ditandatangani di parameter signature. Contoh:
```
https://maps.googleapis.com/maps/api/staticmap?center=Z%C3%BCrich&size=400x400&client=YOUR_CLIENT_ID
&signature=BASE64_SIGNATURE
```

Untuk contoh yang menunjukkan cara menerapkan penandatanganan URL menggunakan kode sisi server, lihat Kode contoh untuk penandatanganan URL di bawah.

Kode contoh untuk penandatanganan URL

Bagian berikut ini menunjukkan cara menerapkan penandatanganan URL menggunakan kode sisi server. URL harus selalu ditandatangani sisi server agar rahasia penandatanganan URL tidak dapat dilihat pengguna.

Python

Contoh di bawah ini menggunakan library Python standar untuk menandatangani URL. (Download kodenya.)

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

import hashlib
import hmac
import base64
import urllib.parse as 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, str.encode(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.decode()


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

Java

Contoh di bawah ini menggunakan class java.util.Base64 yang tersedia sejak JDK 1.8 - versi lama mungkin perlu menggunakan Apache Commons atau yang serupa. (Download kodenya.)

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;
  }
}

Node.js

Contoh di bawah ini menggunakan modul Node native untuk menandatangani URL. (Download kodenya.)

'use strict'

const crypto = require('crypto');
const url = require('url');

/**
 * Convert from 'web safe' base64 to true base64.
 *
 * @param  {string} safeEncodedString The code you want to translate
 *                                    from a web safe form.
 * @return {string}
 */
function removeWebSafe(safeEncodedString) {
  return safeEncodedString.replace(/-/g, '+').replace(/_/g, '/');
}

/**
 * Convert from true base64 to 'web safe' base64
 *
 * @param  {string} encodedString The code you want to translate to a
 *                                web safe form.
 * @return {string}
 */
function makeWebSafe(encodedString) {
  return encodedString.replace(/\+/g, '-').replace(/\//g, '_');
}

/**
 * Takes a base64 code and decodes it.
 *
 * @param  {string} code The encoded data.
 * @return {string}
 */
function decodeBase64Hash(code) {
  // "new Buffer(...)" is deprecated. Use Buffer.from if it exists.
  return Buffer.from ? Buffer.from(code, 'base64') : new Buffer(code, 'base64');
}

/**
 * Takes a key and signs the data with it.
 *
 * @param  {string} key  Your unique secret key.
 * @param  {string} data The url to sign.
 * @return {string}
 */
function encodeBase64Hash(key, data) {
  return crypto.createHmac('sha1', key).update(data).digest('base64');
}

/**
 * Sign a URL using a secret key.
 *
 * @param  {string} path   The url you want to sign.
 * @param  {string} secret Your unique secret key.
 * @return {string}
 */
function sign(path, secret) {
  const uri = url.parse(path);
  const safeSecret = decodeBase64Hash(removeWebSafe(secret));
  const hashedSignature = makeWebSafe(encodeBase64Hash(safeSecret, uri.path));
  return url.format(uri) + '&signature=' + hashedSignature;
}

C#

Contoh di bawah ini menggunakan library System.Security.Cryptography default untuk menandatangani permintaan URL. Perhatikan bahwa kita perlu mengonversi encoding Base64 default untuk mengimplementasikan versi aman untuk URL. (Download kodenya.)

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));
    }
  }
}

Contoh dalam bahasa lain

Contoh yang mencakup lebih banyak bahasa tersedia di project penandatanganan URL.

Pemecahan masalah

Jika permintaan menyertakan tanda tangan yang tidak valid, API akan menampilkan error HTTP 403 (Forbidden). Error ini kemungkinan besar terjadi jika rahasia penandatanganan yang digunakan tidak ditautkan ke client ID yang diteruskan, atau jika input non-ASCII tidak dienkode ke URL sebelum ditandatangani.

Untuk memecahkan masalah ini, salin URL permintaan, hapus parameter kueri signature, lalu buat ulang tanda tangan yang valid dengan mengikuti petunjuk di bawah:

Untuk membuat tanda tangan digital dengan client ID menggunakan widget Tanda tangani URL sekarang di bawah:

Ambil rahasia penandatanganan URL client ID Anda, seperti yang dijelaskan di Langkah 1: Dapatkan rahasia penandatanganan URL.
Di kolom URL, tempel URL permintaan yang tidak ditandatangani dari Langkah 2: Buat permintaan yang tidak ditandatangani.
Di kolom Rahasia Penandatanganan URL, tempel rahasia penandatanganan URL dari Langkah 2.
Tanda tangan digital dibuat, berdasarkan URL permintaan yang tidak ditandatangani dan rahasia penandatanganan Anda, serta ditambahkan ke URL asli Anda.
Kolom URL Bertanda Tangan Anda yang muncul akan berisi URL yang ditandatangani secara digital.