Criar a página de aterrissagem para sua oferta de SaaS gratuita ou de avaliação no marketplace comercial
Este artigo orientará você pelo processo de criação de uma página de aterrissagem para um aplicativo SaaS gratuito ou de avaliação 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 o cliente optar por baixar seu aplicativo, o marketplace comercial o direcionará para a página de aterrissagem a fim de ativar e configurar a assinatura dele em seu aplicativo SaaS. Ao criar uma oferta de SaaS (software como serviço), no Partner Center, você pode escolher se deseja ou não vender pela Microsoft. Se quiser apenas listar sua oferta no marketplace comercial da Microsoft sem vender pela Microsoft, poderá especificar como os clientes potenciais poderão interagir com a oferta. Ao habilitar a opção de anúncio Obter agora (gratuito) ou Avaliação gratuita, será preciso especificar uma URL da página de aterrissagem em que o usuário poderá acessar a assinatura ou avaliação gratuitas.
A finalidade da página de aterrissagem é simplesmente receber o usuário para que ele possa ativar a avaliação ou assinatura gratuitas. Usando a ID do Microsoft Entra e o Microsoft Graph, você habilitará o SSO (logon único) para o usuário e obterá detalhes importantes sobre o usuário que você pode usar para ativar sua avaliação gratuita ou assinatura gratuita, 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 de usuário que exijam mais consentimento 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 usuário e diminui o risco de abandono.
A página de aterrissagem normalmente inclui as seguintes informações e opções de anúncio:
- Apresentação do nome e dos detalhes da avaliação ou assinatura gratuita. Por exemplo, especifique os limites de uso ou a duração de uma avaliação.
- Apresentação dos detalhes da conta do usuário, incluindo nome e sobrenome, a organização e o email.
- Solicitação para o usuário confirmar ou substituir diferentes detalhes da conta.
- Orientação do usuário 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.
As seções a seguir neste artigo orientam você pelo processo de criação de uma página de destino:
- Crie um registro de aplicativo do Microsoft Entra para a página de aterrissagem.
- Usar um exemplo de código como ponto de partida para seu aplicativo.
- Leia as informações de declarações codificadas no token de ID, recebidas da ID do Microsoft Entra após a entrada, que foi enviada 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 marketplace comercial é totalmente integrado ao Microsoft Entra ID. Os usuários chegam ao marketplace autenticados com uma conta do Microsoft Entra ou MSA (conta Microsoft). Após adquirir uma assinatura ou avaliação gratuitas por meio de sua oferta exclusiva do anúncio, o usuário passa do marketplace comercial para a URL da página de aterrissagem para ativar e gerenciar a assinatura de seu aplicativo SaaS. Você deve permitir que o usuário 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 usuários de outras empresas visitem o aplicativo, você deve escolher Contas em qualquer diretório organizacional (qualquer diretório do Microsoft Entra – multilocatário) e contas pessoais da Microsoft (como Skype ou Xbox) quando 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 usuário 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 visitem sua página de destino.
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 usuários enviados do marketplace possam interagir inicialmente com a página de aterrissagem.
Usar um exemplo de código como ponto de partida
A Microsoft forneceu vários aplicativos de exemplo que implementam um site simples com o login 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 (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. As etapas exatas diferem dependendo de qual amostra você está usando.
Ler informações de declarações codificadas no token de ID
Como parte do fluxo do OpenID Connect, a ID do Microsoft Entra adiciona um token de ID à solicitação quando o usuário é 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. |
| Endereço de email do usuário. Este campo pode estar vazio. | |
| name | Valor legível por humanos que identifica a entidade do token. Nesse caso, é o nome do usuário. |
| 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 usuário é. 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 usuário, mas seu processo de ativação pode exigir mais detalhes, como a empresa do usuário, 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. |
Mais propriedades, 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. Para obter mais informações, consulte Propriedades do tipo de recurso de usuário.
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 como 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.