Como integrar o front-end do aplicativo

Nesta página, descrevemos as etapas para integrar o front-end do seu aplicativo com o Google Cloud Marketplace. A integração de front-end ajuda a oferecer a clientes uma experiência estável quando eles passam do Google Cloud Marketplace para o aplicativo.

Como criar uma página de ativação da conta para novos usuários

Quando os usuários escolhem seu produto no Google Cloud Marketplace, eles precisam ativar as contas deles no seu aplicativo. Você precisa criar uma página de ativação para configurar e aprovar as contas dos usuários em 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 em seu sistema ou como uma página que aprova contas automaticamente. Ao configurar sua página de ativação, verifique se os usuários podem acessá-la sem inserir um nome de usuário e uma senha.

No Google Cloud Marketplace, quando os usuários clicam no link para se inscrever no seu aplicativo, o Google envia uma solicitação HTTP POST para sua página de ativação e envia um parâmetro JSON Web Token (JWT) no 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. Use esse ID para vincular a Conta do Google do usuário à conta dele no seu sistema.

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

Se você é novo no JWT, consulte a introdução do JWT.

Como adicionar a página de ativação da conta ao portal

Use o Portal do Produtor para adicionar o URL da página de ativação da conta.

Portal do Produtor

O link direto para o Portal do Produtor é:

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

Para adicionar a página de ativação da conta 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 ativação da conta no campo URL de inscrição.

Portal do parceiro

O link direto para o Portal do parceiro é:

https://console.cloud.google.com/partner/solutions?project=YOUR_PROJECT_ID

Para adicionar a página de ativação da conta ao Portal do parceiro:

  1. Na lista de soluções, clique no código da solução que você criou.

  2. Na página Planos e recursos, clique para editar a página.

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

Verificar o 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/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-pro.com.
  • roles é uma matriz de strings que representam os papéis do usuário. No momento, pode ser: ** account_admin, que indica que o usuário é um administrador da conta de faturamento que comprou o produto ou ** project_editor, que indica que o usuário é um editor do projeto, 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 Open ID Connect.

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

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

Iniciando 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 OAuth2.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.

Integrar o Logon único (SSO) para seus clientes

Quando os clientes se inscrevem no seu produto, eles precisam ser registrados para uma conta na sua página de ativação sem antes digitar um nome de usuário e senha.

A integração SSO usa os JWTs para autenticar usuários. Se você é novo no JWT, consulte a introdução do JWT.

Portal do Produtor

Para configurar a integração com o SSO:

  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. Para vincular isso ao seu painel, insira o URL dele no campo URL de login.

  3. Para usar o SSO do Google, clique em Ativar o login por SSO (opcional) e insira o URL de login do SSO no campo URL do SSO.

  4. Na interface da Web do seu app, adicione o código para verificar o payload do JWT que é enviado ao seu aplicativo quando os usuários fazem login no Google Cloud Marketplace.

    O formato do JWT para autenticação é o mesmo que o JWT enviado quando os usuários se inscrevem pela primeira vez no seu aplicativo, descrito em Como verificar o JWT.

Portal do parceiro

Para configurar a integração com o SSO:

  1. Acesse a página Planos e recursos do produto e escolha EDITAR os planos e os recursos do produto.

  2. Para vincular isso ao seu painel, insira o URL do seu painel no campo URL do painel.

  3. Para usar o SLO do Google, em Login por SSO (optional), clique em Ativar SSO e digite o URL de login por SSO no campo URL de login por SSO. Digite o URL das chaves de API SSO no campo URL da chave de API de SSO.

  4. Na interface da Web do seu app, adicione o código para verificar o payload do JWT que é enviado ao seu aplicativo quando os usuários fazem login no Google Cloud Marketplace.

    O formato do JWT para autenticação é o mesmo que o JWT enviado quando os usuários se inscrevem pela primeira vez no seu aplicativo, descrito em Como verificar o JWT.

Como provisionar contas de serviço para seus clientes

Se o aplicativo exigir uma conta de serviço, trabalhe com um engenheiro de parceiros para provisionar contas de serviço para os clientes e configurar uma página para eles concederem os papéis necessários de gerenciamento de identidade e acesso (IAM, na sigla em inglês) as contas de serviço. É necessário fornecer o link para a página, geralmente por meio do console de gerenciamento do aplicativo.

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 app dos outros. Recomendamos usar o nome do serviço criado quando você integrou o app.

  • ID do projeto: o ID do projeto em que você cria as contas de serviço que acessam os recursos dos clientes. Todas as contas de serviço usadas pelo app precisam ser criadas 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.

O engenheiro de parceiros cria uma página para permitir que seus clientes concedam acesso às contas de serviço. Em seguida, vincule a página ao seu console.

Como integrar o URL no seu console

Quando o engenheiro de parceiros tiver notificado que a página 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 do seu cliente. 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 no 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

Esta é uma lista dos parâmetros de URL que você pode enviar para a página de acesso:

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.