Criar a página de aterrissagem para sua oferta negociável de SaaS no marketplace comercial
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 Gráfico do Azure Active Directory (Azure AD) foi preterido a partir de 30 de junho de 2023. No futuro, não faremos mais investimentos no Azure AD Graph. As APIs do Azure AD Graph não têm SLA ou compromisso de manutenção além das 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 as 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, consulte Importante: Aposentadoria do Graph do Azure AD 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 o Microsoft Entra ID e o Microsoft Graph, você habilitará o logon único (SSO) 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 pelo Microsoft Entra ID 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:
- Crie um registro de aplicativo Microsoft Entra para a página de destino.
- Usar um exemplo de código como ponto de partida para seu aplicativo.
- Use dois aplicativos do Microsoft Entra para melhorar a segurança na produção.
- Resolva o token de identificação de compra do Marketplace adicionado à URL pelo marketplace comercial.
- Leia informações de declarações codificadas no token de ID, que foi recebido do Microsoft Entra ID após entrar, que foi enviado com a solicitação.
- Usar a API do Microsoft Graph para coletar informações adicionais, conforme necessário.
Criar um registro de aplicativo do Microsoft Entra
O mercado comercial é totalmente integrado com o Microsoft Entra ID. Os compradores chegam ao mercado autenticados com uma conta do Microsoft Entra ou uma conta da Microsoft (MSA). 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 Microsoft Entra SSO. (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.
O primeiro passo para usar a identidade é garantir que sua página de destino esteja registrada como um aplicativo 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 de seu processo de integração ou provisionamento, considere usar a funcionalidade de consentimento incremental do Microsoft Entra ID para que todos os compradores enviados do marketplace possam interagir inicialmente com a página de destino.
Usar um exemplo de código como ponto de partida
Fornecemos vários aplicativos de exemplo que implementam um site simples com o login do Microsoft Entra habilitado. Depois que seu aplicativo é registrado no Microsoft Entra ID, a folha Guia de 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
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.
Usar 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 destino usa o primeiro aplicativo Microsoft Entra registrado para entrar no usuário. Depois que o usuário é conectado, a página de destino usa a segunda ID do Microsoft Entra para solicitar um token de acesso para chamar as APIs de preenchimento 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 pelo Microsoft Entra ID 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 SaaS para obter os detalhes da assinatura. Como acontece com todas as chamadas para as APIs de atendimento de SaaS, sua solicitação de serviço para serviço será autenticada com um token de acesso baseado no usuário do Microsoft Entra Application ID 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 preenchimento de SaaS, você precisa de um token de acesso, que pode ser gerado chamando o ponto de extremidade OAuth do Microsoft Entra ID. 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. O Microsoft Entra ID adiciona um token de ID à solicitação quando o comprador é enviado para a página de destino. 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. |
| 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. |
| 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 a localização 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 o Microsoft Entra ID 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.
Próximas etapas
Tutoriais em vídeo
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de