Integrar o front-end do seu app

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

Em um alto nível, você precisa fornecer um URL de inscrição para gerenciar a criação de contas de usuários, que depois são gerenciadas no console da Web. Você também precisa fornecer um URL para que os usuários façam login. Como opção, você pode 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 de 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

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.

Adicione seu URL de inscrição

Quando os usuários compram seu produto do Cloud Marketplace, você precisa criar uma conta com o produto para eles. Para isso, crie uma página de inscrição para configurar e aprovar contas de usuários no sistema. É possível configurar essa página 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.

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 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 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 dele. É 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.

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 estiver trabalhando com JWTs, consulte a introdução do 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, siga estas etapas:

  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 seu 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 Enable SSO login?, selecione Yes.

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

Quando os clientes fazem login no app usando o 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 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 inscrição ou login de um cliente com o SSO, envolvem o envio de uma solicitação HTTP POST com um JSON Web Token (JWT) que talvez seja 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.
  • Indica se você precisa verificar o JWT ou não.
Evento Tipo de solicitação HTTP Verificação de JWT obrigató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 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/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
  }
}

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 (gerente de direitos), mas não um administrador de faturamento, do projeto nessa conta de faturamento.

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

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 a declaração exp para verificar se o JWT não expirou.

  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/cloud-commerce-partner@system.gserviceaccount.com

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

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ê esperava para 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.

Criar contas de serviço para seus clientes

Se o seu produto precisar de 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 necessários do Identity and Access Management (IAM) às contas de serviço.

Você precisa fornecer o link dessa 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: esse é um ID do produto exclusivo que diferencia seu produto de outros. Recomendamos usar o nome do 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 a concessão de acesso à conta de serviço por ele.

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 às contas de serviço. Em seguida, você cria um link para a página a partir de 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 à 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 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 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

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

ParâmetroDescrição
service-nameObrigatório. Esse é o nome do serviço que você forneceu ao engenheiro de parceiros.
service-account-emailObrigatório. Este é o endereço de e-mail da conta de serviço que você criou para o cliente.
singleQuando verdadeiro, isso indica que seu produto precisa de acesso a um único projeto.
hints=project-id-1Define o projeto que você quer que a conta de serviço acesse. Use vírgulas para separar projetos.
filter=role1Limita 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.
redirectFornece 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.
Próxima
Como testar seu produto SaaS