Usa cookie firmati

Questa pagina fornisce una panoramica dei cookie firmati e le istruzioni per utilizzarli con Cloud CDN. I cookie firmati consentono un accesso limitato alle risorse per un insieme di file, indipendentemente dal fatto che gli utenti dispongano di Account Google.

I cookie firmati sono un'alternativa agli URL firmati, che proteggono l'accesso quando è possibile firmare separatamente decine o centinaia di URL per ogni utente nella tua applicazione.

I cookie firmati ti consentono di:

• Autorizza un utente e fornisci un token limitato nel tempo per accedere ai tuoi contenuti protetti (anziché firmare ogni URL).
• Specifica l'accesso dell'utente a un prefisso URL specifico, ad esempio https://media.example.com/videos/, e concedi all'utente autorizzato l'accesso ai contenuti protetti solo all'interno di quel prefisso dell'URL.
• Mantieni invariati gli URL e i manifest multimediali, semplificando la pipeline per la pacchettizzazione e migliorando l'inserimento nella cache.

Se vuoi limitare l'accesso a URL specifici, valuta la possibilità di utilizzare gli URL firmati.

Prima di iniziare

Prima di utilizzare i cookie firmati, procedi nel seguente modo:

• Assicurati che Cloud CDN sia abilitato; per le istruzioni, consulta Utilizzo di Cloud CDN. Puoi configurare i cookie firmati su un backend prima di abilitare Cloud CDN, ma non ci sarà alcun effetto finché Cloud CDN non verrà abilitato.

• Se necessario, esegui l'aggiornamento alla versione più recente di Google Cloud CLI:

  gcloud components update
  

Per una panoramica, consulta l'articolo URL firmati e cookie firmati.

Configurazione delle chiavi di richiesta firmate

La creazione di chiavi per gli URL o i cookie firmati richiede diversi passaggi, descritti nelle sezioni seguenti.

Considerazioni sulla sicurezza

Importante: devi configurare i server web di origine per convalidare le firme su ogni richiesta firmata pubblicata e accettare o rifiutare le richieste non firmate.

Cloud CDN non convalida le richieste nelle seguenti circostanze:

• La richiesta non è firmata.
• Cloud CDN non è abilitato nel servizio o nel bucket di backend per la richiesta.

Le richieste firmate devono essere sempre convalidate all'origine prima di fornire la risposta. Questo perché le origini possono essere utilizzate per fornire una combinazione di contenuti firmati e non firmati e perché un client potrebbe accedere direttamente all'origine.

• Cloud CDN non blocca le richieste senza un parametro di query Signature o un cookie HTTP Cloud-CDN-Cookie. Rifiuta le richieste con parametri non validi (o con un formato non corretto).
• Quando l'applicazione rileva una firma non valida, assicurati che risponda con un codice di risposta HTTP 403 (Unauthorized). I codici di risposta di HTTP 403 non possono essere inseriti nella cache.
• Le risposte alle richieste firmate e non firmate vengono memorizzate separatamente nella cache, quindi una risposta corretta a una richiesta firmata valida non viene mai utilizzata per gestire una richiesta non firmata.
• Se l'applicazione invia un codice di risposta memorizzabile nella cache a una richiesta non valida, le richieste future valide potrebbero essere rifiutate erroneamente.

Per i backend Cloud Storage, assicurati di rimuovere l'accesso pubblico in modo che Cloud Storage possa rifiutare le richieste prive di una firma valida.

La seguente tabella riassume il comportamento.

La richiesta ha la firma	Hit della cache	Comportamento
No	No	Inoltra all'origine del backend.
No	Sì	Pubblica dalla cache.
Sì	No	Convalida la firma. Se valido, inoltra all'origine del backend.
Sì	Sì	Convalida la firma. Se valida, pubblica dalla cache.

Crea chiavi di richiesta firmate

Puoi attivare il supporto per gli URL e i cookie firmati Cloud CDN creando una o più chiavi su un servizio di backend, un bucket di backend o entrambi abilitati per Cloud CDN.

