Integração de usuários externos a 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 linha de negócios (LOB). 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 aplicativos LOB integrados ao Microsoft Entra ID.
Os benefícios incluem:
- Integração de usuários e acesso aos aplicativos LOB. Os usuários têm acesso com alguns passos
- Os usuários externos trazem sua identidade e executam o logon único (SSO)
- Provisionamento de identidade externa para o Microsoft Entra ID
- O Acesso Condicional do Microsoft Entra e as políticas de acesso entre locatários para impor políticas de autorização, como autenticação multifator
Fluxo de integração
Para integrar aplicativos LOB com o Microsoft Entra B2B, siga este padrão:
- O usuário final dispara o convite dentro do aplicativo LOB e fornece o endereço de e-mail do usuário externo. O aplicativo verifica se o usuário já existe e, se não existir, prossegue para Criar e enviar 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 e-mail do usuário externo que é 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 falha de sucesso da chamada de API. Se bem-sucedida, a resposta inclui a ID do objeto de usuário do Microsoft Entra e o link de convite enviado para o email do usuário convidado. Você pode suprimir o email da Microsoft e enviar seu próprio email personalizado.
- (Opcional) Para escrever mais atributos para o usuário convidado ou adicionar o usuário convidado a um grupo. O aplicativo faz uma chamada de API extra para a API do Microsoft Graph.
- (Opcional) A API do Microsoft Graph faz as atualizações para o Microsoft Entra ID.
- (Opcional) A API do Microsoft Graph retorna o status de sucesso ou falha para o aplicativo.
- O aplicativo provisiona o usuário para seu banco de dados ou diretório de usuário back-end usando o atributo user object ID como o ID imutável.
- O aplicativo apresenta o status de sucesso ou falha para o usuário final.
Se a atribuição for necessária para acessar o aplicativo LOB, o usuário convidado será atribuído ao aplicativo com uma função de aplicativo. Habilite essa ação como outra chamada de API adicionando o convidado convidado a um grupo ou automatize a associação com grupos de associação dinâmica do Microsoft Entra. Os grupos de associação dinâmica não exigem outra chamada de API pelo aplicativo; no entanto, eles são atualizados tão rapidamente quanto adicionar um usuário a um grupo por meio de convite de usuário.
Confirme se o usuário externo está no diretório
É possível que o usuário externo tenha sido convidado e integrado. O aplicativo LOB verifica se o usuário está no diretório. Faça uma chamada de API para a API do Microsoft Graph e apresente as correspondências ao usuário convidado para que ele selecione.
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 detalhes do usuário na resposta, o usuário estará no diretório. Apresente os usuários retornados ao usuário convidado. Permitir que os usuários selecionem o usuário externo que obtém acesso. Para conceder ao usuário acesso ao aplicativo, fazer chamadas de API ou disparar outros processos.
Criar e enviar o convite
Se o usuário externo não estiver no diretório, use 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 para a API do Microsoft Graph.
Use os seguintes elementos:
- Solicitar que o usuário final forneça o endereço de e-mail do usuário externo
- Determine a URL do convite que redireciona os usuários convidados, depois que eles autenticarem e resgatarem o convite B2B
- A URL pode ser uma página de destino genérica ou determinada dinamicamente pelo aplicativo LOB com base em onde o usuário final disparou o convite
Mais sinalizadores e atributos para a solicitação de convite:
- Nome de exibição do usuário convidado
- E-mail de convite padrão da Microsoft ou suprimir o email padrão para criar o seu próprio
Depois que o aplicativo coleta as informações necessárias, o aplicativo deve POSTAR a solicitação para o gerenciador de convites da API do Microsoft Graph. Verifique se o registro do aplicativo tem 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"
}
Nota
Para ver as opções para o corpo JSON do convite, consulte 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 pacotes de acesso de gerenciamento de direitos. Crie um botão Convite em seu aplicativo LOB que dispara um email personalizado com URL de inscrição de autoatendimento ou uma URL de pacote de acesso. O usuário convidado embarca e acessa o aplicativo.
(Opcional) Escrever outros atributos para o Microsoft Entra ID
Importante
Conceder permissão a um aplicativo para atualizar usuários em seu diretório é uma ação altamente privilegiada. Se você conceder ao aplicativo essas permissões altamente privilegiadas, proteja e monitore seu aplicativo LOB.
Sua organização ou o aplicativo LOB pode exigir informações armazenadas para uso futuro, como emissão de declarações em tokens ou políticas de autorização granulares. Quando usuários externos são convidados ou criados no Microsoft Entra ID, um aplicativo pode fazer outra chamada de API para atualizá-los. O aplicativo deve ter permissões de API extras e uma chamada extra para a API do Microsoft Graph.
Para atualizar o usuário, use o ID do objeto do usuário convidado criado a partir da chamada da API de convite, o valor do 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 obter mais informações, consulte Atualizar usuário no Microsoft Graph v1.0.
(Opcional) Atribuir o usuário convidado a um grupo
Nota
Se a atribuição de usuário não for necessária para acessar o aplicativo, você poderá ignorar esta 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, faça outra chamada de API. O grupo é atribuído ao aplicativo e mapeado para uma função de 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 aos grupos que este aplicativo atualiza. Ou atribua a permissão na API do group.readwrite.all
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 obter mais informações, consulte 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 sensível ao tempo, essa abordagem não é recomendada porque os grupos dinâmicos de associação 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 de API. Em vez disso, crie um grupo que adicione o usuário como um 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 status.
Provisionar o usuário convidado para o aplicativo
Depois que o usuário externo convidado é provisionado na ID do Microsoft Entra, a API do Microsoft Graph retorna uma resposta com informações do usuário, como ID do objeto e email. O aplicativo LOB provisiona o usuário para seu 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 o aplicativo, o aplicativo LOB notifica o usuário iniciador de que o processo foi bem-sucedido. O usuário convidado obtém SSO com sua identidade sem a organização convidando a integração e emitindo credenciais extras. O Microsoft Entra ID impõe políticas de autorização com Acesso Condicional, autenticação multifator Microsoft Entra e Proteção de ID do Microsoft Entra.
Outras considerações
Certifique-se de que o tratamento de erros seja feito no aplicativo LOB. O aplicativo valida cada chamada de API. Se não forem bem-sucedidas, tentativas extras ou mensagens de erro são úteis.
Para que os aplicativos LOB atualizem usuários externos convidados, conceda uma função personalizada que permita que o aplicativo atualize usuários e atribua escopo a uma unidade administrativa dinâmica. Por exemplo, crie uma unidade administrativa dinâmica com usuários onde usertype = guest. Quando os usuários externos são integrados ao Microsoft Entra ID, eles são adicionados à unidade administrativa. O aplicativo LOB precisa tentar atualizar o usuário e pode levar mais de uma tentativa se houver atrasos. Apesar dos atrasos, a abordagem permite que o aplicativo LOB atualize usuários externos sem conceder permissão para atualizar qualquer usuário no diretório.