Integre o frontend da sua app

Esta página descreve como integrar o frontend da sua app com o Cloud Marketplace para oferecer aos seus clientes uma experiência simples quando passam do Cloud Marketplace para o seu produto.

A um nível elevado, tem de fornecer um URL de inscrição para processar a criação de contas de utilizadores, que são geridas na sua consola Web. Também tem de fornecer um URL para os utilizadores iniciarem sessão. Opcionalmente, pode integrar o Início de sessão único (SSO).

Use o Producer Portal para integrar o front-end da sua app

Para aceder a todas as informações de que precisa para integrar o frontend da sua app com o Cloud Marketplace a partir de uma localização, pode usar a secção Integração do frontend do Producer Portal.

O link direto para o Producer Portal é:

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

Nota: se não vir o link ou não conseguir aceder ao URL, verifique se selecionou o projeto correto. Se ainda não conseguir aceder ao URL, use o serviço de apoio técnico para parceiros para pedir assistência e inclua a palavra "Marketplace" na descrição. Para mais informações acerca da mesa de apoio técnico para parceiros, visite o artigo Peça assistência com o Google Cloud Marketplace.

Para aceder à secção Integração de front-end:

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

2. Na página Vista geral do seu produto, aceda à secção Integração técnica e clique em Integração de front-end.

Adicione o URL de inscrição

Quando os utilizadores compram o seu produto no Cloud Marketplace, tem de criar uma conta com o seu produto para eles. Para o fazer, tem de criar uma página de inscrição para configurar e aprovar as contas dos utilizadores no seu sistema. Pode configurar a página como uma página de registo onde os utilizadores se inscrevem numa conta no seu sistema ou como uma página que aprova contas automaticamente.

Aviso: quando configurar a página de inscrição, certifique-se de que os utilizadores podem aceder à página sem introduzir primeiro um nome de utilizador e uma palavra-passe.

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

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

2. Na página Vista geral do seu produto, aceda à secção Integração técnica e clique em Integração de front-end.

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

Valide as informações de inscrição do utilizador

Se um utilizador ainda não tiver estabelecido uma conta no seu sistema, tem de clicar no botão Registar com YOUR_COMPANY_NAME no Cloud Marketplace. Quando clicam no botão, Google Cloud enviam um pedido HTTP POST para a sua página de inscrição, com um símbolo da Web JSON (JWT) no parâmetro x-gcp-marketplace-token. O JWT contém o ID da conta de aprovisionamento do utilizador, que o identifica como um utilizador, e um ID oculto, que representa o ID da respetiva Conta Google. Google Cloud Tem de usar o ID da conta de aprovisionamento e o ID ocultado para associar a Conta Google do utilizador à respetiva conta no seu sistema.

Nota: é possível que um único utilizador tenha vários IDs de contas de aprovisionamento ou que vários utilizadores partilhem um ID de conta de aprovisionamento comum, consoante a forma como eles ou a respetiva organização configuraram a utilização do Google Cloud.

Após validar o JWT, a sua página de inscrição tem de enviar um pedido de aprovação da conta para a Partner Procurement API, descrito nos passos de integração de back-end.

Para obter informações detalhadas sobre a carga útil do JWT e como validá-la, consulte a secção Valide o JWT abaixo.

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

Adicione o URL de início de sessão

Tem de especificar o URL da página de início de sessão da sua app.

Para introduzir o URL da página de início de sessão da sua app no Producer Portal:

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

2. Na página Vista geral do seu produto, aceda à secção Integração técnica e clique em Integração de front-end.

3. Introduza o URL da página de início de sessão da sua app no campo URL de início de sessão.

(Opcional) Ative o Início de sessão único (SSO) para os seus clientes

Para ativar o SSO no Producer Portal:

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

   1. Na página Vista geral do seu produto, aceda à secção Integração técnica e clique em Integração de front-end.

   2. Em Ativar início de sessão único?, selecione Sim.

Valide as informações de início de sessão de SSO dos seus clientes

Quando os clientes iniciam sessão na sua app através do SSO, Google Cloud envia um pedido HTTP POST para a página de início de sessão da sua app com um símbolo da Web JSON (JWT) no mesmo formato que o JWT enviado quando os utilizadores se inscrevem pela primeira vez na sua app.

Para obter informações detalhadas sobre a carga útil do JWT e como validá-la, consulte a secção Valide o JWT abaixo.

Valide o JWT

Alguns processos, como inscrever um novo cliente ou iniciar sessão de um cliente com SSO, envolvem o envio de um pedido HTTP POST com um símbolo da Web JSON (JWT) que pode ter de validar.

A tabela seguinte lista:

• Eventos que envolvem o envio de um pedido HTTP com um JWT.
• O tipo de pedido HTTP envolvido.
• Se tem ou não de validar o JWT.

Evento	Tipo de pedido HTTP	Validação de JWT necessária
Inscreva um novo cliente	POST	Sim
Início de sessão do cliente, sem SSO	GET	Não
Início de sessão de clientes com SSO	POST	Sim

O payload JWT

O payload do JWT está no seguinte formato:

Cabeçalho

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

Onde:

• 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 no 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 Google do utilizador. Tem de usar este ID para associar a conta Google do utilizador à respetiva conta no seu sistema.
• iss identifica o remetente do JWT. O URL na reivindicação iss aponta para uma chave pública da Google.
• exp indica quando o token expira e está definido para 5 minutos após o envio do token.
• aud é o domínio que aloja o seu produto, como example.com.