Per ogni servizio o bucket di backend, puoi creare ed eliminare chiavi in base alle esigenze di sicurezza. Ogni backend può avere fino a tre chiavi configurate alla volta. Ti consigliamo di ruotare periodicamente le chiavi eliminando quella meno recente, aggiungendone una nuova e utilizzando la nuova quando firma URL o cookie.

Puoi utilizzare lo stesso nome di chiave in più servizi e bucket di backend perché ogni set di chiavi è indipendente dagli altri. I nomi delle chiavi possono contenere fino a 63 caratteri. Per assegnare un nome alle chiavi, utilizza i caratteri A-Z, a-z, 0-9, _ (trattino basso) e - (trattino).

Quando crei chiavi, assicurati di mantenerle al sicuro poiché chiunque ne abbia una può creare URL firmati o cookie firmati accettati da Cloud CDN fino a quando la chiave non viene eliminata da Cloud CDN. Le chiavi vengono memorizzate sul computer in cui generi gli URL o i cookie firmati. Cloud CDN archivia anche le chiavi per verificare le firme delle richieste.

Per mantenere segrete le chiavi, i valori delle chiavi non vengono inclusi nelle risposte alle richieste API. Se perdi una chiave, devi crearne una nuova.

Importante: mantieni privato il file della chiave generato e non esporlo agli utenti né archiviarlo direttamente nel codice sorgente. Valuta l'utilizzo di un meccanismo di archiviazione dei secret come Cloud Key Management Service per criptare la chiave e fornire l'accesso solo alle applicazioni attendibili.

Per creare una chiave di richiesta firmata, segui questi passaggi.

Console

1. Nella console Google Cloud, vai alla pagina Cloud CDN.

   Vai a Cloud CDN

2. Fai clic sul nome dell'origine a cui vuoi aggiungere la chiave.
3. Nella pagina Dettagli origine, fai clic sul pulsante Modifica.
4. Nella sezione Nozioni di base sull'origine, fai clic su Avanti per aprire la sezione Regole host e percorso.
5. Nella sezione Regole host e percorso, fai clic su Avanti per aprire la sezione Prestazioni della cache.
6. Nella sezione Contenuti con limitazioni, seleziona Limita l'accesso utilizzando URL firmati e cookie firmati.

7. Fai clic su Aggiungi chiave di firma.

   1. Specifica un nome univoco per la nuova chiave di firma.

   2. Nella sezione Metodo di creazione chiave, seleziona Genera automaticamente. In alternativa, fai clic su Fammi entrare, poi specifica una coppia chiave-valore di firma.

      Per la prima opzione, copia la coppia chiave-valore di firma generata automaticamente in un file privato, che puoi utilizzare per creare URL firmati.

   3. Fai clic su Fine.

   4. Nella sezione Età massima delle voci di cache, inserisci un valore e seleziona un'unità di tempo.

8. Fai clic su Fine.

gcloud

Lo strumento a riga di comando gcloud legge le chiavi da un file locale specificato. Il file della chiave deve essere creato generando 128 bit altamente casuali, codificandoli con base64, quindi sostituendo il carattere + con - e sostituendo il carattere / con _. Per ulteriori informazioni, consulta il documento RFC 4648. È fondamentale che la chiave sia fortemente casuale. In un sistema simile a UNIX, puoi generare una chiave fortemente casuale e archiviarla nel file della chiave con il seguente comando:

head -c 16 /dev/urandom | base64 | tr +/ -_ > KEY_FILE_NAME

Per aggiungere la chiave a un servizio di backend:

gcloud compute backend-services \
   add-signed-url-key BACKEND_NAME \
   --key-name KEY_NAME \
   --key-file KEY_FILE_NAME

Per aggiungere la chiave a un bucket di backend:

gcloud compute backend-buckets \
   add-signed-url-key BACKEND_NAME \
   --key-name KEY_NAME \
   --key-file KEY_FILE_NAME

