Utiliser des cookies sign�s

Cette page pr�sente les cookies sign�s et d�crit comment les utiliser avec Cloud�CDN. Les cookies sign�s fournissent un acc�s limit� dans le temps aux ressources d'un ensemble de fichiers, que les utilisateurs poss�dent ou non un compte Google.

Les cookies sign�s constituent une alternative aux URL sign�es. Ils prot�gent l'acc�s lorsqu'il n'est pas envisageable de signer s�par�ment des dizaines ou des centaines d'URL pour chaque utilisateur dans votre application.

Les cookies sign�s vous permettent�:

• d'autoriser un utilisateur et de lui fournir un jeton limit� dans le temps pour qu'il puisse acc�der � votre contenu prot�g� (au lieu de signer chaque URL)�;
• de limiter l'acc�s de l'utilisateur � un pr�fixe d'URL sp�cifique, tel que https://media.example.com/videos/, et d'accorder � l'utilisateur autoris� un acc�s au contenu prot�g� au sein de ce pr�fixe d'URL uniquement�;
• de conserver vos URL et fichiers manifestes multim�dias tels quels, ce qui simplifie le pipeline d'empaquetage et am�liore la mise en cache.

Si vous pr�f�rez limiter l'acc�s � des URL sp�cifiques, envisagez plut�t d'utiliser des URL sign�es.

Avant de commencer

Avant d'utiliser des cookies sign�s, proc�dez comme suit�:

• Assurez-vous que Cloud�CDN est activ�. Pour obtenir des instructions, consultez la page Utiliser Cloud�CDN. Vous pouvez configurer des cookies sign�s sur un backend avant d'activer Cloud�CDN, mais ils sont sans effet jusqu'� l'activation de Cloud�CDN.

• Si n�cessaire, installez la derni�re version de Google Cloud�CLI�:

  gcloud components update
  

Pour en savoir plus, consultez la page Cookies et URL sign�s.

Configurer des cl�s de requ�te sign�es

La cr�ation de cl�s pour vos URL ou cookies sign�s n�cessite plusieurs �tapes, d�crites dans les sections suivantes.

Points � noter concernant la s�curit�

Cloud�CDN ne valide pas les requ�tes dans les cas suivants�:

• La requ�te n'est pas sign�e.
• Cloud�CDN n'est pas activ� sur le service de backend ou le bucket backend de la requ�te.

Les requ�tes sign�es doivent toujours �tre valid�es � l'origine avant de diffuser la r�ponse. Ceci est d� au fait que les origines peuvent servir � diffuser un m�lange de contenu sign� et non sign�, et qu'un client peut acc�der directement � l'origine.

• Cloud�CDN ne bloque pas les requ�tes n'utilisant ni le param�tre de requ�te Signature, ni le cookie HTTP Cloud-CDN-Cookie. Cloud�CDN rejette les requ�tes dont les param�tres sont incorrects (ou ne sont pas r�dig�s correctement).
• Lorsque votre application d�tecte une signature non valide, assurez-vous qu'elle r�pond avec un code de r�ponse HTTP 403 (Unauthorized). Les codes de r�ponse HTTP 403 ne peuvent pas �tre mis en cache.
• Les r�ponses aux requ�tes sign�es et non sign�es sont mises en cache s�par�ment. Par cons�quent, une r�ponse r�ussie � une requ�te sign�e valide n'est jamais utilis�e pour diffuser une requ�te non sign�e.
• Si votre application envoie un code de r�ponse pouvant �tre mis en cache � une requ�te non valide, les futures requ�tes valides risquent d'�tre rejet�es par erreur.

Pour les backends Cloud�Storage, assurez-vous de supprimer l'acc�s public afin que Cloud�Storage puisse rejeter les requ�tes ne contenant pas de signature valide.

Le tableau suivant r�capitule le comportement.

Cr�er des cl�s de requ�te sign�es

Pour pouvoir exploiter les URL et cookies sign�s Cloud�CDN, vous devez cr�er une ou plusieurs cl�s sur un service de backend et/ou un bucket backend compatibles avec Cloud�CDN.

Pour chaque service de backend ou bucket backend, vous pouvez cr�er et supprimer des cl�s selon vos besoins en termes de s�curit�. Chaque backend peut comporter jusqu'� trois�cl�s configur�es � la fois. Nous vous sugg�rons d'effectuer r�guli�rement une rotation des cl�s�: supprimez la cl� la plus ancienne, ajoutez-en une nouvelle et utilisez-la pour la signature des URL ou cookies.

