Integra el frontend de tu app

En esta página, se describe cómo integrar el frontend de tu app en Cloud Marketplace para brindar a los clientes una experiencia fluida cuando pasan de Cloud Marketplace a tu producto.

En un nivel alto, debes proporcionar una URL de registro para controlar la creación de cuentas de usuario, que luego se administran en tu consola web. También debes proporcionar una URL para que los usuarios accedan. De forma opcional, también puedes integrar el inicio de sesión único (SSO).

Usa Producer Portal para integrar el frontend de tu app

Si quieres acceder a toda la información que necesitas para integrar el frontend de tu app con Cloud Marketplace desde una ubicación, puedes usar la sección Integración de frontend de Producer Portal.

El vínculo directo a Producer Portal es el siguiente:

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

Nota: Si no ves el vínculo o no puedes acceder a la URL, verifica que hayas seleccionado el proyecto correcto. Si aún no puedes acceder a la URL, usa Partner Support Desk para solicitar asistencia y, luego, incluye la palabra “Marketplace” en tu descripción. Para obtener más información sobre Partner Support Desk, consulta Solicita asistencia con Cloud Marketplace.

Para acceder a la sección Integración de frontend, haz lo siguiente:

1. En la lista de productos, haz clic en el nombre del producto.

2. En la página Descripción general de tu producto, ve a la sección Integración técnica y haz clic en Integración frontend.

Agrega tu URL de registro

Cuando los usuarios compren tu producto en Cloud Marketplace, debes crearles una cuenta con tu producto. Para ello, debes crear una página de registro a fin de configurar y aprobar las cuentas de los usuarios en tu sistema. Puedes configurar la página como una página de registro en la que los usuarios se registran para obtener una cuenta en tu sistema, o como una página que aprueba cuentas automáticamente.

Precaución: Cuando configures la página de registro, asegúrate de que los usuarios puedan acceder a ella sin primero ingresar un nombre de usuario y una contraseña.

Después de crear la página de registro, agrégala en Producer Portal:

1. En la lista de productos, haz clic en el nombre del producto.

2. En la página Descripción general de tu producto, ve a la sección Integración técnica y haz clic en Integración frontend.

3. Ingresa la URL de tu página de registro en el campo URL de registro.

Verifica la información de registro del usuario

Si un usuario aún no estableció una cuenta en tu sistema, debe hacer clic en el botón Registrarse con YOUR_COMPANY_NAME en Cloud Marketplace. Cuando hacen clic en el botón, Google Cloud envía una solicitud HTTP POST a tu página de registro, con un token web JSON (JWT) en el parámetro x-gcp-marketplace-token. El JWT contiene el ID de la cuenta de adquisición del usuario, que lo identifica como un usuario de Google Cloud, y un ID ofuscado, que representa el ID de su Cuenta de Google. Debes usar tanto el ID de la cuenta de adquisición como el ID ofuscado para vincular la Cuenta de Google del usuario con su cuenta en tu sistema.

Nota: Es posible que un solo usuario tenga varios IDs de cuenta de adquisición o que varios usuarios compartan un ID de cuenta de adquisición común, según la forma en que ellos o su organización hayan configurado el uso de Google Cloud.

Después de verificar el JWT, tu página de registro debe enviar una solicitud de aprobación de cuenta a la API de Partner Procurement, como se describe en los pasos de integración del backend.

Para obtener información detallada sobre la carga útil de JWT y cómo verificarla, consulta Verifica el JWT a continuación.

Si es la primera vez que trabajas con JWT, consulta la introducción a JWT.

Agrega tu URL de acceso

Debes especificar la URL de la página de acceso de tu app.

Para ingresar la URL de la página de acceso de tu app en Producer Portal, haz lo siguiente:

1. En la lista de productos, haz clic en el nombre del producto.

2. En la página Descripción general de tu producto, ve a la sección Integración técnica y haz clic en Integración frontend.

3. Ingresa la URL de la página de acceso de tu app en el campo URL de acceso.

Habilita el inicio de sesión único (SSO) para tus clientes (opcional)

Para habilitar el SSO en Producer Portal, haz lo siguiente:

1. En la lista de productos, haz clic en el nombre del producto.

   1. En la página Descripción general de tu producto, ve a la sección Integración técnica y haz clic en Integración de frontend.

   2. En ¿Habilitar el acceso SSO?, selecciona Sí.

