Intégrer l'interface de votre application

Cette page explique comment intégrer l'interface de votre application Cloud Marketplace afin d'offrir une expérience fluide à vos clients depuis Cloud Marketplace vers votre produit.

De manière générale, vous devez fournir une URL d'inscription pour gérer la création qui sont ensuite gérés dans votre console Web. Vous devez également fournir un URL permettant aux utilisateurs de se connecter. Vous pouvez éventuellement intégrer l'authentification unique (SSO).

Intégrer l'interface de votre application à l'aide de Producer Portal

Pour accéder à toutes les informations dont vous avez besoin pour intégrer l'interface de votre application Cloud Marketplace depuis un seul emplacement, vous pouvez utiliser Section Intégration de l'interface de Producer Portal.

Le lien direct vers Producer Portal est le suivant :

https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID

Pour accéder à la section Intégration de l'interface:

  1. Dans la liste des produits, cliquez sur le nom de votre produit.

  2. Sur la page Présentation de votre produit, accédez à la section Intégration technique et cliquez sur Intégration de l'interface.

Ajouter votre URL d'inscription

Lorsque les utilisateurs achètent votre produit sur Cloud Marketplace, vous devez créer un avec votre produit pour eux. Pour cela, vous devez créer une page d'inscription pour configurer et approuver dans votre système. Vous pouvez configurer cette page en tant que page d'inscription dans laquelle les utilisateurs créent un compte dans votre système, ou sous forme de page qui approuve automatiquement les comptes.

Une fois la page d'inscription créée, ajoutez-la dans Producer Portal:

  1. Dans la liste des produits, cliquez sur le nom de votre produit.

  2. Sur la page Présentation de votre produit, accédez à la section Informations techniques intégration, puis cliquez sur Intégration de l'interface.

  3. Saisissez l'URL de votre page d'inscription dans le champ URL d'inscription.

Vérifier les informations d'inscription de l'utilisateur

Si un utilisateur n'a pas encore créé de compte dans votre système, il doit cliquer sur le bouton S'inscrire avec YOUR_COMPANY_NAME dans Cloud Marketplace. Lorsque l'utilisateur clique sur le bouton, Google Cloud envoie une HTTP POST vers votre page d'inscription, avec une Jeton Web JSON (JWT) dans le x-gcp-marketplace-token. Le jeton JWT contient l'objet ID de compte d'approvisionnement, qui les identifie en tant qu'utilisateur Google Cloud et ID obscurci, qui représente son ID de compte Google. Vous devez utiliser à la fois l'ID de compte d'approvisionnement et l'ID obscurci permettant d'associer le compte Google de l'utilisateur à son compte dans votre système.

Après avoir validé le jeton JWT, votre page d'inscription doit envoyer une demande d'approbation de compte à l'API Partner Procurement, décrite dans les étapes d'intégration du backend.

Pour en savoir plus sur la charge utile JWT et comment la valider, consultez la section Valider le JWT ci-dessous.

Si vous débutez avec les jetons JWT, consultez Introduction au jeton JWT.

Ajouter votre URL de connexion

Vous devez indiquer l'URL de la page de connexion de votre application.

Pour saisir l'URL de la page de connexion de votre application dans Producer Portal:

  1. Dans la liste des produits, cliquez sur le nom de votre produit.

  2. Sur la page Présentation de votre produit, accédez à la section Intégration technique, puis cliquez sur Intégration de l'interface.

  3. Saisissez l'URL de la page de connexion de votre application dans le champ URL de connexion.

(Facultatif) Activer l'authentification unique (SSO) pour vos clients

Pour activer l'authentification unique dans Producer Portal :

  1. Dans la liste des produits, cliquez sur le nom de votre produit.

    1. Sur la page Présentation de votre produit, accédez à la section Informations techniques intégration, puis cliquez sur Intégration de l'interface.

    2. Sous Enable SSO login? (Activer la connexion SSO ?), sélectionnez Yes (Oui).

Validez l'identité de vos clients Informations de connexion SSO

Lorsque les clients se connectent à votre application à l'aide de l'authentification unique, Google Cloud envoie une HTTP POST à la page de connexion de votre application, avec une Jeton Web JSON (JWT) du même format que le jeton JWT envoyé lorsque les utilisateurs s'inscrivent pour la première fois à votre application.

Pour en savoir plus sur la charge utile JWT et sur la façon de la vérifier, consultez Vérifiez le JWT ci-dessous.