Nota: anche se il sottocomando è add-signed-url-key, la chiave è una chiave di richiesta firmata che funziona sia per i cookie firmati sia per gli URL firmati.

Configura le autorizzazioni di Cloud Storage

Se utilizzi Cloud Storage e hai limitato l'accesso alla lettura degli oggetti, devi concedere a Cloud CDN l'autorizzazione per leggere gli oggetti aggiungendo l'account di servizio Cloud CDN agli ACL di Cloud Storage.

Non è necessario creare l'account di servizio. L'account di servizio viene creato automaticamente la prima volta che aggiungi una chiave a un bucket di backend in un progetto.

Prima di eseguire il comando seguente, aggiungi almeno una chiave a un bucket di backend nel tuo progetto. In caso contrario, il comando ha esito negativo e restituisce un errore perché l'account di servizio di riempimento della cache di Cloud CDN non viene creato finché non aggiungi una o più chiavi per il progetto. Sostituisci PROJECT_NUM con il numero di progetto e BUCKET con il bucket di archiviazione.

Nota: se nel progetto è presente un criterio dell'organizzazione per la condivisione limitata ai domini (DRS), devi disabilitarlo prima di eseguire il comando gsutil iam ch. Assicurati di riabilitare il criterio dopo aver eseguito il comando gsutil iam ch.

gsutil iam ch \
  serviceAccount:[e-mail]:objectViewer \
  gs://BUCKET

L'account di servizio Cloud CDN [e-mail] non compare nell'elenco degli account di servizio del tuo progetto. Questo perché l'account di servizio Cloud CDN è di proprietà di Cloud CDN, non del tuo progetto.

Per ulteriori informazioni sui numeri di progetto, consulta Individuare l'ID e il numero del progetto nella documentazione della guida della console Google Cloud.

Personalizza il tempo massimo della cache

Cloud CDN memorizza nella cache le risposte per le richieste firmate indipendentemente dall'intestazione Cache-Control del backend. Il tempo massimo per cui le risposte possono essere memorizzate nella cache senza riconvalida è impostato dal flag signed-url-cache-max-age, che il valore predefinito è un'ora e può essere modificato come mostrato qui.

Per impostare il tempo massimo per la cache per un servizio di backend o un bucket di backend, esegui uno dei seguenti comandi:

gcloud compute backend-services update BACKEND_NAME
  --signed-url-cache-max-age MAX_AGE

gcloud compute backend-buckets update BACKEND_NAME
  --signed-url-cache-max-age MAX_AGE

Elenca i nomi delle chiavi di richiesta firmata

Per elencare le chiavi in un servizio di backend o in un bucket di backend, esegui uno dei seguenti comandi:

gcloud compute backend-services describe BACKEND_NAME

gcloud compute backend-buckets describe BACKEND_NAME

Elimina chiavi di richiesta firmate

Quando gli URL firmati da una determinata chiave non devono più essere rispettati, esegui uno dei seguenti comandi per eliminare la chiave dal servizio di backend o dal bucket di backend:

gcloud compute backend-services \
   delete-signed-url-key BACKEND_NAME --key-name KEY_NAME

gcloud compute backend-buckets \
   delete-signed-url-key BACKEND_NAME --key-name KEY_NAME

Creazione di un criterio

Le norme per i cookie firmati sono una serie di coppie key-value (delimitate dal carattere :), simili ai parametri di ricerca utilizzati in un URL firmato. Ad esempio, consulta la sezione Emettere cookie agli utenti.

I criteri rappresentano i parametri per i quali una richiesta è valida. I criteri vengono firmati utilizzando un codice HMAC (Hash-based Message Authentication Code) convalidato da Cloud CDN in ogni richiesta.

Definizione del formato e dei campi del criterio

Devi definire quattro campi obbligatori nel seguente ordine:

• URLPrefix
• Expires
• KeyName
• Signature

