Notifications d'événements pour Secret Manager

Cette rubrique traite de la prise en charge des notifications d'événements dans Secret Manager.

Aperçu

Les notifications d'événement envoient des informations sur les modifications apportées à vos secrets et à vos versions de secrets à Pub/Sub. Ces notifications peuvent être utilisées pour déclencher des workflows arbitraires, comme le redémarrage d'une application lorsqu'une nouvelle version de secret est ajoutée ou l'envoi d'une notification aux ingénieurs chargés de la sécurité lorsqu'un secret est supprimé. Pour en savoir plus sur l'utilisation de ces notifications pour déclencher des workflows, consultez la documentation Pub/Sub.

Fonctionnement des notifications d'événements dans Secret Manager

Les secrets peuvent être configurés avec une liste de 10 sujets Pub/Sub au maximum. Chaque fois qu'une opération modifiant le secret ou l'une de ses versions est effectuée, Secret Manager publie automatiquement un message dans chacun des sujets Pub/Sub de ce secret. Les appels Get, List et Access n'entraînent pas de publication de messages.

Les messages Pub/Sub comportent un ensemble de paires clé/valeur "attribut" contenant des métadonnées sur l'événement, ainsi qu'un champ "données" contenant une sérialisation JSON complète de la ressource secret ou Version de secret qui a été créée ou modifiée. Il s'agit d'une chaîne au format UTF-8 qui représente la ressource Secret ou SecretVersion au format spécifié par l'API publique de Secret Manager, encodée au format JSON comme spécifié dans Mappage JSON proto3

Types d'événement

La liste suivante répertorie les types d'événements actuellement compatibles avec Secret Manager :

Type d'événement Description
SECRET_CREATE Envoyé lorsqu'un secret a bien été créé.
SECRET_UPDATE Envoyé lorsqu'un nouveau secret a bien été mis à jour.
SECRET_DELETE Envoyé lorsqu'un secret est supprimé, en raison d'une requête initiée par l'utilisateur ou de son expiration.
SECRET_VERSION_ADD Envoyé lorsqu'une nouvelle version de secret a bien été ajoutée.
SECRET_VERSION_ENABLE Envoyé lorsqu'une version de secret est activée.
SECRET_VERSION_DISABLE Envoyé lorsqu'une version de secret est désactivée.
SECRET_VERSION_DESTROY Envoyé lorsqu'une version de secret est détruite.
SECRET_ROTATE Envoyé lorsqu'il est temps d'alterner un secret. Pour en savoir plus, consultez la page Créer et gérer des règles de rotation sur des secrets.
TOPIC_CONFIGURED

Il s'agit d'un message de test sans corps ni attributs autres que eventType: TOPIC_CONFIGURED. Cela est envoyé lorsqu'un secret est créé ou mis à jour avec une liste de sujets Pub/Sub, mais n'indique pas que l'opération a réussi.

Un message SECRET_CREATE ou SECRET_UPDATE est envoyé immédiatement après la réussite de l'opération.

Chaque fois que des sujets sont mis à jour sur un secret, un message TOPIC_CONFIGURED est envoyé à tous les sujets du secret, y compris ceux qui étaient déjà présents.

Format des notifications

Les notifications envoyées au sujet Pub/Sub comprennent deux parties :

  • Attributs : ensemble de paires valeur/clé décrivant l'événement
  • Données : chaîne contenant les métadonnées de l'objet modifié.

Attributs

Les attributs sont des paires valeur/clé présentes dans les notifications que Secret Manager envoie à votre sujet Pub/Sub. Toutes les notifications autres que les messages de test TOPIC_CONFIGURED contiennent toujours l'ensemble de paires clé/valeur suivant, quelles que soient les données de la notification :

Nom de l'attribut Exemple Description
eventType SECRET_CREATE Type d'événement qui vient de se produire. Consultez la section Types d'événements pour obtenir la liste des valeurs possibles.
dataFormat JSON_API_V1 Format des données d'objet.
secretId projects/p/secrets/my-secret Nom complet de la ressource du secret sur lequel l'événement s'est produit.
timestamp 2021-01-20T11:17:45.081104-08:00 Heure à laquelle l'événement s'est produit.

Parfois, les notifications contiennent l'ensemble de paires clé/valeur suivant :

Nom de l'attribut Exemple Description
versionId projects/p/secrets/my-secret/versions/456

Nom de la version du secret pour lequel l'événement s'est produit.

Cet élément n'est présent que dans les notifications d'événements SECRET_VERSION_ADD, SECRET_VERSION_ENABLE, SECRET_VERSION_DISABLE et SECRET_VERSION_DESTROY.

