Integrar 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). Assim como o botão Compartilhar disponível em muitos aplicativos do Office 365, os desenvolvedores de aplicativos podem criar uma experiência de convite com um único 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 apenas algumas etapas
- Os usuários externos trazem sua identidade e executam logon único (SSO)
- Provisionamento de identidade externa para Microsoft Entra ID
- O Acesso Condicional do Microsoft Entra e as políticas de acesso entre locatários permitem impor 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, vai para a etapa Criar e enviar 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 sucesso ou falha da chamada de API. Se for bem-sucedida, a resposta incluirá a ID de objeto de usuário do Microsoft Entra e o link do convite enviado para o email do usuário convidado. Você pode suprimir o email da Microsoft e enviar seu email personalizado.
- (Opcional) Para gravar mais atributos para o usuário convidado ou adicioná-lo 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 no 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 em seu banco de dados ou diretório de usuário de back-end usando o atributo de ID de objeto de usuário como 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 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, mas são atualizados com a mesma rapidez de adicionar um usuário a um grupo via convite para usuário.
Confirmar se o usuário externo está no diretório
É possível que o usuário externo foi 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 que está convidando para ele selecionar.
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ê recebe os detalhes do usuário na resposta, o usuário está no diretório. Apresente os usuários retornados ao usuário que está convidando. 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 dispare outros processos.
Criar e enviar o convite
Se o usuário externo ainda não estiver no diretório, use o Microsoft Entra B2B para convidá-lo e integrá-lo ao locatário do Microsoft Entra. Determine o que incluir na solicitação de convite para a API do Microsoft Graph.
Use os seguintes elementos:
- Solicite que o usuário final forneça o endereço de email do usuário externo
- Determine a URL de convite que redireciona os usuários convidados, depois que eles autenticam e resgatam o convite B2B
- A URL pode ser uma página de aterrisagem 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
- Usar email de convite padrão da Microsoft ou suprimir o email padrão para criar o seu
Depois que o aplicativo coletar as informações necessárias, deverá POSTAR a solicitação para o gerenciador de convites da API do Microsoft Graph. Verifique se o registro de 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"
}
Anotação
Para ver as opções disponíveis 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 para autoatendimento do Microsoft Entra ou os pacotes de acesso de gerenciamento de direitos. Crie um botão Convite em seu aplicativo LOB que dispara um email personalizado contendo uma URL de inscrição para autoatendimento ou uma URL de pacote de acesso. O usuário convidado é integrado 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 você conceder ao aplicativo essas permissões altamente privilegiadas, proteja e monitore o aplicativo LOB.
Sua organização ou o aplicativo LOB podem requerer o armazenamento de informações para uso futuro, como a emissão de declarações em tokens ou políticas de autorização granular. 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 extras de API e fazer uma chamada extra para a API do Microsoft Graph.
Para atualizar o usuário, use a ID de objeto do usuário convidado criado da chamada de API de convite, o valor de ID na resposta da API da verificação de existência ou o convite. Você pode gravar em qualquer atributo padrão ou em 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
Anotaçã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. Do 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.
Exemplo de permissões: atribuir 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 atualizados por esse aplicativo. 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 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 tem detecção de hora, essa abordagem não é recomendada, pois os grupos dinâmicos podem levar até 24 horas para serem preenchidos.
Se 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 membro de um 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 é provisionado no Microsoft Entra ID, a API do Microsoft Graph retorna uma resposta com informações do usuário, como ID de objeto e email. O aplicativo LOB provisiona o usuário em seu diretório ou banco de dados. A implementação 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 LOB notifica o usuário iniciante 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 adequado é feito no aplicativo LOB. O aplicativo valida cada chamada de API. Se não for bem-sucedido, tentativas extras ou mensagens de erro serão úteis.
Para que os aplicativos LOB atualizem os usuários externos convidados, conceda uma função personalizada que permita ao aplicativo atualizar os usuários e atribuir o escopo a uma unidade administrativa dinâmica. Por exemplo, crie uma unidade administrativa dinâmica com os usuários onde usertype = convidado. Quando os usuários externos são integrados ao Microsoft Entra ID, são adicionados à unidade administrativa. O aplicativo LOB precisa tentar atualizar o usuário e pode ser necessária mais de uma tentativa se houver atrasos. Apesar desses atrasos, a abordagem permite que o aplicativo LOB atualize usuários externos sem conceder permissão para atualizar qualquer usuário no diretório.