Dans le cas d'une distribution push, Pub/Sub envoie des requêtes à votre application d'abonné pour distribuer des messages.
Avant de commencer
Avant de lire ce document, assurez-vous de connaître les points suivants:
Fonctionnement de Pub/Sub et des différents termes Pub/Sub
Les différents types d'abonnements acceptés par Pub/Sub et les raisons pour lesquelles vous pourriez vouloir utiliser un abonnement push.
Propriétés d'un abonnement push
Lorsque vous configurez un abonnement push, vous pouvez spécifier les propriétés suivantes.
URL du point de terminaison (obligatoire). Adresse HTTPS accessible publiquement Le serveur du point de terminaison push doit disposer d'un certificat SSL valide signé par une autorité de certification. Le service Pub/Sub envoie les messages aux points de terminaison push situés dans la région Google Cloud où le service stocke les messages. Le service Pub/Sub distribue les messages provenant de la même région Google Cloud de la manière la plus optimale possible.
Pub/Sub ne nécessite plus de preuve de propriété pour les domaines d'URL d'abonnement push. Si votre domaine reçoit des requêtes POST inattendues de la part de Pub/Sub, vous pouvez signaler une suspicion d'utilisation abusive.
Activez l'authentification. Lorsque cette option est activée, les messages distribués par Pub/Sub au point de terminaison push incluent un en-tête d'autorisation permettant au point de terminaison d'authentifier la requête. Des mécanismes d'authentification et d'autorisation automatiques sont disponibles pour les points de terminaison App Engine standards et Cloud Functions hébergés dans le même projet que l'abonnement.
La configuration d'authentification d'un abonnement push authentifié se compose du compte de service et des paramètres d'audience spécifiés dans un appel create, patch ou ModifyPushConfig:
Compte de service (obligatoire) Compte de service associé à l'abonnement push. Ce compte est utilisé en tant que revendication
email
du jeton Web JSON (JWT) généré. Voici la liste des conditions requises pour le compte de service:Ce compte de service doit appartenir au même projet que l'abonnement push.
Le compte principal qui crée ou modifie l'abonnement push doit disposer de l'autorisation
iam.serviceAccounts.actAs
sur le compte de service. Vous pouvez soit autoriser l'appelant à emprunter l'identité de plusieurs comptes de service au niveau du projet, du dossier ou de l'organisation, soit autoriser l'appelant à emprunter l'identité du compte de service.Si votre projet a été créé le 8 avril 2021 ou avant cette date, vous devez accorder le rôle
roles/iam.serviceAccountTokenCreator
au compte de service géré par Googleservice-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com
sur le projet pour permettre à Pub/Sub de créer des jetons. Toutefois, si votre projet a été créé après cette date, vous n'avez pas besoin d'attribuer ce rôle, car le compte de service dispose du rôleroles/pubsub.serviceAgent
avec des autorisations identiques.
Audience. Chaîne unique non sensible à la casse permettant au webhook de valider l'audience visée pour un jeton donné.
Abonnement push et VPC Service Controls
Pour un projet protégé par VPC Service Controls, tenez compte des points suivants pour les abonnements push:
Vous ne pouvez créer qu'un abonnement push pour lequel le point de terminaison push est défini sur les services Cloud Run avec des URL
run.app
par défaut. Les domaines personnalisés ne fonctionnent pas.Vous ne pouvez pas modifier les abonnements push existants. Ces abonnements push continuent de fonctionner, même s'ils ne sont pas protégés par VPC Service Controls.
Recevoir des messages
Lorsque Pub/Sub transmet un message à un point de terminaison push, il envoie le message dans le corps d'une requête POST
. Le corps de la requête est un objet JSON et les données du message se trouvent dans le champ message.data
. Les données du message sont encodées en base64.
L'exemple suivant est le corps d'une requête POST
envoyée à un point de terminaison push :
{ "message": { "attributes": { "key": "value" }, "data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==", "messageId": "2070443601311540", "message_id": "2070443601311540", "publishTime": "2021-02-26T19:13:55.749Z", "publish_time": "2021-02-26T19:13:55.749Z" }, "subscription": "projects/myproject/subscriptions/mysubscription" }
Pour recevoir des messages d'abonnements push, utilisez un webhook et traitez les requêtes POST
envoyées par Pub/Sub au point de terminaison push. Pour en savoir plus sur le traitement de ces requêtes POST
dans App Engine, consultez la page Écrire des messages Pub/Sub et y répondre.
Après avoir reçu une requête push, renvoyez un code d'état HTTP. Pour accuser réception du message, renvoyez l'un des codes d'état suivants :
102
200
201
202
204
Pour envoyer un accusé de réception négatif pour le message, renvoyez tout autre code d'état. Si vous envoyez un accusé de réception négatif ou que le délai d'accusé de réception expire, Pub/Sub renvoie le message. Vous ne pouvez pas modifier le délai d'accusé de réception des messages individuels que vous recevez des abonnements push.
Authentification pour l'abonnement push
Si un abonnement push utilise l'authentification, le service Pub/Sub signe un jeton JWT et l'envoie dans l'en-tête d'autorisation de la requête push. Le jeton JWT inclut des revendications et une signature.
Les abonnés peuvent valider le jeton JWT et vérifier les éléments suivants:
- Les revendications sont exactes.
- Le service Pub/Sub a signé les revendications.
Si les abonnés utilisent un pare-feu, ils ne peuvent pas recevoir de requêtes push. Pour recevoir des requêtes push, vous devez désactiver le pare-feu et vérifier le jeton JWT.
Format JWT
Le jeton JWT est un jeton JWT OpenIDConnect composé d'un en-tête, d'un ensemble de revendications et d'une signature. Le service Pub/Sub encode le jeton JWT en tant que chaîne en base64 avec des délimiteurs de points.
Par exemple, l'en-tête d'autorisation suivant inclut un jeton JWT encodé :
"Authorization" : "Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjdkNjgwZDhjNzBkNDRlOTQ3MTMzY2JkNDk5ZWJjMWE2MWMzZDVh YmMiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJodHRwczovL2V4YW1wbGUuY29tIiwiYXpwIjoiMTEzNzc0M jY0NDYzMDM4MzIxOTY0IiwiZW1haWwiOiJnYWUtZ2NwQGFwcHNwb3QuZ3NlcnZpY2VhY2NvdW50LmNvb SIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJleHAiOjE1NTAxODU5MzUsImlhdCI6MTU1MDE4MjMzNSwia XNzIjoiaHR0cHM6Ly9hY2NvdW50cy5nb29nbGUuY29tIiwic3ViIjoiMTEzNzc0MjY0NDYzMDM4MzIxO TY0In0.QVjyqpmadTyDZmlX2u3jWd1kJ68YkdwsRZDo-QxSPbxjug4ucLBwAs2QePrcgZ6hhkvdc4UHY 4YF3fz9g7XHULNVIzX5xh02qXEH8dK6PgGndIWcZQzjSYfgO-q-R2oo2hNM5HBBsQN4ARtGK_acG-NGG WM3CQfahbEjZPAJe_B8M7HfIu_G5jOLZCw2EUcGo8BvEwGcLWB2WqEgRM0-xt5-UPzoa3-FpSPG7DHk7 z9zRUeq6eB__ldb-2o4RciJmjVwHgnYqn3VvlX9oVKEgXpNFhKuYA-mWh5o7BCwhujSMmFoBOh6mbIXF cyf5UiVqKjpqEbqPGo_AvKvIQ9VTQ"
L'en-tête et l'ensemble de revendications sont des chaînes JSON. Une fois décodés, ils prennent la forme suivante :
{"alg":"RS256","kid":"7d680d8c70d44e947133cbd499ebc1a61c3d5abc","typ":"JWT"} { "aud":"https://example.com", "azp":"113774264463038321964", "email":"gae-gcp@appspot.gserviceaccount.com", "sub":"113774264463038321964", "email_verified":true, "exp":1550185935, "iat":1550182335, "iss":"https://accounts.google.com" }
Les jetons associés aux requêtes envoyées aux points de terminaison push peuvent remonter jusqu'à une heure.
Configurer Pub/Sub pour l'authentification push
L'exemple suivant montre comment définir le compte de service d'authentification push sur le compte de service de votre choix et accorder le rôle iam.serviceAccountTokenCreator
au compte de service géré par Googleservice-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com
.
Console
Accédez à la page Abonnements Pub/Sub.
Cliquez sur Créer un abonnement.
Dans le champ ID d'abonnement, saisissez un nom.
Sélectionnez un thème.
Sélectionnez Push comme type de diffusion.
Saisissez une URL de point de terminaison.
Cochez Enable authentication (Activer l'authentification).
Sélectionnez un compte de service.
(Facultatif) Cliquez sur Accorder pour accorder au compte de service géré par Google
service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com
le rôleiam.serviceAccountTokenCreator
s'il ne dispose pas déjà du rôle.Facultatif: saisissez une audience.
Cliquez sur Créer.
gcloud
# Configure the push subscription gcloud pubsub subscriptions (create|update|modify-push-config) ${SUBSCRIPTION} \ --topic=${TOPIC} \ --push-endpoint=${PUSH_ENDPOINT_URI} \ --push-auth-service-account=${SERVICE_ACCOUNT_EMAIL} \ --push-auth-token-audience=${OPTIONAL_AUDIENCE_OVERRIDE} # Only needed for projects created on or before April 8, 2021: # Grant the Google-managed service account the `iam.serviceAccountTokenCreator` role PUBSUB_SERVICE_ACCOUNT="service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com" gcloud projects add-iam-policy-binding ${PROJECT_ID} \ --member="serviceAccount:${PUBSUB_SERVICE_ACCOUNT}"\ --role='roles/iam.serviceAccountTokenCreator'
Si vous utilisez un abonnement push authentifié avec une application App Engine sécurisée avec Identity-Aware Proxy, vous devez fournir l'ID client IAP en tant qu'audience de jeton d'authentification push.
Pour activer IAP sur votre application App Engine, consultez la section Activer IAP.
Pour trouver l'ID client IAP, recherchez l'ID client IAP-App-Engine-app
sur la page Identifiants.
Réclamations
Un jeton JWT peut être utilisé pour valider que les revendications (y compris les revendications par email
et aud
) sont signées par Google. Pour plus d'informations sur la manière dont les API OAuth 2.0 de Google peuvent être utilisées à la fois pour l'authentification et l'autorisation, consultez la documentation sur OpenID Connect.
Deux mécanismes rendent ces revendications significatives. Tout d'abord, Pub/Sub exige que l'utilisateur ou le compte de service effectuant l'appel CreateSubscription, UpdateSubscription ou ModifierPushConfig disposent d'un rôle doté de l'autorisation iam.serviceAccounts.actAs
sur le compte de service d'authentification push. Un rôle de ce type est le rôle roles/iam.serviceAccountUser
.
Deuxièmement, l'accès aux certificats utilisés pour signer les jetons est étroitement contrôlé. Pour créer le jeton, Pub/Sub doit appeler un service Google interne en utilisant une identité de compte de service de signature distincte, qui est le compte de service géré par Google service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com
.
Ce compte de service de signature doit disposer de l'autorisation iam.serviceAccounts.getOpenIdToken
ou du rôle Créateur de jetons de compte de service (roles/iam.serviceAccountTokenCreator
) sur le compte de service d'authentification push (ou sur toute ressource ascendante, telle que le projet) du compte de service push auth.
Valider les jetons
La validation des jetons envoyés par Pub/Sub au point de terminaison push implique les actions suivantes :
- Vérifier l'intégrité du jeton à l'aide de la validation de signature
- S'assurer que les revendications email et audience du jeton correspondent aux valeurs définies dans la configuration de l'abonnement push.
L'exemple suivant montre comment authentifier une requête push auprès d'une application App Engine non sécurisée avec Identity-Aware Proxy. Si votre application App Engine est sécurisée avec IAP, l'en-tête de requête HTTP contenant le JWT IAP est x-goog-iap-jwt-assertion
et doit être validé en conséquence.
protocol
Requête :
GET https://oauth2.googleapis.com/tokeninfo?id_token={BEARER_TOKEN}
Réponse :
200 OK
{ "alg": "RS256", "aud": "example.com", "azp": "104176025330667568672", "email": "{SERVICE_ACCOUNT_NAME}@{YOUR_PROJECT_NAME}.iam.gserviceaccount.com", "email_verified": "true", "exp": "1555463097", "iat": "1555459497", "iss": "https://accounts.google.com", "kid": "3782d3f0bc89008d9d2c01730f765cfb19d3b70e", "sub": "104176025330667568672", "typ": "JWT" }
C#
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage C# qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour C#.
Go
Java
Node.js
Python
Ruby
Pour en savoir plus sur la variable d'environnement PUBSUB_VERIFICATION_TOKEN
utilisée dans les exemples de code ci-dessus, consultez la page Écrire des messages Pub/Sub et y répondre.
Vous trouverez des exemples supplémentaires sur la validation du support JWT dans le guide de connexion à Google pour les sites Web. Une présentation plus complète des jetons OpenID est disponible dans le guide OpenID Connect, et comprend une liste de bibliothèques clientes qui utiles pour valider les jetons JWT.
Authentification à partir d'autres services Google Cloud
Cloud Run, App Engine et Cloud Functions authentifient les appels HTTP à partir de Pub/Sub en validant les jetons générés par Pub/Sub. La seule configuration requise consiste à attribuer les rôles IAM nécessaires au compte de l'appelant.
Consultez les guides et tutoriels suivants pour différents cas d'utilisation avec ces services:
Cloud Run :
- Déclenchement à partir du mode push de Pub/Sub : votre compte de service d'authentification push doit disposer du rôle
roles/run.invoker
et être associé à un service Cloud Run pour appeler le service Cloud Run correspondant. - Tutoriel : Utiliser Pub/Sub avec Cloud Run
Google App Engine :
Cloud Functions :
- Déclencheurs HTTP : votre compte de service d'authentification push doit disposer du rôle
roles/cloudfunctions.invoker
pour appeler une fonction si vous avez l'intention d'utiliser des requêtes push Pub/Sub en tant que déclencheurs HTTP pour cette fonction. - Déclencheurs Google Cloud Pub/Sub : Les rôles et les autorisations IAM sont automatiquement configurés si vous utilisez des déclencheurs Pub/Sub pour appeler une fonction.
Gérer la distribution des messages
Arrêter et reprendre la distribution des messages
Pour empêcher temporairement l'envoi de requêtes par Pub/Sub au point de terminaison push, passez l'abonnement en mode pull. Le changement peut prendre quelques minutes.
Pour reprendre la distribution push, définissez à nouveau l'URL sur un point de terminaison valide. Pour arrêter définitivement la distribution, supprimez l'abonnement.
Intervalle entre les tentatives d'envoi push
Si un abonné push envoie un trop grand nombre d'accusés de réception négatifs, Pub/Sub peut commencer à distribuer des messages à l'aide d'un intervalle entre les tentatives. Lorsque Pub/Sub utilise un intervalle entre les tentatives, il arrête de distribuer des messages pendant une durée prédéterminée. Cette durée peut être comprise entre 100 millisecondes et 60 secondes. Une fois le temps écoulé, Pub/Sub recommence à distribuer les messages.
Fonctionnement de l'intervalle entre les tentatives
L'intervalle entre les tentatives d'envoi utilise un algorithme d'intervalle exponentiel entre les tentatives pour déterminer le délai entre Pub/Sub et l'envoi des messages. Ce délai est calculé en fonction du nombre d'accusés de réception négatifs envoyés par les abonnés.
Par exemple, si un abonné push reçoit cinq messages par seconde et envoie un accusé de réception négatif par seconde, Pub/Sub diffuse des messages toutes les 500 millisecondes environ. Ou, si l'abonné push envoie cinq accusés de réception négatifs par seconde, Pub/Sub distribue les messages toutes les 30 à 60 secondes.
Tenez compte des considérations suivantes concernant l'abandon:
- Impossible d'activer ou de désactiver l'intervalle entre les tentatives. Vous ne pouvez pas non plus modifier les valeurs utilisées pour calculer le délai.
- Déclencheurs Push sur les actions suivantes :
- En cas de réception d'un accusé de réception négatif.
- Délai d'accusé de réception d'un message expiré
- L'intervalle entre les tentatives de transfert s'applique à tous les messages d'un abonnement (mondial).
Rythme de distribution
Pub/Sub ajuste le nombre de requêtes push simultanées à l'aide d'un algorithme de démarrage lent. Le nombre maximal autorisé de requêtes push simultanées est la fenêtre push. La fenêtre push augmente en cas de livraison réussie et diminue en cas d'échec. Le système commence par une petite taille de fenêtre à un chiffre.
Lorsqu'un abonné accuse réception des messages, la fenêtre augmente de manière exponentielle. Pour les abonnements pour lesquels les abonnés reconnaissent plus de 99% des messages et enregistrent en moyenne une latence de requête push inférieure à une seconde, la fenêtre push doit se développer suffisamment pour suivre le débit de publication.
La latence des requêtes push inclut les éléments suivants :
La latence du réseau aller-retour entre les serveurs Pub/Sub et le point de terminaison push
Temps de traitement de l'abonné
Après 3 000 messages en attente par région, la fenêtre augmente de manière linéaire pour éviter que le point de terminaison push ne reçoive trop de messages. Si la latence moyenne dépasse une seconde ou si l'abonné accuse réception de moins de 99% des requêtes, la fenêtre affiche la limite inférieure de 3 000 messages en attente.
Pour plus d'informations sur les métriques que vous pouvez utiliser pour surveiller la diffusion push, consultez la section Surveiller les abonnements push.
Quotas et limites
Les abonnements push sont soumis à un ensemble de quotas et de limites de ressources.