deleteType REQUESTED Indique si la suppression a été demandée par un utilisateur (REQUESTED) ou en raison de l'expiration du secret (EXPIRATION). Présent uniquement pour les notifications d'événements SECRET_DELETE.

Données

Le champ de données est une chaîne UTF-8 contenant les métadonnées de l'objet modifié. Les données sont soit un secret, soit une version de secret.

Dans le cas des notifications SECRET_DELETE, les métadonnées contenues dans le champ de données représentent les métadonnées de l'objet avant sa suppression. Pour toutes les autres notifications, les métadonnées incluses dans le champ de données représentent les métadonnées de l'objet après sa modification.

Limites

Les notifications d'événement ne sont disponibles que dans l'API v1 de Secret Manager et dans l'outil de ligne de commande gcloud.

Avant de commencer

Vous pouvez choisir de stocker toutes les ressources dans le même projet ou de stocker les secrets et les sujets Pub/Sub dans des projets distincts. Remplissez les conditions préalables suivantes pour configurer Secret Manager et Pub/Sub :

  • Secret Manager :

    • Créez ou utilisez un projet existant pour stocker vos ressources Secret Manager.
    • Si nécessaire, suivez les étapes décrites dans la section Configurer Secret Manager du guide de démarrage rapide de Secret Manager.
  • Pub/Sub

    • Créez ou utilisez un projet existant pour stocker vos ressources Pub/Sub.
    • Si nécessaire, activez l'API Pub/Sub.

Authentifiez-vous sur Google Cloud :

$ gcloud auth login --update-adc

Créer une identité d'agent de service

Vous devez créer une identité d'agent de service pour chaque projet nécessitant des secrets avec des notifications d'événements.

Pour créer une identité de service avec le SDK Cloud, exécutez la commande suivante :

$ gcloud beta services identity create \
    --service "secretmanager.googleapis.com" \
    --project "PROJECT_ID"

La commande précédente affiche un nom de compte de service au format suivant :

service-PROJECT_NUMBER@gcp-sa-secretmanager.iam.gserviceaccount.com

Vous accorderez à ce compte de service l'autorisation de publier des messages sur les sujets Pub/Sub qui seront configurés sur vos secrets.

Enregistrez le nom du compte de service sous forme de variable d'environnement :

# This is from the output of the command above
$ export SM_SERVICE_ACCOUNT="service-...."

Les variables d'environnement du projet Secret Manager, du projet Pub/Sub et du compte de service de Secret Manager doivent être définies pendant toute la durée de cette procédure.

Créer des sujets Pub/Sub

Suivez le guide de démarrage rapide de Pub/Sub pour créer des sujets dans votre projet Pub/Sub dans Cloud Console. Vous pouvez également créer des sujets avec l'outil de ligne de commande gcloud, comme dans cet exemple.

$ gcloud pubsub topics create "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"

Répétez cette opération plusieurs fois si vous souhaitez créer plusieurs sujets Pub/Sub sur le secret.

Accordez à ce compte de service Secret Manager l'autorisation de publier des messages sur les sujets que vous venez de créer. Vous pouvez le faire via Cloud Console ou à l'aide de l'outil de ligne de commande gcloud. La commande suivante accorde au compte de service le rôle d'éditeur Pub/Sub (roles/pubsub.publisher) sur le sujet Pub/Sub my-topic.

$ gcloud pubsub topics add-iam-policy-binding PUBSUB_TOPIC_NAME \
    --member "serviceAccount:${SM_SERVICE_ACCOUNT}" \
    --role "roles/pubsub.publisher"

Créer un abonnement Pub/Sub

Pour afficher les messages publiés dans un sujet, vous devez également créer un abonnement associé à ce sujet. Suivez le guide de démarrage rapide de Pub/Sub pour créer des abonnements dans votre projet Pub/Sub dans Cloud Console. Vous pouvez également créer des abonnements avec l'outil de ligne de commande gcloud comme dans cet exemple.

$ gcloud pubsub subscriptions create "projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME" \
    --topic "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"

Créer un secret avec des sujets configurés

Créez un secret avec une liste de 10 sujets configurés au maximum. Tous les sujets configurés sur un secret reçoivent des notifications d'événement lorsque le secret ou l'une de ses versions est modifié. La commande suivante crée un secret avec my-topic configuré.

gcloud

