Integrar o front-end do app

Esta página descreve como integrar o front-end do app ao Cloud Marketplace para oferecer aos clientes uma experiência tranquila quando eles passam do Cloud Marketplace para o produto.

De modo geral, você precisa fornecer um URL de inscrição para processar a criação de contas de usuários, que são gerenciadas no seu web console. Você também precisa fornecer um URL para os usuários fazerem login. Opcionalmente, é possível integrar o Logon único (SSO).

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

Para acessar todas as informações necessárias para integrar o front-end do app ao Cloud Marketplace em um só 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 você não encontrar o link ou não conseguir acessar o URL, verifique se selecionou o projeto correto. Se ainda não for possível acessar o URL, use a Central de suporte ao parceiro para solicitar ajuda e incluir a palavra "Marketplace" na sua descrição. Para mais informações sobre Partner Support Desk, acesse Solicitar assistência 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 produto, acesse a seção Integração técnica e clique em Integração de front-end.

Adicionar o URL de inscrição

Quando os usuários compram seu produto no Cloud Marketplace, você precisa criar uma conta com seu produto para eles. Para isso, você precisa criar uma página de inscrição para configurar e aprovar as contas dos usuários no seu sistema. É possível configurar a página como uma página de registro em que os usuários precisam se inscrever para ter uma conta no 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 podem acessá-la sem antes inserir um nome de usuário e uma senha.

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

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

2. Na página Visão geral do 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 criado uma conta no seu sistema, ele precisará clicar no botão Register with YOUR_COMPANY_NAME no Cloud Marketplace. Quando o usuário clica 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 os identifica como um usuário do Google Cloud, e um ID ofuscado, que representa o ID da conta do Google. Use o ID da conta de compra 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 suprimentos ou que vários usuários compartilhem um ID de conta de suprimentos 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 do back-end.

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

Se você não tem experiência com JWTs, consulte a introdução do JWT.

Adicionar seu URL de login

É necessário especificar o URL da página de login do app.

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

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

2. Na página Visão geral do 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 login do app 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 produto, acesse a seção Integração técnica e clique em Integração de front-end.

   2. Em Ativar o login por SSO?, selecione Sim.

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

Quando os clientes fazem login no seu app usando o SSO, o Google Cloud envia uma solicitação HTTP POST para a página de login do app com um Token da Web JSON (JWT) do mesmo formato do JWT enviado quando os usuários se inscreveram pela primeira vez no 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 token da Web JSON (JWT) que pode ser necessário 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 envolvido.
• Se é necessário verificar o JWT.

Evento	Tipo de solicitação HTTP	Verificação do JWT necessária
Inscrever um novo cliente	POST	Sim
Login do cliente, sem SSO	GET	Não
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 que foi 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
  }
}

Onde:

• 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 vincula 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 uma das seguintes opções:

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

  • project_editor, que indica que o usuário é um editor (administrador de direitos), mas não um administrador de faturamento, do projeto nessa 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 GAIA ofuscado do usuário, que pode ser usado para iniciar o OpenID Connect.

Payload para vários pedidos do mesmo produto

Se você tiver ativado vários pedidos do mesmo produto, o payload vai incluir um objeto orders adicional. Isso inclui o ID de pedido exclusivo correspondente ao ID de direito de acesso 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 IDs de pedidos exclusivos para cada ID de direito que indica as diferentes ofertas do mesmo produto. Esse campo só fica disponível quando a opção de vários pedidos do mesmo produto está ativada.

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 do JWT usa a chave pública do Google.

2. Verifique se o JWT não expirou, verificando 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 podemos adicionar novos campos ao JWT, não considere um JWT inválido apenas porque ele 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, acesse 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 você espera que conclua 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.

Criar 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:

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

É necessário fornecer o link para a página da conta de serviço aos clientes, geralmente pelo 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 de produto exclusivo que diferencia seu produto de outros. Recomendamos usar o nome do serviço que você criou quando integrou o produto.

• ID do projeto: o ID do projeto em que você cria as contas de serviço que acessam os recursos dos clientes. É necessário criar 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 o motivo da necessidade dos papéis. 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 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, vincule a página ao seu console.

Quando o engenheiro de parceiros notificar 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

Você pode adicionar outros parâmetros de acordo com as 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 o produto requer acesso a um único projeto do Google Cloud e que o cliente pode retornar ao console.

Lista de parâmetros de URL

Confira a seguir uma lista dos parâmetros de URL que você pode enviar 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.