Configurer des notifications sur un secret

Cette page explique comment configurer et utiliser des notifications d'événements pour vos secrets dans Secret Manager.

Présentation

Secret Manager s'intègre à Pub/Sub pour fournir des notifications d'événements pour les modifications apportées aux secrets et aux versions de secrets. Vous pouvez utiliser ces notifications pour lancer des workflows, 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émarrer 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 d'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 SecretVersion 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 le mappage JSON proto3.

Types d'événement

La liste suivante répertorie les types d'événements 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_VERSION_DESTROY_SCHEDULED Envoyé lorsqu'une durée de délai de destruction est configurée sur le secret et que l'utilisateur tente de détruire une version de secret.
SECRET_ROTATE Envoyé lorsqu'il est temps d'alterner un secret. Pour en savoir plus, consultez la section Créer des calendriers de rotation.
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 clé/valeur 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 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.

  1. Pour configurer Secret Manager, procédez comme suit:

    • Créez ou utilisez un projet existant pour stocker vos ressources Secret Manager.

    • Si nécessaire, suivez les étapes indiquées sur la page Activer l'API Secret Manager.

  2. Pour configurer Pub/Sub, procédez comme suit:

    • Créez ou utilisez un projet existant pour stocker vos ressources Pub/Sub.

    • Si nécessaire, activez l'API Pub/Sub.

  3. Authentifiez-vous sur Google Cloud à l'aide de la commande suivante:

        $ gcloud auth login --update-adc

Créer une identité d'agent de service

Pour créer une identité d'agent de service pour chaque projet nécessitant des secrets avec des notifications d'événements, procédez comme suit:

  1. 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"

    Cette commande renvoie un nom de compte de service au format suivant:

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

  2. Accordez à ce compte de service l'autorisation de publier des messages sur les sujets Pub/Sub configurés sur vos secrets.

  3. Enregistrez le nom du compte de service en tant que variable d'environnement à l'aide de la commande suivante:

        # 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 dans la Google Cloud CLI à l'aide de la commande suivante:

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • PROJECT_ID: ID du projet Google Cloud contenant le secret
  • PUBSUB_PROJECT_ID: ID du projet dans lequel créer des abonnements
  • PUBSUB_TOPIC_NAME: nom du sujet

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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 au compte de service Secret Manager l'autorisation de publier des messages sur les sujets

Vous pouvez accorder des autorisations au compte de service Secret Manager via la console Google Cloud ou Google Cloud CLI.

Pour accorder le rôle Diffuseur Pub/Sub (roles/pubsub.publisher) au sujet Pub/Sub, utilisez la commande suivante:

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • PUBSUB_TOPIC_NAME: nom du sujet

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

gcloud pubsub topics create 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 sujets dans la Google Cloud CLI à l'aide de la commande suivante:

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • PUBSUB_PROJECT_ID: ID du projet dans lequel créer des abonnements
  • PUBSUB_SUBSCRIPTION_NAME: nom de l'abonnement
  • PUBSUB_TOPIC_NAME: nom du sujet

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

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

Windows (PowerShell)

gcloud pubsub subscriptions create projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME `
  --topic projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME

Windows (cmd.exe)

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 change.

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • SECRET_ID: ID du secret ou identifiant complet du secret
  • PUBSUB_TOPIC_NAME: nom du sujet
  • LOCATION: emplacement Google Cloud du secret

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME --location=LOCATION

Windows (PowerShell)

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME --location=LOCATION

Windows (cmd.exe)

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME --location=LOCATION

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, ainsi que d'effacer tous les sujets d'un secret.

Ajouter des sujets

Pour ajouter un ou plusieurs sujets à un secret, utilisez la commande suivante:

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • SECRET_ID: ID du secret ou identifiant complet du secret
  • LOCATION: emplacement Google Cloud du secret
  • PROJECT_ID: ID du projet Google Cloud contenant le secret
  • PUBSUB_PROJECT_ID: ID du projet dans lequel créer des abonnements
  • PUBSUB_TOPIC_1_NAME et PUBSUB_TOPIC_2_NAME: noms des sujets que vous ajoutez au secret

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

gcloud secrets update SECRET_ID --location=LOCATION \
  --project PROJECT_ID \
  --add-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

Windows (PowerShell)

gcloud secrets update SECRET_ID --location=LOCATION `
  --project PROJECT_ID `
  --add-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

Windows (cmd.exe)

gcloud secrets update SECRET_ID --location=LOCATION ^
  --project PROJECT_ID ^
  --add-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

Supprimer les sujets

Pour supprimer un ou plusieurs sujets d'un secret, utilisez la commande suivante:

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • SECRET_ID: ID du secret ou identifiant complet du secret
  • LOCATION: emplacement Google Cloud du secret
  • PROJECT_ID: projet Google Cloud contenant le secret
  • PUBSUB_PROJECT_ID: ID du projet dans lequel créer des abonnements
  • PUBSUB_TOPIC_1_NAME et PUBSUB_TOPIC_2_NAME: noms des sujets que vous supprimez du secret

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

gcloud secrets update SECRET_ID --location=LOCATION \
  --project PROJECT_ID \
  --remove-topics "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2__NAME

Windows (PowerShell)

gcloud secrets update SECRET_ID --location=LOCATION `
  --project PROJECT_ID `
  --remove-topics "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2__NAME

Windows (cmd.exe)

gcloud secrets update SECRET_ID --location=LOCATION ^
  --project PROJECT_ID ^
  --remove-topics "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2__NAME

Effacer les sujets

Pour supprimer tous les sujets d'un secret, utilisez la commande suivante:

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • SECRET_ID: ID du secret ou identifiant complet du secret
  • PROJECT_ID: projet Google Cloud contenant le secret
  • LOCATION: emplacement Google Cloud du secret

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

gcloud secrets update SECRET_ID --location=LOCATION \
  --project PROJECT_ID \
  --clear-topics

Windows (PowerShell)

gcloud secrets update SECRET_ID --location=LOCATION `
  --project PROJECT_ID `
  --clear-topics

Windows (cmd.exe)

gcloud secrets update SECRET_ID --location=LOCATION ^
  --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 lancer des workflows en créant des fonctions Cloud Run permettant de consommer les messages Pub/Sub. Pour en savoir plus, consultez la documentation sur les fonctions Cloud Run. L'exemple de code suivant concerne une fonction Cloud Run qui imprime eventType, secretId et des métadonnées chaque fois qu'un événement 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<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;
        }
    }
}

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 savoir comment installer et utiliser la bibliothèque cliente pour Secret Manager, consultez la page Bibliothèques clientes Secret Manager.

Pour vous authentifier auprès de Secret Manager, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 


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

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) => {
  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}.`);
};

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. 

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

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"]
  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

Pour obtenir la liste de tous les types d'événements, consultez la section Types d'événements.

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 des sujets Pub/Sub sont ajoutés à un secret, puis que le sujet est modifié de sorte que Secret Manager ne puisse plus publier de messages (par exemple, le sujet est supprimé ou les autorisations du compte de service Secret Manager sont supprimées), Secret Manager écrit des journaux dans Secret Secret Manager avec un message indiquant pourquoi la publication a échoué.

Étape suivante