Criar a página de aterrissagem para sua oferta negociável de SaaS no marketplace comercial

  • Artigo

Este artigo orientará você pelo processo de criação de uma página de aterrissagem para um aplicativo SaaS negociável que será vendido no marketplace comercial da Microsoft.

Importante

O Azure Active Directory (Azure AD) Graph foi preterido a partir de 30 de junho de 2023. No futuro, não faremos mais investimentos no Azure AD Graph. As APIs do Graph do Azure AD não têm SLA ou compromisso de manutenção além de correções relacionadas à segurança. Os investimentos nos novos recursos e funcionalidades só serão feitos no Microsoft Graph.

Desativaremos o Azure AD Graph em etapas incrementais para que você tenha tempo suficiente para migrar seus aplicativos para APIs do Microsoft Graph. Em uma data posterior que anunciaremos, bloquearemos a criação de novos aplicativos usando o Azure AD Graph.

Para saber mais, confira Importante: desativação do Azure AD Graph e substituição do módulo do Powershell.

Visão geral

Encare a página de aterrissagem como o "lobby" da sua oferta de SaaS (software como serviço). Após a subscrição de uma oferta pelo comprador, o marketplace comercial o direcionará para a página de aterrissagem a fim de ativar e configurar a assinatura dele em seu aplicativo SaaS. Considere isso como uma etapa de confirmação do pedido que permite que o comprador veja o que comprou e confirme os detalhes da conta. Usando a ID do Microsoft Entra e o Microsoft Graph, você habilitará o SSO (logon único) para o comprador e obterá detalhes importantes sobre o comprador que você pode usar para confirmar e ativar sua assinatura, incluindo seu nome, endereço de email e organização.

Como as informações necessárias para ativar a assinatura são limitadas e fornecidas pela ID do Microsoft Entra e pelo Microsoft Graph, não deve haver necessidade de solicitar informações que exijam mais do que o consentimento básico. Se você precisar de detalhes do usuário que exigem consentimento adicional para seu aplicativo, solicite essas informações após a conclusão da ativação da assinatura. Isso permite uma ativação descomplicada da assinatura para o comprador e diminui o risco de abandono.

A página de aterrissagem normalmente inclui o seguinte:

  • Apresentação do nome da oferta e do plano adquiridos, bem como os termos de cobrança.
  • Apresentação dos detalhes da conta do comprador, incluindo nome e sobrenome, a organização e o email.
  • Solicitação para o comprador confirmar ou substituir diferentes detalhes da conta.
  • Orientação do comprador nas etapas seguintes após a ativação. Por exemplo, receber um email de boas-vindas, gerenciar a assinatura, obter suporte ou ler a documentação.

Observação

O comprador também será direcionado para a página de aterrissagem ao gerenciar sua assinatura após a ativação. Depois que a assinatura do comprador for ativada, você deverá usar o SSO (logon único) para permitir que o usuário entre. É recomendável direcionar o usuário para um perfil de conta ou página de configuração.

As seções seguintes guiarão você pelo processo de criação de uma página de aterrissagem:

  1. Crie um registro de aplicativo do Microsoft Entra para a página de aterrissagem.
  2. Usar um exemplo de código como ponto de partida para seu aplicativo.
  3. Use dois aplicativos do Microsoft Entra para melhorar a segurança na produção.
  4. Resolva o token de identificação de compra do Marketplace adicionado à URL pelo marketplace comercial.
  5. Leia as informações de declarações codificadas no token de ID, que foi recebido da ID do Microsoft Entra após a entrada, que foi enviado com a solicitação.
  6. Usar a API do Microsoft Graph para coletar informações adicionais, conforme necessário.

Criar um registro de aplicativo do Microsoft Entra

O marketplace comercial é totalmente integrado ao Microsoft Entra ID. Os compradores chegam ao marketplace autenticados com uma conta do Microsoft Entra ou MSA (conta Microsoft). Após a compra, o comprador vai do marketplace comercial para a URL da página de aterrissagem para ativar e gerenciar a assinatura do seu aplicativo SaaS. Você deve permitir que o comprador entre em seu aplicativo com o SSO do Microsoft Entra. (A URL da página de aterrissagem é especificada na página de Configuração técnica da oferta.)

