Integrar usuários externos aos aplicativos de linha de negócios usando o Microsoft Entra B2B
Os desenvolvedores de aplicativos podem usar o Microsoft Entra B2B para integrar e colaborar com usuários externos em aplicativos de LOB (linha de negócios). Semelhante ao botão Compartilhar em muitos aplicativos do Office 365, os desenvolvedores de aplicativos podem criar uma experiência de convite com um clique em qualquer aplicativo de LOB integrado ao Microsoft Entra ID.
Os benefícios incluem:
- Integração de usuários e acesso aos aplicativos de LOB. Acesso aos usuários em poucas etapas.
- Que usuários externos tragam sua própria identidade e executem o SSO (logon único).
- Provisionamento automático de identidades externas para o Microsoft Entra ID.
- Acesso Condicional do Microsoft Entra e políticas de acesso entre locatários para aplicar políticas de autorização, como a autenticação multifator.
Fluxo de integração
Para integrar aplicativos LOB com o Microsoft Entra B2B, siga este padrão:
- O usuário final aciona o convite no aplicativo LOB e fornece o endereço de email do usuário externo. O aplicativo verifica se o usuário já existe e, se não existir, Cria e envia o convite|
- O aplicativo envia um POST para a API do Microsoft Graph em nome do usuário. Ele fornece a URL de redirecionamento e o email do usuário externo definido em Confirmar se o usuário externo está no diretório.
- A API do Microsoft Graph provisiona o usuário convidado no Microsoft Entra ID.
- A API do Microsoft Graph retorna o status de êxito ou falha da chamada à API. Se o status for de êxito, a resposta incluirá a ID do objeto do usuário do Microsoft Entra e o link do convite que é enviado para o email do usuário convidado. Você pode suprimir o email da Microsoft e enviar um email personalizado.
- (Opcional) Para gravar mais atributos para o usuário convidado ou adicionar o usuário convidado a um grupo. O aplicativo faz uma chamada à API extra à API do Microsoft Graph.
- (Opcional) A API do Microsoft Graph faz as atualizações no Microsoft Entra ID.
- (Opcional) A API do Microsoft Graph retorna o status de êxito ou falha para o aplicativo.
- O aplicativo provisiona o usuário em seu próprio banco de dados ou diretório de usuário de back-end usando o atributo de ID de objeto do usuário como ID imutável.
- O aplicativo apresenta o status de êxito ou falha ao usuário final.
Se a atribuição for necessária para acessar o aplicativo de LOB, o usuário convidado também será atribuído ao aplicativo com uma função de aplicativo. Para ativar essa ação como outra chamada à API, basta adicionar o convidado a um grupo ou automatizar a associação com os grupos de associação dinâmica do Microsoft Entra. Os grupos de associação dinâmica não exigem outra chamada à API pelo aplicativo; no entanto, eles são atualizados tão rápido quanto adicionar um usuário a um grupo por meio de convite do usuário.
Confirmar se o usuário externo está no diretório
É possível que o usuário externo tenha sido convidado e integrado. O aplicativo de LOB verifica se o usuário está no diretório. Faça uma chamada à API do Microsoft Graph e apresente as correspondências ao usuário convidado para que ele escolha.
Por exemplo:
Application Permission: User.read.all
GET https://graph.microsoft.com/v1.0/users?$filter=othermails/any(id:id eq 'userEmail@contoso.com')
Se você receber os detalhes de um usuário na resposta, então o usuário está no diretório. Apresente os usuários retornados ao usuário convidado. Permita que os usuários selecionem o usuário externo que obtém acesso. Para conceder acesso de usuário ao aplicativo, faça chamadas de API ou acione outros processos.
Criar e enviar o convite
Se o usuário externo não estiver no diretório, você poderá usar o Microsoft Entra B2B para convidá-lo e integrá-lo ao seu locatário do Microsoft Entra. Determine o que incluir na solicitação de convite à API do Microsoft Graph.
Use os elementos a seguir:
- Solicite que o usuário final forneça o endereço de email do usuário externo.
- Depois que os usuários autenticarem e resgatarem o convite do B2B, determine a URL de convite que os redirecionará
- A URL pode ser uma página inicial genérica do aplicativo ou determinada de forma dinâmica pelo aplicativo de LOB com base em onde o usuário final acionou o convite
Mais sinalizadores e atributos para a solicitação de convite:
- Nome de exibição do usuário convidado
- Email de convite padrão da Microsoft ou suprima o email padrão para criar o seu próprio
Depois que o aplicativo coletar as informações necessárias, o aplicativo deverá POSTAR a solicitação para o gerenciador de convites da API do Microsoft Graph. Verifique se o registro do aplicativo tem as permissões no Microsoft Entra ID.
Por exemplo:
Delegated Permission: User.Invite.All
POST https://graph.microsoft.com/v1.0/invitations
Content-type: application/json
{
"invitedUserDisplayName": "John Doe",
"invitedUserEmailAddress": "john.doe@contoso.com",
"sendInvitationMessage": true,
"inviteRedirectUrl": "https://customapp.contoso.com"
}
Observação
Para ver as opções do corpo JSON do convite, confira o tipo de recurso de convite no Microsoft Graph v1.0.
Os desenvolvedores de aplicativos podem integrar usuários externos usando a inscrição de autoatendimento do Microsoft Entra ou os pacotes de acesso de gerenciamento de direitos. Você pode criar um botão de Convite em seu aplicativo de LOB que aciona um email personalizado contendo um URL de inscrição de autoatendimento ou um URL de pacote de acesso. O usuário convidado faz a integração e acessa o aplicativo.
(Opcional) Gravar outros atributos no Microsoft Entra ID
Importante
Conceder permissão a um aplicativo para atualizar usuários em seu diretório é uma ação altamente privilegiada. Se conceder ao aplicativo essas permissões altamente privilegiadas, proteja e monitore o aplicativo de LOB
Sua organização ou o aplicativo de LOB pode precisar de armazenamento de informações para uso futuro, como a emissão de declarações em tokens ou políticas de autorização granular. Seu aplicativo pode fazer outra chamada à API para atualizar o usuário externo depois que ele tiver sido convidado ou criado no Microsoft Entra ID. O aplicativo precisa ter permissões extras de API e uma chamada extra à API do Microsoft Graph.
Para atualizar o usuário, use a ID do objeto do usuário convidado criado da chamada à API de convite, o valor de ID na resposta da API da verificação de existência ou convite. Você pode gravar em qualquer atributo padrão ou atributos de extensão personalizados.
Por exemplo:
Application Permission: User.ReadWrite.All
PATCH https://graph.microsoft.com/v1.0/users/<user's object ID>
Content-type: application/json
{
"businessPhones": [
"+1 234 567 8900"
],
"givenName": "John"
"surname": "Doe",
"extension_cf4ff515cbf947218d468c96f9dc9021_appRole": "external"
}
Para mais informações, confira Atualizar usuário no Microsoft Graph v1.0.
(Opcional) atribuir o usuário convidado a um grupo
Observação
Se a atribuição de usuário não for necessária para acessar o aplicativo, pule essa etapa.
Se a atribuição de usuário for necessária no Microsoft Entra ID para acesso ao aplicativo ou atribuição de função, o usuário será atribuído ao aplicativo. Caso contrário, o usuário não poderá obter acesso independentemente da autenticação. Para adicionar o usuário externo convidado a um grupo específico, faça outra chamada à API. O grupo é atribuído ao aplicativo e mapeado para uma função do aplicativo.
Um exemplo de permissões: atribua a função Atualizador de Grupo ou uma função personalizada ao aplicativo empresarial. Defina o escopo da atribuição de função para os grupos que este aplicativo atualiza. Ou atribua a permissão group.readwrite.all na API do Microsoft Graph.
POST https://graph.microsoft.com/v1.0/groups/<insert group id>/members/$ref
Content-type: application/json
{
"@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/<insert user id>"
}
Para mais informações, confira Adicionar membros no Microsoft Graph v1.0.
Como alternativa, você pode usar grupos de associação dinâmica do Microsoft Entra que atribuem usuários automaticamente com base em atributos específicos, como userType, email ou um atributo personalizado. No entanto, se o acesso do usuário for urgente, essa abordagem não é recomendada, pois os grupos de associação dinâmica podem levar até 24 horas para serem preenchidos.
Se você usar grupos de associação dinâmica, não adicione os usuários a um grupo com outra chamada à API. Crie um grupo que adiciona o usuário como membro do grupo com base em atributos como userType, email ou um atributo personalizado. Para obter mais informações, consulte Criar ou editar um grupo dinâmico e obter o status.
Provisionar o usuário convidado para o aplicativo
Depois que o usuário externo convidado for provisionado no Microsoft Entra ID, a API do Microsoft Graph retornará uma resposta com as informações do usuário, como ID de objeto e email. O aplicativo de LOB provisionará o usuário em seu próprio diretório ou banco de dados. O provisionamento varia dependendo do aplicativo e do tipo de diretório interno que o aplicativo usa.
Com o usuário externo provisionado no Microsoft Entra ID e no aplicativo, o aplicativo de LOB notifica o usuário inicial de que o processo foi bem-sucedido. O usuário convidado obtém SSO com sua identidade sem que a organização que está convidando faça a integração e emita credenciais extras. O Microsoft Entra ID impõe políticas de autorização, com Acesso Condicional, autenticação multifator do Microsoft Entra e Microsoft Entra ID Protection.
Outras considerações
Verifique se o tratamento de erro foi feito no aplicativo de LOB. O aplicativo valida cada chamada à API. Se não for bem-sucedido, outras tentativas ou mensagens de erro serão úteis.
Para que o aplicativo LOB atualize os usuários externos convidados, conceda uma função personalizada que permita que o aplicativo atualize usuários e atribua o escopo a uma unidade administrativa dinâmica. Por exemplo, crie uma unidade administrativa dinâmica com usuários em que usertype = convidado. Quando os usuários externos são integrados ao Microsoft Entra ID, eles são adicionados à unidade administrativa. O aplicativo de LOB precisa tentar atualizar o usuári e pode levar mais de uma tentativa se houver atrasos. Apesar dos atrasos, essa abordagem permite que o aplicativo de LOB atualize usuários externos sem conceder permissão para atualizar qualquer usuário no diretório.