Vérifier le jeton JWT

Certains processus, tels que l'inscription d'un nouveau client ou la connexion d'un client avec implique l'envoi d'une requête HTTP POST avec Jeton Web JSON (JWT) dont vous pourriez avoir besoin à vérifier.

Le tableau suivant répertorie:

  • Événements impliquant l'envoi d'une requête HTTP avec un jeton JWT.
  • Type de requête HTTP impliqué.
  • Indique si le jeton JWT doit être validé ou non.
Événement Type de requête HTTP Validation JWT requise

Inscrire un nouveau client

POST

Oui

Connexion client, sans authentification unique

GET

Non

Connexion client avec authentification unique

POST

Oui

Charge utile JWT

La charge utile du jeton JWT est au format suivant :

Header

{
  "alg": "RS256",
  "kid": "KEY_ID"
}

Où :

  • alg est toujours RS256.
  • kid indique l'ID de clé utilisé pour sécuriser le jeton JWT. Utilisez cet ID pour rechercher la clé à partir de l'objet JSON dans l'attribut iss de la charge utile.

Charge utile

{
  "iss": "https://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com",
  "iat": CURRENT_TIME,
  "exp": CURRENT_TIME + 5 minutes,
  "aud": "PARTNER_DOMAIN_NAME",
  "sub": "PROCUREMENT_ACCOUNT_ID",
  "google": {
    "roles": [GCP_ROLE],
    "user_identity": USER_ID
  }
}

Où :

  • sub est l'ID du compte Google de l'utilisateur. Vous devez utiliser cet identifiant pour lier le compte Google de l'utilisateur à son compte dans votre système.
  • iss identifie l'expéditeur du jeton JWT. L'URL dans la demande iss renvoie à une clé publique de Google.
  • exp indique que le jeton a expiré et est définie sur cinq minutes après l'envoi du jeton.
  • aud est le domaine qui héberge votre produit, tel que example.com.
  • roles est un tableau de chaînes représentant les rôles de l'utilisateur. Il peut s'agir soit:

    • account_admin, qui indique que l'utilisateur est un administrateur de compte de facturation (administrateur des commandes) du compte de facturation ayant acheté le produit, ou

    • project_editor, qui indique que l'utilisateur est un éditeur (gestionnaire d'accès), mais pas un administrateur de facturation, du projet associé à ce compte de facturation.

  • user_identity est l'ID GAIA obscurci de l'utilisateur, qui peut être utilisé pour lancer OpenID Connect.

Charge utile pour plusieurs commandes du même produit

Si vous avez activé plusieurs commandes du même produit, la charge utile inclut un objet orders supplémentaire. Cet attribut inclut l'ID de commande unique correspondant à l'ID de droit d'accès pour chaque commande. Assurez-vous que la page de connexion de votre application peut répondre à ce nouveau champ orders.

{
  "iss": "https://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com",
  "iat": CURRENT_TIME,
  "exp": CURRENT_TIME + 5 minutes,
  "aud": "PARTNER_DOMAIN_NAME",
  "sub": "PROCUREMENT_ACCOUNT_ID",
  "google": {
    "roles": [GCP_ROLE],
    "user_identity": USER_ID,
    "orders": [ORDER_ID1, ORDER_ID2]
  }
}

Où :

  • ORDER_ID est une liste d'ID de commande uniques pour chaque ID de droit d'accès. Elle indique les différentes offres sur le même produit. Ce champ n'est disponible que si plusieurs commandes du même produit sont activées.

Pour savoir comment activer plusieurs commandes d'un même produit, consultez l'article Activer plusieurs commandes du même produit.

Vérifier la charge utile

Lorsque vous recevez le jeton JWT, vous devez vérifier les éléments suivants :

  1. Vérifiez que la signature JWT utilise la clé publique de Google.

  2. Assurez-vous que le jeton JWT n'a pas expiré en vérifiant la revendication exp.

  3. Vérifiez que la demande aud correspond au domaine approprié pour votre produit.

  4. Vérifiez que la revendication iss est https://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com.

  5. Vérifiez que sub n'est pas vide.

Lancer la connexion à Google avec login_hint

Si vous souhaitez que vos utilisateurs passent par un flux d'autorisation OAuth 2.0 avec votre site, vous pouvez utiliser les informations d'identité de la charge utile pour initialiser ce flux sur le compte Google qu'ils utilisaient pour Google Cloud avant la redirection. Pour ce faire, vous devez fournir l'élément user_identity renseigné dans le jeton JWT en tant que login_hint. Pour plus d'informations, consultez le Documentation Google OAuth 2.0