• roles é uma matriz de strings que representa as funções do utilizador. Pode ser uma das seguintes opções:

  • account_admin, o que indica que o utilizador é um administrador da conta de faturação (administrador de encomendas) da conta de faturação que comprou o produto, ou

  • project_editor, o que indica que o utilizador é um editor (gestor de autorizações), mas não um administrador de faturação, do projeto nessa conta de faturação.

  Nota: se ativou o Início de sessão único (SSO), os utilizadores com a função account_admin também têm de ter a função project_editor.

• user_identity é o ID GAIA ocultado do utilizador, que pode ser usado para iniciar o OpenID Connect.

Payload para várias encomendas do mesmo produto

Se tiver ativado várias encomendas do mesmo produto, a carga útil inclui um objeto orders adicional. Isto inclui o ID da encomenda exclusivo correspondente ao ID da autorização para cada encomenda. Certifique-se de que a página de início de sessão da sua app consegue responder a este 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]
  }
}

Onde:

• ORDER_ID é uma lista de IDs de encomendas exclusivos para cada ID de autorização que indica as diferentes ofertas do mesmo produto. Este campo só está disponível se estiverem ativadas várias encomendas do mesmo produto.

Para mais informações sobre como ativar várias encomendas do mesmo produto, consulte o artigo Ative várias encomendas do mesmo produto.

Valide a carga útil

Quando receber o JWT, tem de validar o seguinte:

1. Verifique se a assinatura JWT está a usar a chave pública da Google.

2. Verifique se o JWT não expirou, consultando a reivindicação exp.

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

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

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

Nota: uma vez que podemos adicionar novos campos ao JWT, não deve considerar um JWT inválido apenas porque contém novos campos que ainda não encontrou.

Inicie sessão com o Google com login_hint

Se quiser que os seus utilizadores passem por um fluxo de consentimento do OAuth 2.0 com o seu site, pode usar as informações de identidade da carga útil para inicializar esse fluxo na Conta Google que estavam a usar para o Google Cloud antes do redirecionamento. Para tal, faculte o user_identity fornecido no JWT como o login_hint. Para mais informações, consulte a documentação do Google OAuth 2.0.

Depois de o utilizador concluir o fluxo OAuth 2.0 com o seu site, deve validar se é o utilizador que esperava que concluísse o fluxo OAuth. Para tal, use a chave de acesso do OAuth 2.0 para chamar a API Google UserInfo para obter as informações básicas do utilizador. Isto devolve um ID que se espera que corresponda ao campo user_identity do JWT.

Crie contas de serviço para os seus clientes

Pré-visualização

Este produto ou funcionalidade está sujeito aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. Os produtos e as funcionalidades pré-GA estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

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

• Aprovisione contas de serviço para os seus clientes e
• Configure uma página de gestão de contas de serviço para que os seus clientes concedam as funções de gestão de identidade e de acesso (IAM) necessárias às contas de serviço.

Tem de fornecer o link para esta página da conta de serviço aos seus clientes, normalmente através da consola de gestão do seu produto.

Aprovisione as contas de serviço

Para aprovisionar as contas de serviço, contacte o seu engenheiro de parceiros e inclua as seguintes informações:

• Nome do serviço: este é um ID do produto exclusivo que diferencia o seu produto de outros produtos. Recomendamos que use o nome do serviço que criou quando integrou o seu produto.

• ID do projeto: o ID do projeto no qual cria as contas de serviço que acedem aos recursos dos seus clientes. Tem de criar todas as contas de serviço que o seu produto usa num único projeto.

• Funções e raciocínio do IAM: as funções do IAM necessárias para as contas de serviço e o motivo pelo qual as funções são necessárias. Estas informações são partilhadas com o cliente e podem afetar a decisão do cliente de conceder acesso à conta de serviço.

Se quiser que o cliente regresse ao seu site depois de conceder acesso à conta de serviço, envie o nome do domínio da sua consola ao engenheiro de parceiros. Pode enviar vários nomes de domínios, incluindo subdomínios, como staging.example.com.

Integre a página de gestão de contas de serviço na consola do seu produto

O engenheiro de parceiros cria uma página de gestão de contas de serviço para permitir que os seus clientes concedam acesso às contas de serviço. Em seguida, associa a página à consola.

Depois de o engenheiro de parceiros lhe enviar uma notificação a indicar que a página de gestão de contas de serviço está pronta, adicione parâmetros ao URL e, em seguida, crie um link para a página a partir da sua consola.

Tem de adicionar dois parâmetros ao URL:

• service-name: este é o nome do serviço que indicou ao seu engenheiro parceiro.

• service-account-email: este é o endereço de email da conta de serviço que criou para o seu cliente. Cada cliente tem uma conta de serviço única.

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

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

Pode adicionar parâmetros adicionais consoante as necessidades dos seus clientes. Por 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 seu produto requer acesso a um único Google Cloud projeto e que o cliente pode regressar à sua consola.

Lista de parâmetros de URL

Segue-se uma lista dos parâmetros de URL que pode enviar para a página de gestão da conta de serviço:

Parâmetro	Descrição
service-name	Este campo é obrigatório. Este é o nome do serviço que forneceu ao seu engenheiro parceiro.
service-account-email	Este campo é obrigatório. Este é o endereço de email da conta de serviço que criou para o seu cliente.
single	Quando é verdadeiro, indica que o seu produto requer acesso a um único projeto.
hints=project-id-1	Define o projeto ao qual quer que a conta de serviço aceda. Use vírgulas para separar projetos.
filter=role1	Limita as funções concedidas à conta de serviço a um subconjunto das funções que forneceu ao seu engenheiro parceiro. Exclua o roles/ quando usar o filtro.
redirect	Fornece um link para o cliente regressar à sua consola de gestão. O nome de domínio tem de ser registado junto do seu engenheiro parceiro para usar este parâmetro.