Integra el frontend de tu app

En esta página, se describe cómo integrar el frontend de tu app con Cloud Marketplace para brindarles a tus clientes una experiencia fluida cuando pasen de Cloud Marketplace a tu producto.

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

Usa Producer Portal para integrar el frontend de tu app

Para 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 si seleccionaste el proyecto correcto. Si aún no puedes acceder a la URL, usa el Partner Support Desk para solicitar asistencia y, luego, incluye la palabra "Mercado" en la descripción. Para obtener más información sobre el Partner Support Desk, consulta Cómo solicitar 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 de frontend.

Agrega tu URL de registro

Cuando los usuarios compran tu producto en Cloud Marketplace, debes crear una cuenta con tu producto para ellos. Para ello, debes crear una página de registro para 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 las cuentas automáticamente.

Precaución: Cuando configures tu página de registro, asegúrate de que los usuarios puedan acceder a ella sin ingresar un nombre de usuario y 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 de 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 usuario de Google Cloud, y un ID ofuscado, que representa el ID de su cuenta de Google. Debes usar el ID de la cuenta de adquisición y 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 cómo 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, que se describe en los pasos de integración de 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, sigue estos pasos:

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 de 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 ¿Quieres habilitar el acceso a SSO?, selecciona Sí.

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

Cuando los clientes acceden a tu app con el SSO, Google Cloud envía una solicitud HTTP POST a la página de acceso de tu 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 registrar un cliente nuevo o acceder a su cuenta con la SSO, implican enviarte una solicitud HTTP POST con un token web JSON (JWT) que es posible que debas verificar.

En la siguiente tabla, se incluyen los siguientes datos:

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

Event	Tipo de solicitud HTTP	Verificación de JWT obligatoria
Registra 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 claves que se usó para asegurar el JWT. Puedes usar el ID de claves con el fin de buscar la clave del objeto de JSON en el atributo iss en 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 en la reclamación de ississ 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, o

  • project_editor, que 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 el rol account_admin también deben tener el rol 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

Si habilitaste varios pedidos del mismo producto, la carga útil incluye un objeto orders adicional. Esto incluye el ID de pedido único que corresponde 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 pedidos únicos para cada ID de derecho que indica las diferentes ofertas del mismo producto. Este campo solo está disponible si se habilitan varios pedidos del mismo producto.

Para obtener más información sobre cómo 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. Verifica que el JWT no haya vencido. Para ello, verifica la reclamación 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 podemos agregar campos nuevos al JWT, no debes considerar un JWT no válido solo porque contiene campos nuevos que aún no conoces.

Inicia el 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, visita la documentación de OAuth 2.0 de Google.

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 asociado para hacer lo siguiente:

• Aprovisiona 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 la 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 de socios y, luego, incluye la siguiente información:

• Nombre del servicio: Es un ID de producto único que diferencia tu producto de otros. Te recomendamos que uses el nombre del servicio que creaste cuando integraste 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 use tu producto dentro de un solo proyecto.

• Roles y razonamiento de IAM: Los roles de IAM necesarios para las cuentas de servicio y el motivo por el que son necesarios. Esta información se comparte con tu cliente y puede afectar si este otorga acceso a la cuenta de servicio.

Si quieres 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 de socios. Puedes enviar varios nombres de dominio, incluidos 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 las cuentas de servicio. Luego, vincula la página desde la consola.

Una vez que el ingeniero de socios te notifique que la página de administración de la cuenta de servicio está lista, agrega parámetros a la URL y, luego, vincula la página desde la consola.

Debes agregar dos parámetros a la URL:

• service-name: Es el nombre del servicio que le proporcionaste a tu ingeniero asociado.

• service-account-email: 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 volver 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 la cuenta 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	Si es verdadero, 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 proporcionaste a tu ingeniero asociado. Excluye el roles/ cuando uses el filtro.
redirect	Proporciona un vínculo para que el cliente regrese a tu consola de administración. Para usar este parámetro, el nombre de dominio debe estar registrado con tu ingeniero socio.