Vous pouvez utiliser le m�me nom de cl� dans plusieurs services de backend et buckets backend, car chaque ensemble de cl�s est ind�pendant des autres. Les noms de cl� peuvent comporter jusqu'� 63�caract�res. Pour nommer vos cl�s, utilisez les caract�res�A-Z, a-z, 0-9, _�(trait de soulignement) et -�(trait d'union).

Lorsque vous cr�ez des cl�s, veillez � les s�curiser, car toute personne qui en poss�de une peut cr�er des URL ou cookies sign�s accept�s par Cloud�CDN jusqu'� ce que la cl� soit supprim�e du r�seau de diffusion de contenu. Les cl�s sont stock�es sur l'ordinateur sur lequel vous g�n�rez les URL ou cookies sign�s. Cloud�CDN stocke �galement les cl�s pour valider les signatures de requ�te.

Pour garder les cl�s secr�tes, les valeurs de cl� ne sont pas incluses dans les r�ponses aux requ�tes API. Si vous perdez une cl�, vous devez en cr�er une nouvelle.

Pour cr�er une cl� de requ�te sign�e, proc�dez comme suit :

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

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

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

Configurer les autorisations Cloud�Storage

Si vous utilisez Cloud�Storage et que vous avez restreint l'acc�s en lecture aux objets, vous devez autoriser Cloud�CDN � lire les objets en ajoutant le compte de service Cloud�CDN aux listes de contr�le d'acc�s Cloud�Storage.

Vous n'avez pas besoin de cr�er le compte de service. Il est cr�� automatiquement la premi�re fois que vous ajoutez une cl� � un bucket backend d'un projet.

Avant d'ex�cuter la commande suivante, ajoutez au moins une cl� � un bucket backend de votre projet. Si vous ne respectez pas cette condition, la commande �choue et renvoie une erreur, car le compte de service du remplissage du cache Cloud�CDN n'est pas cr�� tant que vous n'avez pas ajout� au moins une cl� pour le projet.

gcloud storage buckets add-iam-policy-binding gs://BUCKET \
  --member=serviceAccount:service-PROJECT_NUM@cloud-cdn-fill.iam.gserviceaccount.com \
  --role=roles/storage.objectViewer

Remplacez PROJECT_NUM par votre num�ro de projet, puis BUCKET par votre bucket de stockage.

Le compte de service Cloud�CDN, service-PROJECT_NUM@cloud-cdn-fill.iam.gserviceaccount.com, ne figure pas dans la liste des comptes de service de votre projet. Ceci est d� au fait qu'il appartient � Cloud�CDN, et non � votre projet.

Pour plus d'informations sur les num�ros de projet, consultez la section Localiser l'ID et le num�ro de projet dans la documentation d'aide de Google Cloud�Console.

Personnaliser le temps de cache maximal

Cloud�CDN met en cache les r�ponses aux requ�tes sign�es, quel que soit l'en-t�te Cache-Control du backend. Le d�lai maximal de mise en cache des r�ponses sans revalidation est d�fini par l'option signed-url-cache-max-age, qui prend la valeur par d�faut d'une heure, et peut �tre modifi� comme indiqu� ici.

Pour d�finir la dur�e maximale de mise en cache d'un service de backend ou d'un bucket backend, ex�cutez l'une des commandes suivantes�:

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

R�pertorier les noms des cl�s de requ�te sign�es

Pour r�pertorier les cl�s d'un service de backend ou d'un bucket backend, ex�cutez l'une des commandes suivantes�:

gcloud compute backend-services describe BACKEND_NAME

gcloud compute backend-buckets describe BACKEND_NAME

Supprimer des cl�s de requ�te sign�es

Lorsque les URL sign�es par une cl� sp�cifique ne doivent plus �tre honor�es, ex�cutez l'une des commandes suivantes pour supprimer cette cl� du service de backend ou du bucket 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

Cr�er une r�gle

Les r�gles de cookie sign� correspondent � une s�rie de paires key-value (d�limit�es par le caract�re :), semblables aux param�tres de requ�te utilis�s dans une URL sign�e. Pour obtenir des exemples, consultez la section �mettre des cookies pour les utilisateurs.

Les r�gles repr�sentent les param�tres pour lesquels une requ�te est valide. Les r�gles sont sign�es � l'aide d'un code d'authentification de message bas� sur le hachage (HMAC) que Cloud�CDN valide pour chaque requ�te.

D�finir le format et les champs des r�gles

Vous devez d�finir quatre�champs dans l'ordre suivant�:

• URLPrefix
• Expires
• KeyName
• Signature

Les paires key-value d'une r�gle de cookie sign� sont sensibles � la casse.

URLPrefix