Dica

Não inclua o caractere de sinal de sustenido (#) na URL da página de aterrissagem. Caso contrário, os clientes não poderão acessar sua página de aterrissagem.

A primeira etapa para usar a identidade é garantir que sua página de aterrissagem esteja registrada como um aplicativo do Microsoft Entra. O registro do aplicativo permite que você use a ID do Microsoft Entra para autenticar usuários e solicitar acesso aos recursos do usuário. Esse passo pode ser considerado a definição do aplicativo, o que permite que o serviço saiba como emitir tokens para o aplicativo com base nas configurações do aplicativo.

Registrar um novo aplicativo usando o portal do Azure

Para começar, siga as instruções para registrar um novo aplicativo. Para permitir que os usuários de outras empresas visitem o aplicativo, você deve escolher uma das opções de multilocatário quando for perguntado quem pode usar o aplicativo.

Se pretender consultar a API do Microsoft Graph, configure seu novo aplicativo para acessar APIs Web. Quando você seleciona as permissões de API para esse aplicativo, o padrão de User.Read é suficiente para coletar informações básicas sobre o comprador para tornar o processo de integração simples e automático. Não solicite nenhuma permissão de API rotulada como precisa de consentimento do administrador, pois isso impedirá que todos os usuários não administradores acessem sua página de aterrissagem.

Se você precisar de permissões elevadas como parte do processo de integração ou provisionamento, considere usar a funcionalidade de consentimento incremental da ID do Microsoft Entra para que todos os compradores enviados do marketplace possam interagir inicialmente com a página de aterrissagem.

Usar um exemplo de código como ponto de partida

Fornecemos vários aplicativos de exemplo que implementam um site simples com o logon do Microsoft Entra habilitado. Depois que seu aplicativo é registrado na ID do Microsoft Entra, a folha Início Rápido oferece uma lista de tipos de aplicativos comuns e pilhas de desenvolvimento, conforme mostrado na Figura 1. Escolha aquele que corresponder ao seu ambiente e siga as instruções para baixar e configurar.

Figura 1: folha Início Rápido no portal do Azure

Ilustra a folha de início rápido no portal do Azure.

Depois de baixar o código e configurar seu ambiente de desenvolvimento, altere as definições de configuração no aplicativo para refletir a ID do aplicativo, a ID do locatário e o segredo do cliente que você registrou no procedimento anterior. Observe que as etapas exatas serão diferentes dependendo do exemplo que você estiver usando.

Use dois aplicativos do Microsoft Entra para melhorar a segurança na produção

Este artigo apresenta uma versão simplificada da arquitetura para implementar uma página de aterrissagem para sua oferta de SaaS do marketplace comercial. Ao executar a página em produção, recomendamos que você melhore a segurança comunicando-se com as APIs de cumprimento de SaaS somente por meio de um aplicativo protegido e diferente. Isso requer a criação de dois novos aplicativos:

  • Primeiramente, o aplicativo da página de aterrissagem multilocatário foi descrito até este ponto, exceto sem a funcionalidade de entrar em contato com as APIs de cumprimento de SaaS. Essa funcionalidade será descarregada para outro aplicativo, conforme descrito abaixo.
  • Em segundo lugar, um aplicativo que se comunique com as APIs de cumprimento de SaaS. Esse aplicativo deve ser de locatário único, devendo ser usado apenas pela sua organização, e uma lista de controle de acesso pode ser estabelecida para limitar o acesso às APIs somente a partir desse aplicativo.

Isso permite que a solução funcione em cenários que observam o princípio da separação de preocupações. Por exemplo, a página de aterrissagem usa o primeiro aplicativo registrado do Microsoft Entra para conectar o usuário. Depois que o usuário é conectado, a página de aterrissagem usa a segunda ID do Microsoft Entra para solicitar um token de acesso para chamar as APIs de atendimento de SaaS e chamar a operação de resolução.

Resolver o token de identificação de compra do marketplace

Quando o comprador é enviado para a página de aterrissagem, um token é adicionado ao parâmetro da URL. Esse token é diferente do token emitido pela ID do Microsoft Entra e do token de acesso usado para autenticação de serviço a serviço e é usado como uma entrada para a chamada de resolução de APIs de atendimento de SaaS para obter os detalhes da assinatura. Assim como acontece com todas as chamadas para as APIs de atendimento de SaaS, sua solicitação de serviço a serviço será autenticada com um token de acesso baseado no usuário da ID do Aplicativo Microsoft Entra do aplicativo para autenticação de serviço a serviço.

Observação

Na maioria dos casos, é preferível fazer essa chamada de um segundo aplicativo de locatário único. Consulte Usar dois aplicativos do Microsoft Entra para melhorar a segurança na produção anteriormente neste artigo.

Solicitar um token de acesso

Para autenticar seu aplicativo com as APIs de atendimento de SaaS, você precisa de um token de acesso, que pode ser gerado chamando o ponto de extremidade OAuth da ID do Microsoft Entra. Consulte Como obter o token de autorização do editor.

Chamar o ponto de extremidade de resolução

As APIs de cumprimento de SaaS implementam o ponto de extremidade de resolução que pode ser chamado para confirmar a validade do token do marketplace e retornar informações sobre a assinatura.

Ler informações de declarações codificadas no token de ID

Durante o fluxo de OpenID Connect, coloque o valor da ID do locatário recebida em https://login.microsoftonline.com/{tenant}/v2.0. A ID do Microsoft Entra adiciona um token de ID à solicitação quando o comprador é enviado para a página de aterrissagem. Esse token contém várias partes de informações básicas que podem ser úteis no processo de ativação, incluindo as informações vistas nesta tabela.

Valor Descrição
aud Público-alvo para este token. Neste caso, deve corresponder à ID do aplicativo e ser validado.
preferred_username Nome de usuário primário do usuário visitante. Pode ser um endereço de email, número de telefone ou outro identificador.
Email Endereço de email do usuário. Observe que esse campo pode estar vazio.
name Valor legível por humanos que identifica a entidade do token. Neste caso, será o nome do comprador.
oid Identificador no sistema de identidade da Microsoft que identifica o usuário de forma exclusiva em todos os aplicativos. O Microsoft Graph retornará esse valor como a propriedade de ID para uma determinada conta de usuário.
tid Identificador que representa o locatário do Microsoft Entra do qual o comprador é. No caso de uma identidade MSA, sempre será 9188040d-6c67-4c5b-b112-36a304b66dad. Confira mais informações na observação da próxima seção: usar a API do Microsoft Graph.
sub Identificador que identifica exclusivamente o usuário neste aplicativo específico.

Usar a API do Microsoft Graph

O token de ID contém informações básicas para identificar o comprador, mas seu processo de ativação pode exigir detalhes adicionais, como a empresa do comprador, para concluir o processo de integração. Use a API do Microsoft Graph para solicitar essas informações e evitar forçar o usuário a inserir esses detalhes novamente. As permissões User.Read padrão incluem as seguintes informações, por padrão.

Valor Description
displayName O nome exibido no catálogo de endereços para o usuário.
givenName Nome do usuário.
jobTitle O cargo do usuário.
mail O endereço SMTP do usuário.
mobilePhone O número do celular principal do usuário.
preferredLanguage O código ISO 639-1 para o idioma preferencial do usuário.
sobrenome O sobrenome do usuário.

Propriedades adicionais, como o nome da empresa do usuário ou o local do usuário (país/região), podem ser selecionadas para inclusão na solicitação. Consulte Propriedades para o tipo de recurso de usuário para obter mais detalhes.

A maioria dos aplicativos registrados com a ID do Microsoft Entra concede permissões delegadas para ler as informações do usuário do locatário do Microsoft Entra da empresa. Toda solicitação que o Microsoft Graph fizer para essas informações deverá ser acompanhada de um token de acesso para autenticação. As etapas específicas para geração do token de acesso dependerão da pilha de tecnologia que você usar, mas o código de exemplo conterá um modelo. Confira mais informações em Obter acesso em nome de um usuário.

Observação

As contas do locatário MSA (com a ID de locatário 9188040d-6c67-4c5b-b112-36a304b66dad) não retornarão mais informações do que as que já foram coletadas com o token de ID. Portanto, você pode ignorar essa chamada para a API do Microsoft Graph para essas contas.

Conteúdo relacionado

Tutoriais em vídeo