Menandatangani permintaan secara digital dengan kunci API
Bergantung pada penggunaan Anda, tanda tangan digital - di samping kunci API - mungkin diperlukan untuk mengautentikasi permintaan. Lihat yang berikut ini artikel:
Cara kerja tanda tangan digital
Tanda tangan digital dibuat menggunakan rahasia penandatanganan URL, yang tersedia di Konsol Google Cloud. Rahasia ini pada dasarnya adalah kunci pribadi, yang hanya dibagikan antara Anda dan Google, dan bersifat unik untuk project Anda.
Proses penandatanganan menggunakan algoritma enkripsi untuk menggabungkan URL dan rahasia bersama milik Anda. Tanda tangan unik yang dihasilkan memungkinkan server kami memverifikasi bahwa situs yang membuat permintaan menggunakan kunci API Anda telah diberi otorisasi untuk melakukannya.
Membatasi permintaan yang tidak ditandatangani
Untuk memastikan kunci API Anda hanya menerima permintaan yang ditandatangani:
- Buka halaman Quotas Google Maps Platform di Konsol Cloud.
- Klik drop-down project dan pilih project yang sama yang Anda gunakan saat membuat kunci API untuk aplikasi atau situs Anda.
- Pilih Street View Static API dari drop-down API.
- Luaskan bagian Unsigned requests.
- Di tabel Quota Name, klik tombol edit di sebelah kuota yang ingin Anda edit. Misalnya, Unsigned requests per day.
- Perbarui Quota limit di panel Edit Quota Limit.
- Pilih Simpan.
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 Credentials Google Maps Platform di Konsol Cloud.
- Pilih drop-down project dan pilih project yang sama dengan yang Anda gunakan saat membuat kunci API untuk Street View Static API.
- Scroll ke bawah ke kartu Secret Generator. Kolom Current secret berisi rahasia penandatanganan URL Anda saat ini.
- Halaman ini juga menampilkan widget Sign a URL now yang memungkinkan Anda menandatangani secara otomatis permintaan Street View Static API menggunakan rahasia penandatanganan Anda saat ini. Scroll ke bawah ke kartu Sign a URL now untuk mengaksesnya.
Untuk mendapatkan rahasia penandatanganan URL baru, klik Regenerate Secret. Masa berlaku rahasia sebelumnya akan berakhir 24 jam setelah Anda membuat rahasia yang baru. Setelah 24 jam, permintaan yang berisi rahasia lama tidak akan berfungsi lagi.
Langkah 2: Buat permintaan yang tidak ditandatangani
Karakter yang tidak tercantum dalam tabel di bawah harus dienkode ke URL:
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. Untuk mengetahui petunjuknya, lihat dokumentasi developer berikut:
Pastikan Anda juga menyertakan kunci API dalam parameter key
. Contoh:
https://maps.googleapis.com/maps/api/streetview?location=Z%C3%BCrich&size=400x400&key=YOUR_API_KEY
Membuat permintaan yang ditandatangani
Untuk kasus penggunaan satu kali, seperti menghosting gambar Maps Static API atau Street View Static API sederhana pada halaman web, atau untuk memecahkan masalah, Anda dapat membuat tanda tangan digital secara otomatis menggunakan widget Sign a URL now 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/streetview?location=Z%C3%BCrich&size=400x400&key=YOUR_API_KEY
&signature=BASE64_SIGNATURE
Menggunakan widget Sign a URL now
Untuk membuat tanda tangan digital dengan kunci API menggunakan widget Sign a URL now di Konsol Google Cloud:
- Cari widget Sign a URL now, 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.
- Kolom Your Signed URL yang muncul akan berisi URL yang ditandatangani secara digital. Pastikan untuk membuat salinan.
Membuat tanda tangan digital sisi server
Dibandingkan dengan widget Sign a URL now, Anda harus melakukan beberapa langkah tambahan saat membuat tanda tangan digital sisi server:
-
Hapus bagian host dan skema protokol dari URL, sehingga hanya jalur dan kueri yang tersisa:
-
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.
-
Tambahkan tanda tangan yang dienkode menggunakan Base64 ke URL permintaan asli yang tidak ditandatangani di parameter
signature
. Contoh:https://maps.googleapis.com/maps/api/streetview?location=Z%C3%BCrich&size=400x400&key=YOUR_API_KEY &signature=BASE64_SIGNATURE
/maps/api/streetview?location=Z%C3%BCrich&size=400x400&key=YOUR_API_KEY
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 kemungkinan besar terjadi jika rahasia penandatanganan yang digunakan tidak ditautkan ke kunci API 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 kunci API menggunakan widget Sign a URL now di Konsol Google Cloud:
- Cari widget Sign a URL now, 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.
- Kolom Your Signed URL yang muncul akan berisi URL yang ditandatangani secara digital. Pastikan untuk membuat salinan.