URLPrefix d�signe un pr�fixe d'URL encod� en base64 et s�curis� pour les URL qui englobe tous les chemins pour lesquels la signature doit �tre valide.

Un pr�fixe URLPrefix encode un sch�ma (http:// ou https://), un nom de domaine complet et un chemin d'acc�s facultatif. Vous n'avez pas besoin de terminer l'URL par le signe /, mais cette pratique est recommand�e. Le pr�fixe ne doit pas inclure de param�tres de requ�te ni de fragments tels que ? ou #.

Par exemple, https://media.example.com/videos correspond aux requ�tes vers les deux��l�ments suivants�:

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

Le chemin du pr�fixe est utilis� en tant que sous-cha�ne de texte, et non en tant que chemin de r�pertoire strict. Par exemple, le pr�fixe https://example.com/data accorde l'acc�s � ces deux��l�ments�:

• /data/file1
• /database

Pour �viter cette erreur, nous vous recommandons de terminer tous les pr�fixes par /, sauf si vous choisissez de terminer intentionnellement un pr�fixe par un nom de fichier partiel tel que https://media.example.com/videos/123 pour accorder l'acc�s aux �l�ments suivants�:

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

Si l'URL demand�e ne correspond pas � URLPrefix, Cloud�CDN rejette la requ�te et renvoie une erreur HTTP 403 au client.

Expiration

Expires doit �tre un horodatage Unix (nombre de secondes depuis le 1er�janvier�1970).

KeyName

KeyName est le nom d'une cl� cr��e sur le bucket backend ou service de backend. Les noms de cl� sont sensibles � la casse.

Signature

Signature est la signature HMAC-SHA-1 s�curis�e pour les URL et encod�e en base64 des champs qui forment la r�gle de cookie. Elle est valid�e � chaque requ�te. Les requ�tes comportant une signature non valide sont rejet�es avec une erreur HTTP 403.

Cr�er des cookies sign�s par programmation

Les exemples de code suivants montrent comment cr�er des cookies sign�s par programmation.

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
}

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

import argparse
import base64
from datetime import datetime
import hashlib
import hmac
from urllib.parse import parse_qs, urlsplit


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

Valider des cookies sign�s

Le processus de validation d'un cookie sign� est fondamentalement le m�me que celui qui permet de g�n�rer un cookie sign�. Par exemple, supposons que vous souhaitiez valider l'en-t�te de cookie sign� suivant�:

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

Vous pouvez utiliser la cl� secr�te nomm�e KEY_NAME pour g�n�rer ind�pendamment la signature, puis confirmer qu'elle correspond � SIGNATURE.

�mettre des cookies pour les utilisateurs

Votre application doit g�n�rer et �mettre pour chaque utilisateur (client) un cookie HTTP unique contenant une r�gle correctement sign�e.

1. Cr�ez un signataire HMAC-SHA-1 dans votre code d'application.

2. Signez la r�gle � l'aide de la cl� choisie, en notant le nom de la cl� que vous avez ajout�e au backend (par exemple, mySigningKey).

3. Cr�ez une r�gle de cookie au format suivant, en tenant compte du fait que le nom et la valeur sont sensibles � la casse�:

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

   Exemple d'en-t�te Set-Cookie�:

   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
   

   Les attributs Domain et Path du cookie d�terminent si le client l'enverra � Cloud�CDN ou non.

Recommandations et exigences

• D�finissez explicitement les attributs Domain et Path pour qu'ils correspondent au pr�fixe du domaine et du chemin depuis lesquels vous souhaitez diffuser votre contenu prot�g�. Ceux-ci peuvent diff�rer du domaine et du chemin o� le cookie est �mis (example.com par rapport � media.example.com ou /browse par rapport � /videos).

• Assurez-vous que vous n'avez qu'un cookie avec un nom donn� pour les m�mes attributs Domain et Path.

• Assurez-vous que vous n'�mettez pas de cookies en conflit, car cela pourrait emp�cher l'acc�s au contenu dans d'autres sessions de navigateur (fen�tres ou onglets).

• D�finissez les options Secure et HttpOnly, le cas �ch�ant. L'option Secure garantit que le cookie n'est envoy� que via des connexions HTTPS. L'option HttpOnly emp�che que le cookie soit mis � disposition dans JavaScript.

• Les attributs de cookie Expires et Max-Age sont facultatifs. Si vous les omettez, le cookie existera tant que la session de navigateur (onglet ou fen�tre) sera active.

• Lors d'un remplissage ou d'un d�faut de cache (miss), le cookie sign� est transmis � l'origine d�finie dans le service de backend. Assurez-vous de valider la valeur du cookie sign� sur chaque requ�te avant de diffuser du contenu.