Le coppie key-value in un criterio relativo ai cookie firmati sono sensibili alle maiuscole.

URLPrefix

URLPrefix indica un prefisso URL codificato in base64 con protezione dell'URL che comprende tutti i percorsi per i quali deve essere valida la firma.

Un elemento URLPrefix codifica uno schema (http:// o https://), un nome di dominio completo e un percorso facoltativo. La fine del percorso con / è facoltativa, ma consigliata. Il prefisso non deve includere parametri di ricerca o frammenti come ? o #.

Ad esempio, https://media.example.com/videos associa le richieste a entrambi i seguenti casi:

• https://media.example.com/videos?video_id=138183&user_id=138138
• https://media.example.com/videos/137138595?quality=low

Il percorso del prefisso viene utilizzato come sottostringa di testo, non strettamente come percorso della directory. Ad esempio, il prefisso https://example.com/data concede l'accesso a entrambi i servizi seguenti:

• /data/file1
• /database

Per evitare l'errore, ti consigliamo di terminare tutti i prefissi con /, a meno che tu non scelga intenzionalmente di terminare il prefisso con un nome file parziale, come https://media.example.com/videos/123, per concedere l'accesso a quanto segue:

• /videos/123_chunk1
• /videos/123_chunk2
• /videos/123_chunkN

Se l'URL richiesto non corrisponde a URLPrefix, Cloud CDN rifiuta la richiesta e restituisce un errore HTTP 403 al client.

Scadenza

Expires deve essere un timestamp Unix (il numero di secondi dal 1° gennaio 1970).

KeyName

KeyName è il nome della chiave creata nel bucket di backend o nel servizio di backend. I nomi delle chiavi sono sensibili alle maiuscole.

Firma

Signature è la firma HMAC-SHA-1 codificata in Base64 con protezione dell'URL dei campi che costituiscono le norme relative ai cookie. Questa operazione viene convalidata per ogni richiesta; le richieste con firma non valida vengono rifiutate con un errore HTTP 403.

Creare cookie firmati a livello di programmazione

I seguenti esempi di codice mostrano come creare in modo programmatico cookie firmati.

Nota: valuta la possibilità di utilizzare Secret Manager per gestire l'accesso alle chiavi di firma.

Nota: i componenti host e percorso di URLPrefix vengono utilizzati per convalidare le firme. Quando fornisci il valore URLPrefix alle API di pubblicità programmatica, ometti la porta. In altre parole, per un percorso come https://example.com:443/path/, specifica il percorso come https://example.com/path/. In caso contrario, la firma generata non corrisponderà al valore calcolato da Cloud CDN.

Go

import (
	"crypto/hmac"
	"crypto/sha1"
	"encoding/base64"
	"fmt"
	"io"
	"io/ioutil"
	"net/http"
	"os"
	"time"
)

// signCookie creates a signed cookie for an endpoint served by Cloud CDN.
//
// - urlPrefix must start with "https://" and should include the path prefix
// for which the cookie will authorize access to.
// - key should be in raw form (not base64url-encoded) which is
// 16-bytes long.
// - keyName must match a key added to the backend service or bucket.
func signCookie(urlPrefix, keyName string, key []byte, expiration time.Time) (string, error) {
	encodedURLPrefix := base64.URLEncoding.EncodeToString([]byte(urlPrefix))
	input := fmt.Sprintf("URLPrefix=%s:Expires=%d:KeyName=%s",
		encodedURLPrefix, expiration.Unix(), keyName)

	mac := hmac.New(sha1.New, key)
	mac.Write([]byte(input))
	sig := base64.URLEncoding.EncodeToString(mac.Sum(nil))

	signedValue := fmt.Sprintf("%s:Signature=%s",
		input,
		sig,
	)

	return signedValue, nil
}

Java

import java.net.MalformedURLException;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.InvalidKeyException;
import java.security.Key;
import java.security.NoSuchAlgorithmException;
import java.time.ZonedDateTime;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class SignedCookies {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.

    // The name of the signing key must match a key added to the back end bucket or service.
    String keyName = "YOUR-KEY-NAME";
    // Path to the URL signing key uploaded to the backend service/bucket.
    String keyPath = "/path/to/key";
    // The Unix timestamp that the signed URL expires.
    long expirationTime = ZonedDateTime.now().plusDays(1).toEpochSecond();
    // URL prefix to sign as a string. URL prefix must start with either "http://" or "https://"
    // and must not include query parameters.
    String urlPrefix = "https://media.example.com/videos/";

    // Read the key as a base64 url-safe encoded string, then convert to byte array.
    // Key used in signing must be in raw form (not base64url-encoded).
    String base64String = new String(Files.readAllBytes(Paths.get(keyPath)),
        StandardCharsets.UTF_8);
    byte[] keyBytes = Base64.getUrlDecoder().decode(base64String);

    // Create signed cookie from policy.
    String signedCookie = signCookie(urlPrefix, keyBytes, keyName, expirationTime);
    System.out.println(signedCookie);
  }

  // Creates a signed cookie for the specified policy.
  public static String signCookie(String urlPrefix, byte[] key, String keyName,
      long expirationTime)
      throws InvalidKeyException, NoSuchAlgorithmException {

    // Validate input URL prefix.
    try {
      URL validatedUrlPrefix = new URL(urlPrefix);
      if (!validatedUrlPrefix.getProtocol().startsWith("http")) {
        throw new IllegalArgumentException(
            "urlPrefix must start with either http:// or https://: " + urlPrefix);
      }
      if (validatedUrlPrefix.getQuery() != null) {
        throw new IllegalArgumentException("urlPrefix must not include query params: " + urlPrefix);
      }
    } catch (MalformedURLException e) {
      throw new IllegalArgumentException(
          "urlPrefix malformed: " + urlPrefix);
    }

    String encodedUrlPrefix = Base64.getUrlEncoder().encodeToString(urlPrefix.getBytes(
        StandardCharsets.UTF_8));
    String policyToSign = String.format("URLPrefix=%s:Expires=%d:KeyName=%s", encodedUrlPrefix,
        expirationTime, keyName);

    String signature = getSignatureForUrl(key, policyToSign);
    return String.format("Cloud-CDN-Cookie=%s:Signature=%s", policyToSign, signature);
  }

  // Creates signature for input string with private key.
  private static String getSignatureForUrl(byte[] privateKey, String input)
      throws InvalidKeyException, NoSuchAlgorithmException {

    final String algorithm = "HmacSHA1";
    final int offset = 0;
    Key key = new SecretKeySpec(privateKey, offset, privateKey.length, algorithm);
    Mac mac = Mac.getInstance(algorithm);
    mac.init(key);
    return Base64.getUrlEncoder()
        .encodeToString(mac.doFinal(input.getBytes(StandardCharsets.UTF_8)));
  }
}