Verifica la información de acceso al SSO de tus clientes

Cuando los clientes acceden a tu app mediante SSO, Google Cloud envía una solicitud HTTP POST a la página de acceso de la app, con un token web JSON (JWT) del mismo formato que el JWT que se envía cuando los usuarios se registran por primera vez en tu app.

Para obtener información detallada sobre la carga útil de JWT y cómo verificarla, consulta Verifica el JWT a continuación.

Verifica el JWT

Algunos procesos, como el registro de un cliente nuevo o el registro de un cliente con SSO, implican el envío de una solicitud HTTP POST con un token web JSON (JWT) que es posible que debas verificar.

En la siguiente tabla, se muestra lo siguiente:

• Eventos que implican el envío de una solicitud HTTP con un JWT.
• El tipo de solicitud HTTP involucrada.
• Indica si debes verificar el JWT o no.

Evento	Tipo de solicitud HTTP	Se requiere verificación de JWT
Registrar un cliente nuevo	POST	Sí
Acceso del cliente sin SSO	GET	No
Acceso del cliente con SSO	POST	Sí

La carga útil de JWT

La carga útil de JWT está en el siguiente formato:

Encabezado

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

Aquí:

• alg siempre es RS256.
• kid indica el ID de clave que se usó para proteger el JWT. Usa el ID de clave para buscar la clave del objeto JSON en el atributo iss de la carga útil.

Carga útil

{
  "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
  }
}

Aquí:

• sub es el ID de la Cuenta de Google del usuario. Debes usar este ID para vincular la Cuenta de Google del usuario con su cuenta en tu sistema.
• iss identifica el remitente del JWT. La URL de la reclamación iss vincula a una clave pública de Google.
• exp indica cuándo vence el token y se establece en 5 minutos después de que se envía el token.
• aud es el dominio que aloja tu producto, como example.com.

• roles es un arreglo de strings que representan las funciones del usuario. Puede ser una de las siguientes opciones:

  • account_admin, que indica que el usuario es un Administrador de cuentas de facturación (Administrador de pedidos) de la cuenta de facturación que compró el producto.

  • project_editor: Indica que el usuario es un editor (administrador de derechos), pero no un administrador de facturación del proyecto en esa cuenta de facturación.

  Nota: Si habilitaste el inicio de sesión único (SSO), los usuarios con la función account_admin también deben tener la función project_editor.

• user_identity es el ID de GAIA ofuscado del usuario, que se puede usar para iniciar OpenID Connect.

Carga útil para varios pedidos del mismo producto

Vista previa — Multiple orders of the same product

Esta función está sujeta a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Si habilitaste varios pedidos del mismo producto, la carga útil incluirá un objeto orders adicional. Esto incluye el ID de pedido único correspondiente al ID de derecho de cada pedido. Asegúrate de que la página de acceso de tu app pueda responder a este nuevo campo 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]
  }
}

Aquí:

• ORDER_ID es una lista de IDs de pedido únicos para cada ID de derecho que indican las diferentes ofertas del mismo producto. Este campo solo está disponible si se habilitan varios pedidos del mismo producto.

Si quieres obtener más información para activar varios pedidos del mismo producto, consulta Cómo activar varios pedidos del mismo producto.

Verifica la carga útil

Cuando recibas el JWT, debes verificar lo siguiente:

1. Verifica que la firma de JWT use la clave pública de Google.

2. Para verificar que el JWT no haya vencido, revisa la reclamación de exp.

3. Verifica que la reclamación aud sea el dominio correcto para tu producto.

4. Verifica que la reclamación iss sea https://www.googleapis.com/robot/v1/metadata/x509/[e-mail].

5. Verifica que sub no esté vacío.

Nota: Debido a que podríamos agregar campos nuevos al JWT, no debes considerar que un JWT no es válido solo porque contiene campos nuevos que aún no conoces.

Iniciar Acceso con Google con login_hint

Si deseas que tus usuarios pasen por un flujo de consentimiento de OAuth 2.0 con tu sitio, puedes usar la información de identidad de la carga útil para inicializar ese flujo en la Cuenta de Google que usaban para Google Cloud antes del redireccionamiento. Para ello, debes proporcionar el user_identity proporcionado en el JWT como el login_hint. Para obtener más información, consulta la documentación de Google OAuth 2.0.

