Intégrer l'interface de votre application

Cette page explique comment intégrer l'interface de votre application à Cloud Marketplace pour offrir à vos clients une expérience fluide lorsqu'ils accèdent à votre produit depuis Cloud Marketplace.

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

Utiliser Producer Portal pour intégrer l'interface de votre application

Pour accéder à toutes les informations dont vous avez besoin pour intégrer l'interface de votre application à Cloud Marketplace à partir d'un seul emplacement, vous pouvez utiliser la 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

Remarque :Si le lien ne s'affiche pas ou si vous ne pouvez pas accéder à l'URL, vérifiez que vous avez sélectionné le bon projet. Si vous ne parvenez toujours pas à accéder à l'URL, utilisez le Partner Support Desk pour demander de l'aide et incluez le mot "Marketplace" dans votre description. Pour en savoir plus sur Partner Support Desk, consultez la page Demander de l'aide concernant Cloud Marketplace.

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, puis cliquez sur Intégration de l'interface.

Ajouter votre URL d'inscription

Lorsque les utilisateurs achètent votre produit sur Cloud Marketplace, vous devez leur créer un compte avec votre produit. Pour ce faire, vous devez créer une page d'inscription afin de configurer et d'approuver les comptes des utilisateurs dans votre système. Vous pouvez la configurer comme une page d'inscription sur laquelle les utilisateurs créent un compte dans votre système ou comme une page qui approuve automatiquement les comptes.

Attention :Lorsque vous configurez votre page d'inscription, assurez-vous que les utilisateurs peuvent y accéder sans avoir à saisir au préalable un nom d'utilisateur et un mot de passe.

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 Intégration technique, 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 établi de compte dans votre système, il doit cliquer sur le bouton S'inscrire auprès de YOUR_COMPANY_NAME dans Cloud Marketplace. Lorsque l'utilisateur clique sur le bouton, Google Cloud envoie une requête HTTP POST à votre page d'inscription, avec un jeton Web JSON (JWT) dans le paramètre x-gcp-marketplace-token. Ce jeton JWT contient l'ID de compte d'approvisionnement de l'utilisateur, qui l'identifie en tant qu'utilisateur Google Cloud, et un 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 pour associer le compte Google de l'utilisateur à son compte dans votre système.

Remarque :Un même utilisateur peut avoir plusieurs ID de compte d'approvisionnement, ou plusieurs utilisateurs peuvent partager un ID de compte d'approvisionnement commun, selon la façon dont ils ou leur organisation ont configuré leur utilisation de Google Cloud.

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 la procédure d'intégration du backend.

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

Si vous débutez avec les jetons JWT, reportez-vous à l'introduction aux jetons 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 Login URL (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 Intégration technique, puis cliquez sur Intégration de l'interface.

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

Vérifier les informations de connexion SSO de vos clients

Lorsque les clients se connectent à votre application à l'aide de l'authentification unique, Google Cloud envoie une requête HTTP POST à la page de connexion de votre application, avec un jeton Web JSON (JWT) du même format que celui 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 la section Vérifier le jeton 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 l'authentification unique, impliquent l'envoi d'une requête HTTP POST avec un jeton Web JSON (JWT) que vous devrez peut-être valider.

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 l'ID de clé 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/[e-mail]",
  "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 revendication iss renvoie vers 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:

  • account_admin, qui indique que l'utilisateur est un administrateur de compte de facturation (administrateur de commandes) sur le compte de facturation qui a acheté le produit ; ou

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

  Remarque :Si vous avez activé l'authentification unique (SSO), les utilisateurs disposant du rôle account_admin doivent également disposer du rôle project_editor.

• 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

Preview — Multiple orders of the same product

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

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/[e-mail]",
  "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/[e-mail].

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

Remarque :Étant donné que nous pouvons ajouter de nouveaux champs au jeton JWT, vous ne devez pas considérer qu'un jeton JWT n'est pas valide simplement parce qu'il contient de nouveaux champs que vous n'avez pas encore rencontrés.

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 en savoir plus, consultez la documentation sur 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 bien de l'utilisateur auquel vous vous attendiez pour effectuer 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 requête renvoie un ID qui doit correspondre au champ user_identity du jeton JWT.

Créer des comptes de service pour vos clients

Preview

Ce produit ou cette fonctionnalité est soumis aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent bénéficier d'une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Si votre produit nécessite un compte de service, vous pouvez collaborer avec un ingénieur partenaire pour:

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

Vous devez fournir à vos clients le lien vers cette page de compte de service, 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: identifiant produit unique qui permet de distinguer votre produit des autres. Nous vous recommandons d'utiliser le nom de service que vous avez créé lors de l'intégration de 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 utilisés par votre produit au sein d'un même projet.

• Rôles IAM et raisonnement: rôles IAM requis pour les comptes de service et raison pour laquelle ils sont nécessaires. Cette information est partagée avec votre client, ce qui peut avoir une incidence sur son 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 à la console de votre produit

L'ingénieur partenaire crée une page de gestion des comptes de service pour permettre à vos clients d'accorder l'accès aux comptes de service. Vous pouvez ensuite créer un lien vers cette page depuis votre console.

Une fois que votre ingénieur partenaire vous a informé que la page de gestion des comptes de service est prête, ajoutez des paramètres à l'URL, puis créez un lien vers cette page depuis votre 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 de vos clients. 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 à la page de gestion des comptes de service:

Paramètres	Description
service-name	Ce champ est obligatoire. Il s'agit du nom de service que vous avez fourni à votre ingénieur partenaire.
service-account-email	Ce champ est obligatoire. Il s'agit de l'adresse e-mail du compte de service que vous avez créé pour votre client.
single	Lorsque la valeur est "true", cela signifie que votre produit nécessite un accès à un seul projet.
hints=project-id-1	Définit le projet auquel vous souhaitez que le compte de service accède. Utilisez des virgules pour séparer les projets.
filter=role1	Les 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.
redirect	Fournit 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.