Integrar o front-end do seu app

Nesta página, descrevemos como integrar o front-end do seu app ao Cloud Marketplace para oferecer aos clientes uma experiência tranquila quando eles migrarem do Cloud Marketplace para seu produto.

Em um nível superior, você precisa fornecer um URL de inscrição para processar a criação de contas de usuários, que serão gerenciadas no console da Web. Você também precisa fornecer um URL para que os usuários façam login. Também é possível integrar o Logon único (SSO).

Usar o Portal do Produtor para integrar o front-end do seu app

Para acessar todas as informações necessárias para integrar o front-end do seu app ao Cloud Marketplace em um local, use a seção Integração de front-end do Portal do Produtor.

O link direto para o Portal do Produtor é:

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

Observação: se o link não aparecer ou não for possível acessar o URL, verifique se você selecionou o projeto correto. Se ainda não for possível acessar o URL, use o Partner Support Desk para solicitar ajuda e inclua a palavra "Marketplace" na descrição. Para mais informações sobre o Partner Support Desk, acesse Solicitar ajuda com o Cloud Marketplace.

Para acessar a seção Integração de front-end:

1. Na lista de produtos, clique no nome do seu produto.

2. Na página Visão geral do seu produto, acesse a seção Integração técnica e clique em Integração de front-end.

Adicione seu URL de inscrição

Quando os usuários compram seu produto no Cloud Marketplace, é necessário criar uma conta com seu produto para eles. Para fazer isso, é preciso criar uma página de inscrição para configurar e aprovar contas de usuários no seu sistema. É possível configurá-la como uma página de registro em que os usuários se inscrevem para uma conta no seu sistema ou como uma página que aprova contas automaticamente.

Atenção :ao configurar a página de inscrição, verifique se os usuários conseguem acessá-la sem digitar um nome de usuário e uma senha.

Depois de criar a página de inscrição, adicione-a ao Portal do Produtor:

1. Na lista de produtos, clique no nome do seu produto.

2. Na página Visão geral do seu produto, acesse a seção Integração técnica e clique em Integração de front-end.

3. Insira o URL da página de inscrição no campo URL de inscrição.

Verificar as informações de inscrição do usuário

Se um usuário ainda não tiver estabelecido uma conta no seu sistema, ele precisará clicar no botão Registrar com YOUR_COMPANY_NAME no Cloud Marketplace. Ao clicar no botão, o Google Cloud envia uma solicitação HTTP POST para sua página de inscrição, com um JSON Web Token (JWT) no parâmetro x-gcp-marketplace-token. O JWT contém o ID da conta de compras do usuário, que o identifica como um usuário do Google Cloud, e um ID ofuscado, que representa o ID da Conta do Google. É necessário usar o ID da conta de compras e o ID ofuscado para vincular a Conta do Google do usuário à conta dele no seu sistema.

Observação: é possível que um único usuário tenha vários IDs de conta de compras ou que vários usuários compartilhem um ID de conta de compras comum, dependendo de como eles ou a organização configuraram o uso do Google Cloud.

Depois de verificar o JWT, sua página de inscrição precisa enviar uma solicitação de aprovação de conta para a API Partner Procurement, descrita nas etapas de integração de back-end.

Para informações detalhadas sobre o payload do JWT e como verificá-lo, consulte Verificar o JWT abaixo.

Se você não tiver experiência com JWTs, consulte a Introdução ao JWT.

Adicione seu URL de login

Você precisa especificar o URL da página de login do seu app.

Para inserir o URL da página de login do seu app no Portal do Produtor:

1. Na lista de produtos, clique no nome do seu produto.

2. Na página Visão geral do seu produto, acesse a seção Integração técnica e clique em Integração de front-end.

3. Digite o URL da página de login do aplicativo no campo URL de login.

(Opcional) Ativar o Logon único (SSO) para seus clientes

Para ativar o SSO no Portal do Produtor:

1. Na lista de produtos, clique no nome do seu produto.

   1. Na página Visão geral do seu produto, acesse a seção Integração técnica e clique em Integração de front-end.

   2. Em Enable SSO login?, selecione Yes.

Verificar as informações de login via SSO dos seus clientes

Quando os clientes fazem login no seu app usando SSO, o Google Cloud envia uma solicitação HTTP POST para a página de login do app, com um JSON Web Token (JWT) do mesmo formato que o JWT enviado quando os usuários se inscrevem pela primeira vez no seu app.

Para informações detalhadas sobre o payload do JWT e como verificá-lo, consulte Verificar o JWT abaixo.

Verificar o JWT

Alguns processos, como a inscrição de um novo cliente ou o login de um cliente com SSO, envolvem o envio de uma solicitação HTTP POST com um JSON Web Token (JWT) que talvez você precise verificar.

A tabela a seguir lista:

• Eventos que envolvem o envio de uma solicitação HTTP com um JWT.
• O tipo de solicitação HTTP envolvida.
• Se você precisa ou não verificar o JWT.

Evento	Tipo de solicitação HTTP	Verificação do JWT obrigatória
Inscrever um novo cliente	POST	Sim
Login do cliente sem SSO	GET	No
Login do cliente com SSO	POST	Sim

O payload do JWT

O payload do JWT está no seguinte formato:

Cabeçalho

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

Em que:

• alg é sempre RS256.
• kid indica o ID da chave usado para proteger o JWT. Use o ID da chave para procurar a chave do objeto JSON no atributo iss no payload.

Payload

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

Em que:

• sub é o ID da conta do Google do usuário. Use esse ID para vincular a Conta do Google do usuário à conta dele no seu sistema.
• iss identifica o remetente do JWT. O URL na declaração iss é vinculado a uma chave pública do Google.
• exp indica quando o token expira e é definido como 5 minutos depois do envio do token.
• aud é o domínio que hospeda seu produto, como example.com.

• roles é uma matriz de strings que representam os papéis do usuário. Pode ser:

  • account_admin, que indica que o usuário é um Administrador da conta de faturamento (administrador do pedido) da conta de faturamento que comprou o produto ou

  • project_editor, que indica que o usuário é um Editor (Gerenciador de direitos), mas não um Administrador de faturamento do projeto dessa conta de faturamento.

  Observação: se você ativou o Logon único (SSO), os usuários com o papel account_admin também precisam ter o papel project_editor.

• user_identity é o ID do GAIA ofuscado do usuário, que pode ser usado para iniciar o OpenID Connect.

Payload para vários pedidos do mesmo produto

Visualização — Multiple orders of the same product

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Se você tiver ativado vários pedidos do mesmo produto, o payload incluirá um objeto orders extra. Isso inclui o ID exclusivo do pedido correspondente ao ID do direito de cada pedido. Verifique se a página de login do app pode responder a esse novo 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]
  }
}

Em que:

• ORDER_ID é uma lista de códigos de pedido exclusivos para cada ID de direito que indica as diferentes ofertas do mesmo produto. Esse campo estará disponível somente se vários pedidos do mesmo produto estiverem ativados.

Para mais informações sobre como ativar vários pedidos do mesmo produto, consulte Ativar vários pedidos do mesmo produto.

Verificar o payload

Quando você recebe o JWT, verifique o seguinte:

1. Verifique se a assinatura JWT está usando a chave pública do Google.

2. Verifique se o JWT não expirou conferindo a declaração exp.

3. Verifique se a declaração aud é o domínio correto para seu produto.

4. Verifique se a declaração iss é https://www.googleapis.com/robot/v1/metadata/x509/[e-mail]

5. Verifique se sub não está vazio.

Observação: como é possível adicionar novos campos ao JWT, não considere um JWT inválido só porque contém novos campos que você ainda não encontrou.

Iniciar o login do Google com login_hint

