Configurer des notifications pour un secret

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 compatibles avec Secret Manager :

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 :

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

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 Google Cloud CLI.

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 la procédure décrite dans le Activez la page de l'API Secret Manager du guide 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 Google Cloud CLI, 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 la console Google Cloud. Vous pouvez également créer des sujets avec Google Cloud CLI, 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. Pour ce faire, utilisez la console Google Cloud ou Google Cloud CLI. La commande suivante attribue au compte de service le rôle Diffuseur 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 la console Google Cloud. Vous pouvez également créer des abonnements avec Google Cloud CLI, 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 secrets create SECRET_ID --topics TOPIC_NAME

$ 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. Avec la Google Cloud CLI, vous pouvez ajouter ou supprimer un ou plusieurs sujets d'un secret, et effacer tous les sujets du 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 des fonctions Cloud Run

Les notifications d'événement peuvent être utilisées pour déclencher des workflows arbitraires en créant des fonctions Cloud Run permettant de consommer les messages Pub/Sub. Pour obtenir un guide complet, consultez la documentation sur les fonctions Cloud Run. L'exemple de code suivant est destiné à une fonction Cloud qui affiche les types eventType, secretId et métadonnées chaque fois qu'un événement est publié dans le sujet. La liste des types d'événements pour Secret Manager est disponible ici.

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<MessagePublishedData>
    {
        public Task HandleAsync(CloudEvent cloudEvent, MessagePublishedData data, CancellationToken cancellationToken)
        {
          string eventType = data.Message.Attributes["eventType"];
          string secretId = data.Message.Attributes["secretId"];
          string secretMetadata = data.Message.TextData;
          Console.WriteLine($"Received {eventType} for {secretId}. New metadata: {secretMetadata}.");
          return Task.CompletedTask;
        }
    }
}

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
}

import java.util.Base64;
import java.util.Map;
import java.util.logging.Logger;
import lombok.Data;

// Demonstrates how to consume and process a Pub/Sub notification from Secret Manager. Triggered
// by a message on a Cloud Pub/Sub topic.
// Ideally the class should implement a background function that accepts a Pub/Sub message.
// public class ConsumeEventNotification implements BackgroundFunction<PubSubMessage> { }
public class ConsumeEventNotification {

  // You can configure the logs to print the message in Cloud Logging.
  private static final Logger logger = Logger.getLogger(ConsumeEventNotification.class.getName());

  // Accepts a message from a Pub/Sub topic and writes it to logger.
  public static String accept(PubSubMessage message) {
    String eventType = message.attributes.get("eventType");
    String secretId = message.attributes.get("secretId");
    String data = new String(Base64.getDecoder().decode(message.data));
    String log = String.format("Received %s for %s. New metadata: %s", eventType, secretId, data);
    logger.info(log);
    return log;
  }

  // Event payload. Mock of the actual Pub/Sub message.
  @Data
  public static class PubSubMessage {

    byte[] data;
    Map<String, String> attributes;
    String messageId;
    String publishTime;
    String orderingKey;
  }
}

/**
* 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) => {
  const eventType = event.attributes.eventType;
  const secretID = event.attributes.secretId;
  const secretMetadata = Buffer.from(event.data, 'base64').toString();
  console.log(`Received ${eventType} for ${secretID}. New metadata: ${secretMetadata}.`);
};

import base64


def consume_event_notification(event: dict, unused_context: None) -> str:
    """
    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")
    event_notification = (
        f"Received {event_type} for {secret_id}. New metadata: {secret_metadata}"
    )
    print(event_notification)
    return event_notification

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"]
  event_type = message["attributes"]["eventType"]
  secret_id = message["attributes"]["secretId"]
  message_data = Base64.decode64 message["data"]
  FunctionsFramework.logger.info "Received %s for %s. New metadata: %s." % [event_type, secret_id, message_data]
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

• Découvrez comment analyser les secrets avec Cloud Asset Inventory.