Pour utiliser Secret Manager avec la ligne de commande, commencez par installer ou mettre à niveau le SDK Cloud vers la version 338.0.0 ou une version ultérieure. Sur Compute Engine ou GKE, vous devez vous authentifier avec le champ d'application cloud-platform.

$ gcloud secrets create SECRET_ID --topics TOPIC_NAME

API

Ces exemples utilisent curl pour illustrer l'utilisation de l'API. Vous pouvez générer des jetons d'accès avec gcloud auth print-access-token. Sur Compute Engine ou GKE, vous devez vous authentifier avec le champ d'application cloud-platform.

$ curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID" \
    --request "POST" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-binary @- <<EOF
{
  "replication":{
    "automatic":{}
  },
  "topics":{
    "name": "TOPIC_NAME"
  }
}
EOF

Mettre à jour les sujets des secrets

Modifiez les sujets Pub/Sub configurés sur un secret en mettant à jour le secret avec les nouveaux noms de ressources du sujet Pub/Sub. L'outil de ligne de commande gcloud vous permet d'ajouter ou de supprimer un ou plusieurs sujets, ainsi que d'effacer tous les sujets d'un secret.

Ajouter des sujets

Ajoute un ou plusieurs sujets à un secret. L'ajout d'un sujet déjà présent n'aura aucun effet.

$ gcloud secrets update "SECRET_ID" \
    --project "PROJECT_ID" \
    --add-topics "projects/PUBSUB_PROJECT_ID/topics/my-topic-2,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"

Supprimer les sujets

Supprime un ou plusieurs sujets d'un secret. La suppression d'un sujet qui n'est pas présent n'aura aucun effet.

$ gcloud secrets update "SECRET_ID" \
    --project "PROJECT_ID" \
    --remove-topics "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_OTHER_TOPIC_NAME"

Effacer les sujets

Supprimer tous les sujets d'un secret.

$ gcloud secrets update SECRET_ID \
    --project "PROJECT_ID" \
    --clear-topics

Utiliser les notifications d'événements avec Cloud Functions

Les notifications d'événement peuvent être utilisées pour déclencher des workflows arbitraires en créant des fonctions Cloud permettant de consommer les messages Pub/Sub. Pour obtenir un guide complet, consultez la documentation Cloud Functions. L'exemple de code ci-dessous concerne une fonction Cloud qui imprime des métadonnées de secret chaque fois qu'un événement UPDATE_SECRET est publié sur le sujet.

C#

Pour exécuter ce code, commencez par configurer un environnement de développement C# et installez le SDK Secret Manager pour C#. Sur Compute Engine ou GKE, vous devez vous authentifier avec le champ d'application cloud-platform.

using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using Google.Events.Protobuf.Cloud.PubSub.V1;
using System;
using System.Threading;
using System.Threading.Tasks;

// Triggered from a message on a Cloud Pub/Sub topic.
// The printed value will be visible in Cloud Logging
// (https://cloud.google.com/functions/docs/monitoring/logging).
namespace PubSubSample
{
    public class Function : ICloudEventFunction
    {
        public Task HandleAsync(CloudEvent cloudEvent, MessagePublishedData data, CancellationToken cancellationToken)
        {
            if (data.Message.Attributes["eventType"] == "SECRET_UPDATE") {
                string secretId = data.Message.Attributes["secretId"];
                string secretMetadata = data.Message.TextData;
                Console.WriteLine($"Secret {secretId} was updated. Its new metadata is: {secretMetadata}");
            }
            return Task.CompletedTask;
        }
    }
}

Go

Pour exécuter ce code, commencez par configurer un environnement de développement Go et installez le SDK Secret Manager pour Go. Sur Compute Engine ou GKE, vous devez vous authentifier avec le champ d'application cloud-platform.

import (
	"context"
	"fmt"
)

// PubSubMessage is the payload of a Pub/Sub event.
type PubSubMessage struct {
	Attributes PubSubAttributes `json:"attributes"`
	Data       []byte           `json:"data"`
}

// PubSubAttributes are attributes from the Pub/Sub event.
type PubSubAttributes struct {
	SecretId  string `json:"secretId"`
	EventType string `json:"eventType"`
}

// ConsumeEventNotification demonstrates how to consume and process the Pub/Sub
// notification from Secret Manager.
func ConsumeEventNotification(ctx context.Context, m PubSubMessage) (string, error) {
	// The printed value will be visible in Cloud Logging:
	//
	//     https://cloud.google.com/functions/docs/monitoring/logging
	//
	eventType := m.Attributes.EventType
	secretID := m.Attributes.SecretId
	data := m.Data

	return fmt.Sprintf("Received %s for %s. New metadata: %q.",
		eventType, secretID, data), nil
}