Python

def sign_cookie(
    url_prefix: str,
    key_name: str,
    base64_key: str,
    expiration_time: datetime,
) -> str:
    """Gets the Signed cookie value for the specified URL prefix and configuration.

    Args:
        url_prefix: URL prefix to sign.
        key_name: name of the signing key.
        base64_key: signing key as a base64 encoded string.
        expiration_time: expiration time.

    Returns:
        Returns the Cloud-CDN-Cookie value based on the specified configuration.
    """
    encoded_url_prefix = base64.urlsafe_b64encode(
        url_prefix.strip().encode("utf-8")
    ).decode("utf-8")
    epoch = datetime.utcfromtimestamp(0)
    expiration_timestamp = int((expiration_time - epoch).total_seconds())
    decoded_key = base64.urlsafe_b64decode(base64_key)

    policy = f"URLPrefix={encoded_url_prefix}:Expires={expiration_timestamp}:KeyName={key_name}"

    digest = hmac.new(decoded_key, policy.encode("utf-8"), hashlib.sha1).digest()
    signature = base64.urlsafe_b64encode(digest).decode("utf-8")

    signed_policy = f"Cloud-CDN-Cookie={policy}:Signature={signature}"

    return signed_policy

Convalida dei cookie firmati in corso...

Il processo di convalida di un cookie firmato è essenzialmente la stessa di generazione di un cookie firmato. Ad esempio, supponi di voler convalidare la seguente intestazione dei cookie firmati:

Cookie: Cloud-CDN-Cookie=URLPrefix=URL_PREFIX:Expires=EXPIRATION:KeyName=KEY_NAME:Signature=SIGNATURE; Domain=media.example.com; Path=/; Expires=Tue, 20 Aug 2019 02:26:49 GMT; HttpOnly

Puoi utilizzare la chiave secret denominata da KEY_NAME per generare la firma in modo indipendente e quindi verificare che corrisponda a SIGNATURE.

Emissione di cookie agli utenti

L'applicazione deve generare ed emettere a ogni utente (client) un singolo cookie HTTP contenente un criterio firmato correttamente:

1. Crea un firmatario HMAC-SHA-1 nel codice dell'applicazione.

2. Firma il criterio utilizzando la chiave scelta, prendendo nota del nome della chiave che hai aggiunto al backend, ad esempio mySigningKey.

3. Crea una norma sui cookie con il seguente formato, tenendo presente che sia il nome che il valore sono sensibili alle maiuscole:

   Name: Cloud-CDN-Cookie
   Value: URLPrefix=$BASE64URLECNODEDURLORPREFIX:Expires=$TIMESTAMP:KeyName=$KEYNAME:Signature=$BASE64URLENCODEDHMAC
   

   Intestazione Set-Cookie di esempio:

   Set-Cookie: Cloud-CDN-Cookie=URLPrefix=aHR0cHM6Ly9tZWRpYS5leGFtcGxlLmNvbS92aWRlb3Mv:Expires=1566268009:KeyName=mySigningKey:Signature=0W2xlMlQykL2TG59UZnnHzkxoaw=; Domain=media.example.com; Path=/; Expires=Tue, 20 Aug 2019 02:26:49 GMT; HttpOnly
   

   Gli attributi Domain e Path nel cookie determinano se il client invia il cookie a Cloud CDN.

Consigli e requisiti

• Imposta esplicitamente gli attributi Domain e Path in modo che corrispondano al dominio e al prefisso del percorso con cui intendi pubblicare i tuoi contenuti protetti, che potrebbero essere diversi dal dominio e dal percorso in cui viene emesso il cookie (example.com rispetto a media.example.com o /browse e /videos).

• Assicurati di avere un solo cookie con un determinato nome per gli stessi Domain e Path.

• Assicurati di non inviare cookie in conflitto perché ciò potrebbe impedire l'accesso ai contenuti in altre sessioni del browser (finestre o schede).

• Imposta i flag Secure e HttpOnly dove applicabile. Secure assicura che il cookie venga inviato solo tramite connessioni HTTPS. HttpOnly impedisce di rendere il cookie disponibile a JavaScript.

• Gli attributi dei cookie Expires e Max-Age sono facoltativi. Se li ometti, il cookie esiste mentre esiste la sessione del browser (scheda, finestra).

  Nota: l'attributo Expires qui menzionato è quello che (se presente) viene visualizzato al di fuori del valore del cookie. Non confondere questo attributo con il parametro Expires contenuto nel valore del cookie, che è obbligatorio. Il parametro Expires contenuto nel valore del cookie indica il limite di tempo entro il quale Cloud CDN consente all'utente di accedere ai contenuti protetti. Questo limite di tempo è indipendente dalla durata dei cookie.

• In caso di riempimento o fallimento della cache, il cookie firmato viene trasmesso all'origine definita nel servizio di backend. Assicurati di convalidare il valore del cookie firmato in ogni richiesta prima di pubblicare i contenuti.