En esta página, se describe cómo integrar el frontend de tu app en Cloud Marketplace para brindar 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 administrar la creación de cuentas de 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
A fin de acceder a toda la información que necesitas para integrar el frontend de tu app en 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
Para acceder a la sección Integración de frontend, haz lo siguiente:
En la lista de productos, haz clic en el nombre del producto.
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 crearles una cuenta con él. 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 apruebe cuentas automáticamente.
Después de crear la página de registro, agrégala a Producer Portal:
En la lista de productos, haz clic en el nombre del producto.
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.
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 Registrar con YOUR_COMPANY_NAME
en Cloud Marketplace. Cuando hace 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 el ID de la cuenta de adquisición y el ID ofuscado para vincular la Cuenta de Google del usuario a su cuenta en tu sistema.
Después de verificar el JWT, tu página de registro debe enviar una solicitud de aprobación de la 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 Verificar 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.
Sigue estos pasos para ingresar la URL de la página de acceso de tu app en Producer Portal:
En la lista de productos, haz clic en el nombre del producto.
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.
Ingresa la URL de la página de acceso de tu app en el campo URL de acceso.
(Opcional) Habilita el inicio de sesión único (SSO) para tus clientes
Para habilitar el SSO en Producer Portal, haz lo siguiente:
En la lista de productos, haz clic en el nombre del producto.
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.
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 la app mediante el 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 la app.
Para obtener información detallada sobre la carga útil de JWT y cómo verificarla, consulta Verificar el JWT a continuación.
Verifica el JWT
Algunos procesos, como el registro de un cliente nuevo o el acceso de un cliente con SSO, implican el envío de una solicitud HTTP POST
con un token web JSON (JWT) que quizás 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" }
Dónde:
alg
siempre esRS256
.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 atributoiss
en la carga útil.
Carga útil
{ "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 } }
Dónde:
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 deiss
se 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, comoexample.com
.roles
es un arreglo de strings que representan las funciones del usuario. Puede ser cualquiera de las siguientes opciones:account_admin
, que indica que el usuario es un administrador de la cuenta de facturación (administrador de pedidos) de la cuenta de facturación que compró el productoproject_editor
, que indica que el usuario es editor (administrador de derechos), pero no administrador de facturación, del proyecto en esa cuenta de facturación.
user_identity
es el ID de GAIA ofuscado del usuario, que se puede usar para iniciar OpenID Connect.
Verifica la carga útil
Cuando recibas el JWT, debes verificar lo siguiente:
Verifica que la firma JWT use la clave pública de Google.
Verifica que el JWT no haya vencido. Para ello, verifica la reclamación
exp
.Verifica que la reclamación
aud
sea el dominio correcto para tu producto.Verifica que la reclamación
iss
seahttps://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com
.Verifica que
sub
no esté vacío.
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
.
Consulta la documentación de Google OAuth 2.0 para obtener más información.
Después de 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
Si tu producto requiere una cuenta de servicio, puedes trabajar con un ingeniero socio para hacer lo siguiente:
- 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 necesarios de Identity and Access Management (IAM) a las cuentas de servicio.
Debes proporcionar a tus clientes el vínculo a la página de esta cuenta de servicio, por lo general, a través de la consola de administración del producto.
Aprovisiona las cuentas de servicio
Para aprovisionar las cuentas de servicio, comunícate con el Ingeniero socio y agrega 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: 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 use dentro de un solo proyecto.
Funciones de IAM y razonamiento: Son las funciones de IAM necesarias para las cuentas de servicio y el motivo por el que son necesarias. Esto se comparte con tu cliente y puede afectar si este otorga acceso a la cuenta de servicio.
Si quieres que tu cliente vuelva a tu sitio después de que otorgue acceso a la cuenta de servicio, envíale el nombre de dominio de tu consola al Ingeniero socio. Puedes enviar varios nombres de dominio, incluidos subdominios, como staging.example.com
.
Integra la página de administración de la cuenta 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, establece un vínculo a la página desde la consola.
Una vez que tu Ingeniero socio 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 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 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 cuentas de servicio:
Parámetro | Descripción |
---|---|
service-name | Este campo es obligatorio. Este es el nombre de 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 | Configura 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 a tu Ingeniero socio. Excluir roles/ cuando uses el filtro |
redirect | Proporciona un vínculo para que el cliente regrese a la consola de administración. El nombre del dominio debe estar registrado con el ingeniero socio para usar este parámetro. |