Java

Pour exécuter ce code, commencez par configurer un environnement de développement Java et installez le SDK Secret Manager pour Java. Sur Compute Engine ou GKE, vous devez vous authentifier avec le champ d'application cloud-platform.

package com.example;

import com.example.Example.PubSubMessage;
import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import java.util.Base64;
import java.util.Map;
import java.util.logging.Logger;

// Triggered from a message on a Cloud Pub/Sub topic.
// The printed value will be visible in Cloud Logging
// (https://cloud.google.com/functions/docs/monitoring/logging).
public class Example implements BackgroundFunction {
  private static final Logger logger = Logger.getLogger(Example.class.getName());

  @Override
  public void accept(PubSubMessage message, Context context) {
    if (message.attributes.get("eventType").equals("SECRET_UPDATE")) {
      String secretId = message.attributes.get("secretId");
      String data = new String(Base64.getDecoder().decode(message.data));
      logger.info(String.format("Secret %s was updated. Its new metadata is: %s", secretId, data));
    }
  }

  public static class PubSubMessage {
    String data;
    Map attributes;
    String messageId;
    String publishTime;
  }
}

Node.js

Pour exécuter ce code, commencez par configurer un environnement de développement Node.js, puis installez le SDK Secret Manager pour Node.js. Sur Compute Engine ou GKE, vous devez vous authentifier avec le champ d'application cloud-platform.

/**
* Triggered from a message on a Cloud Pub/Sub topic.
* The printed value will be visible in Cloud Logging
* (https://cloud.google.com/functions/docs/monitoring/logging).
*
* @param {!Object} event Event payload.
* @param {!Object} context Metadata for the event.
*/
exports.smEventsFunction = (event, context) => {
  event_type = event.attributes.eventType;
  if (event_type == 'SECRET_UPDATE') {
    const secretID = event.attributes.secretId;
    const secretMetadata = Buffer.from(event.data, 'base64').toString();
    console.log(`Secret ${secretID} was updated. Its new metadata is: ${secretMetadata}`);
  }
};

Python

Pour exécuter ce code, commencez par configurer un environnement de développement Python et installez le SDK Secret Manager pour Python. Sur Compute Engine ou GKE, vous devez vous authentifier avec le champ d'application cloud-platform.

def consume_event_notification(event, unused_context):
    """
    consume_event_notification demonstrates how to consume and process a
    Pub/Sub notification from Secret Manager.
    Args:
          event (dict): Event payload.
          unused_context (google.cloud.functions.Context): Metadata for the event.
    """
    event_type = event["attributes"]["eventType"]
    secret_id = event["attributes"]["secretId"]
    secret_metadata = base64.b64decode(event["data"]).decode("utf-8")
    return f"Received {event_type} for {secret_id}. New metadata: {secret_metadata}"

Ruby

Pour exécuter ce code, commencez par configurer un environnement de développement Ruby et installez le SDK Secret Manager pour Ruby. Sur Compute Engine ou GKE, vous devez vous authentifier avec le champ d'application cloud-platform.

require "functions_framework"
require "base64"

# Triggered from a message on a Cloud Pub/Sub topic.
# The printed value will be visible in Cloud Logging
# (https://cloud.google.com/functions/docs/monitoring/logging).
FunctionsFramework.cloud_event "sm_events_function" do |event|
  message = event.data["message"]
  if message["attributes"]["eventType"] == "SECRET_UPDATE"
    secret_id = message["attributes"]["secretId"]
    message_data = Base64.decode64 message["data"]
    FunctionsFramework.logger.info "Secret %s was updated. Its new metadata is: %s" % [secret_id, message_data]
  end
end

Sujets mal configurés

Si des sujets Pub/Sub sont ajoutés à un secret dans une opération de création ou de mise à jour, mais que Secret Manager ne peut pas publier de messages sur le sujet en raison d'une erreur de configuration, l'opération échouera et renverra un message d'erreur indiquant pourquoi la publication a échoué. Cela peut se produire, par exemple, si le sujet n'existe pas ou si le compte de service Secret Manager n'est pas autorisé à publier.

Si l'ajout de sujets Pub/Sub à un secret est effectué, puis que le sujet est modifié et que Secret Manager ne peut plus publier de messages (par exemple, le sujet est supprimé ou les autorisations du compte de service de Secret Manager sont supprimées), Secret Manager écrit des journaux dans la ressource SecretSecret Manager avec un message indiquant pourquoi la publication a échoué.

Étape suivante