Una vez que el usuario complete el flujo de OAuth 2.0 con tu sitio, debes verificar que sea el usuario que esperabas que completara el flujo de OAuth. Para ello, usa el token de acceso de OAuth 2.0 a fin de llamar a la API de UserInfo de Google y recuperar la información básica del usuario. Esto muestra un ID que se espera que coincida con el campo user_identity del JWT.

Crea cuentas de servicio para tus clientes

Vista previa

Este producto o función está sujeto a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones específicas del Servicio. Los productos y las funciones que se encuentran en la fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Si tu producto requiere una cuenta de servicio, puedes trabajar con un ingeniero socio para realizar las siguientes acciones:

• Aprovisionar cuentas de servicio para tus clientes
• Configura una página de administración de cuentas de servicio para que tus clientes otorguen los roles de Identity and Access Management (IAM) necesarios a las cuentas de servicio.

Debes proporcionar el vínculo a esta página de cuenta de servicio a tus clientes, por lo general, a través de la consola de administración de tu producto.

Aprovisiona las cuentas de servicio

Para aprovisionar las cuentas de servicio, comunícate con tu Ingeniero socio y, además, incluye la siguiente información:

• Nombre del servicio: Es un ID del producto único que diferencia tu producto de otros. Te recomendamos usar el nombre del servicio que creaste cuando incorporaste tu producto.

• ID del proyecto: Es el ID del proyecto en el que creas las cuentas de servicio que acceden a los recursos de tus clientes. Debes crear todas las cuentas de servicio que tu producto usa dentro de un solo proyecto.

• Funciones y razonamiento de IAM: Las funciones de IAM necesarias para las cuentas de servicio y el motivo por el que las funciones son necesarias. Esto se comparte con tu cliente y puede afectar si este otorga acceso a la cuenta de servicio.

Si deseas que el cliente regrese a tu sitio después de otorgar acceso a la cuenta de servicio, envía el nombre de dominio de tu consola a tu Ingeniero socio. Puedes enviar varios nombres de dominio, incluidos los subdominios, como staging.example.com.

Integra la página de administración de cuentas de servicio en la consola de tu producto

El ingeniero socio crea una página de administración de cuentas de servicio para permitir que tus clientes otorguen acceso a ellas. Luego, debes vincular la página desde tu consola.

Después de que el ingeniero socio te notifique que la página de administración de cuentas de servicio está lista, agrega parámetros a la URL y, luego, vincula la página desde tu consola.

Debes agregar dos parámetros a la URL:

• service-name: Este es el nombre del servicio que le proporcionaste a tu Ingeniero socio.

• service-account-email: Esta es la dirección de correo electrónico de la cuenta de servicio que creaste para tu cliente. Cada cliente tiene una cuenta de servicio única.

En el siguiente ejemplo, se muestra una URL con los parámetros obligatorios:

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

Puedes agregar parámetros adicionales según las necesidades de tus clientes. Por ejemplo:

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

Los parámetros de la URL indican que tu producto requiere acceso a un solo proyecto de Google Cloud y que el cliente puede regresar a tu consola.

Lista de parámetros de URL

La siguiente es una lista de los parámetros de URL que puedes enviar a la página de administración de cuentas de servicio:

Parámetro	Descripción
service-name	Este campo es obligatorio. Este es el nombre del servicio que le proporcionaste a tu Ingeniero socio.
service-account-email	Este campo es obligatorio. Esta es la dirección de correo electrónico de la cuenta de servicio que creaste para tu cliente.
single	Cuando es verdadero, esto indica que tu producto requiere acceso a un solo proyecto.
hints=project-id-1	Establece el proyecto al que deseas que acceda la cuenta de servicio. Usa comas para separar los proyectos.
filter=role1	Limita los roles otorgados a la cuenta de servicio a un subconjunto de los roles que le proporcionaste al Ingeniero socio. Excluye roles/ cuando uses el filtro.
redirect	Proporciona un vínculo para que el cliente regrese a la consola de administración. El nombre de dominio debe estar registrado con el Ingeniero socio para poder usar este parámetro.