Une fois que l'utilisateur a terminé le flux OAuth 2.0 avec votre site, vous devez vérifier qu'il s'agit de l'utilisateur auquel vous pensiez terminer le flux OAuth. Pour ce faire, vous devez utiliser le jeton d'accès OAuth 2.0 pour appeler l'API Google UserInfo afin de récupérer les informations de base de l'utilisateur. Cette commande renvoie un ID qui doit correspondre au user_identity du jeton JWT.

Créer des comptes de service pour vos clients

Si votre produit nécessite un compte de service, vous pouvez faire appel à un ingénieur partenaire par:

  • Provisionner des comptes de service pour vos clients
  • Configurez une page de gestion des comptes de service pour que vos clients puissent attribuer les rôles IAM (Identity and Access Management) requis aux comptes de service.

Vous devez fournir le lien vers la page de ce compte de service à vos clients. généralement via la console de gestion de votre produit.

Provisionner les comptes de service

Pour provisionner les comptes de service, contactez votre ingénieur partenaire en indiquant les informations suivantes :

  • Nom du service: il s'agit d'un identifiant produit unique qui différencie votre produit d'autres produits. Nous vous recommandons d'utiliser le nom de service créé lorsque vous intégré votre produit.

  • ID du projet : ID du projet dans lequel vous créez les comptes de service qui accèdent aux ressources de vos clients. Vous devez créer tous les comptes de service que votre produit utilise dans un seul projet.

  • Rôles IAM et raisonnement: les rôles IAM requises pour les comptes de service et la raison pour laquelle ces rôles sont nécessaires. Cette information est partagée avec votre client, ce qui peut avoir un impact sur son accès ou non l'accès au compte de service.

Si vous souhaitez que votre client revienne sur votre site après avoir accordé l'accès au compte de service, envoyez le nom de domaine de votre console à votre ingénieur partenaire. Vous pouvez envoyer plusieurs noms de domaine, y compris des sous-domaines, tels que staging.example.com.

Intégrer la page de gestion des comptes de service dans la console de votre produit

L'ingénieur partenaire crée une page de gestion des comptes de service pour autoriser d'accorder l'accès aux comptes de service. Vous créez ensuite un lien vers la page depuis votre console.

Une fois que votre ingénieur partenaire vous a informé que le service de gestion des comptes est prête, ajoutez des paramètres à l'URL, puis ajoutez un lien vers la page console.

Vous devez ajouter deux paramètres à l'URL :

  • service-name : nom de service que vous avez fourni à votre ingénieur partenaire.

  • service-account-email : adresse e-mail du compte de service que vous avez créé pour votre client Chaque client possède un compte de service unique.

L'exemple suivant présente une URL avec les paramètres requis :

https://console.cloud.google.com/marketplace-saas/service-account/service-name/service-account-email

Vous pouvez ajouter des paramètres supplémentaires en fonction des besoins besoins. Exemple :

https://console.google.com/marketplace-saas/service-account/service-name/service-account-email;single=true;redirect=https%3A%2F%2Fexample.com

Les paramètres de l'URL indiquent que votre produit nécessite l'accès à un seul projet Google Cloud et que le client peut revenir à votre console.

Liste des paramètres d'URL

Voici une liste des paramètres d'URL que vous pouvez envoyer au service de gestion du compte:

ParamètreDescription
service-nameCe champ est obligatoire. Il s'agit du nom de service que vous avez fourni à votre ingénieur partenaire.
service-account-emailCe champ est obligatoire. Il s'agit de l'adresse e-mail du compte de service que vous avez créé pour votre client.
singleLorsque la valeur est "true", cela signifie que votre produit nécessite un accès à un seul projet.
hints=project-id-1Définit le projet auquel vous souhaitez que le compte de service accède. Utilisez des virgules pour séparer les projets.
filter=role1Les rôles attribués au compte de service sont limités à un sous-ensemble des rôles que vous avez fournis à votre ingénieur partenaire. Excluez roles/ lorsque vous utilisez le filtre.
redirectFournit au client un lien permettant de revenir à votre console de gestion. Pour utiliser ce paramètre, le nom de domaine doit être enregistré auprès de votre ingénieur partenaire.