Se você quiser que os usuários passem por um fluxo de consentimento do OAuth 2.0 com seu site, use as informações de identidade do payload para inicializar esse fluxo na Conta do Google que estavam usando para o Google Cloud antes do redirecionamento. Para fazer isso, forneça o user_identity fornecido no JWT como o login_hint. Para mais informações, consulte a documentação do Google OAuth 2.0.

Depois que o usuário concluir o fluxo do OAuth 2.0 com seu site, verifique se ele é o usuário que precisa concluir o fluxo do OAuth. Para fazer isso, use o token de acesso do OAuth 2.0 para chamar a API Google UserInfo e buscar as informações básicas do usuário. Isso retorna um ID que precisa corresponder ao campo user_identity do JWT.

Crie contas de serviço para seus clientes

Visualização

Este produto ou recurso está sujeito aos "Termos das ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos do serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Se o produto exigir uma conta de serviço, trabalhe com um engenheiro de parceiros para:

• Provisionar contas de serviço para seus clientes
• Configure uma página de gerenciamento de conta de serviço para que seus clientes concedam os papéis do Identity and Access Management (IAM) necessários às contas de serviço.

Você precisa fornecer o link para esta página da conta de serviço aos seus clientes, geralmente por meio do console de gerenciamento do produto.

Provisionar as contas de serviço

Para provisionar as contas de serviço, entre em contato com o engenheiro de parceiros e inclua as seguintes informações:

• Nome do serviço: um ID do produto exclusivo que diferencia seu produto de outros. Recomendamos usar o nome de serviço que você criou quando integrou seu produto.

• ID do projeto: o ID do projeto em que você cria as contas de serviço que acessam os recursos dos clientes. Crie todas as contas de serviço que seu produto usa em um único projeto.

• Papéis e raciocínio do IAM: os papéis do IAM necessários para as contas de serviço e por que eles são necessários. Isso é compartilhado com seu cliente e pode afetar se ele concede acesso à conta de serviço.

Se você quiser que o cliente volte ao site depois de conceder acesso à conta de serviço, envie o nome de domínio do console ao engenheiro parceiro. É possível enviar vários nomes de domínio, inclusive subdomínios, como staging.example.com.

Integrar a página de gerenciamento da conta de serviço ao console do seu produto

O engenheiro de parceiros cria uma página de gerenciamento de conta de serviço para permitir que seus clientes concedam acesso a elas. Em seguida, você cria um link para a página no seu console.

Depois que o engenheiro de parceiros notificar você de que a página de gerenciamento da conta de serviço está pronta, adicione parâmetros ao URL e vincule-a à página no console.

É preciso adicionar dois parâmetros ao URL:

• service-name: é o nome do serviço que você forneceu ao engenheiro de parceiros.

• service-account-email: é o endereço de e-mail da conta de serviço que você criou para o cliente. Cada cliente tem uma conta de serviço exclusiva.

O exemplo a seguir mostra um URL com os parâmetros necessários:

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

É possível adicionar outros parâmetros dependendo das necessidades dos seus clientes. Exemplo:

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

Os parâmetros do URL indicam que seu produto requer acesso a um único projeto do Google Cloud e que o cliente pode retornar ao seu console.

Lista de parâmetros de URL

Veja a seguir uma lista dos parâmetros de URL que podem ser enviados para a página de gerenciamento da conta de serviço:

Parâmetro	Descrição
service-name	Obrigatório. Esse é o nome do serviço que você forneceu ao engenheiro de parceiros.
service-account-email	Obrigatório. Este é o endereço de e-mail da conta de serviço que você criou para o cliente.
single	Quando verdadeiro, isso indica que seu produto precisa de acesso a um único projeto.
hints=project-id-1	Define o projeto que você quer que a conta de serviço acesse. Use vírgulas para separar projetos.
filter=role1	Limita os papéis concedidos à conta de serviço a um subconjunto dos papéis fornecidos ao engenheiro parceiro. Exclua o roles/ ao usar o filtro.
redirect	Fornece um link para o cliente retornar ao console de gerenciamento. O nome de domínio precisa ser registrado com seu engenheiro de parceiros para usar esse parâmetro.