Integrar o front-end do seu 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.

Em um nível alto, você deve fornecer um URL de inscrição para lidar com a criação de usuários , que são gerenciadas no seu console da Web. Você também deve fornecer um URL para os usuários fazerem login. Também é 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 seu aplicativo com Cloud Marketplace de um local, é possível usar o 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 vir o link ou não conseguir acessar o URL, verifique se e selecionou o projeto correto. Se ainda não conseguir acessar o URL, use o Partner Support Desk para solicitar assistência e inclua a palavra "Marketplace" na sua descrição. Para mais informações sobre o Partner Support Desk, acesse Solicite 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 seu produto, acesse 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 um em conta com seu produto. Para isso, você deve criar uma página de inscrição para configurar e aprovar no seu sistema. Você pode configurar a página como uma página de registro em que os usuários se inscrevem em uma conta no seu sistema ou como um que aprova contas automaticamente.

Atenção :ao configurar sua página de inscrição, verifique se os usuários conseguem acessar 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 página Técnicas integração 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 ele clica no botão, o Google Cloud envia uma HTTP POST na sua página de inscrição, com um JSON Web Token (JWT) no x-gcp-marketplace-token. O JWT contém o arquivo ID da conta de compras, que os identifica como um usuário do Google Cloud, e uma ID ofuscado, que representa o ID da Conta do Google. É necessário usar o parâmetro o ID da conta de compras e o ID ofuscado para vincular a Conta do Google do usuário à conta deles no seu sistema.

Observação: é possível que um único usuário tenha vários IDs de conta de compras. ou vários usuários compartilhem o mesmo ID da conta de compras, 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 deve enviar uma solicitação de aprovação da conta para a API Partner Procurement, descrita no etapas de integração de back-end.

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

Se você é novo no trabalho 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 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 página Técnicas integração 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 página Técnicas integração e clique em Integração de front-end.

   2. Em Enable SSO login?, selecione Yes.

Verifique os dados dos seus clientes Informações de login do SSO

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 seu app, com um JSON Web Token (JWT) do mesmo formato do JWT enviado quando os usuários se inscrevem pela primeira vez no app.

Para informações detalhadas sobre o payload do JWT e como verificá-lo, consulte Verifique 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 envolvida.
• 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 do pedido) da conta de faturamento que comprou o produto ou

  • project_editor, que indica que o usuário é um editor (direito de projeto), mas não como Administrador de faturamento do projeto nesse do Google Cloud.

  Observação: se você ativou o Logon único (SSO), os usuários com a O papel account_admin também precisa 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

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 vai incluir um objeto orders adicional. 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 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 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 podemos 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, 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 essa pessoa é o usuário que deve 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 deve corresponder ao 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 seus clientes concederem papéis necessários do Identity and Access Management (IAM) para as contas de serviço.

Você precisa fornecer o link para esta página da conta de serviço aos seus 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 criado quando você 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. É 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 para as contas de serviço e por que esses papéis são necessários. Isso é compartilhado com seu cliente e pode afetar se ele concede acessos o 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 concedam acesso às contas de serviço. Em seguida, você cria um link para a página do seu console.

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

É 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 seu produto requer acesso a um único projeto do Google Cloud e que o cliente possa retornar ao seu console.

Lista de parâmetros de URL

Esta é uma lista dos parâmetros de URL que você pode enviar ao serviço página de gerenciamento da conta:

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.