Share via

Integração de usuários externos a aplicativos de linha de negócios usando o Microsoft Entra B2B

  • Artigo

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 qualquer aplicativo LOB integrado ao Microsoft Entra ID.

Os benefícios incluem:

  • Integração de usuários simples e fácil e acesso aos aplicativos LOB com usuários capazes de obter acesso com algumas etapas.

  • Permite que os usuários externos tragam sua própria identidade e executem o logon único (SSO).

  • Provisionamento automático de identidades externas para o Microsoft Entra ID.

  • Aplique o Acesso Condicional do Microsoft Entra e as políticas de acesso entre locatários para impor políticas de autorização, como exigir autenticação multifator.

Fluxo de integração

Para integrar aplicativos LOB com o Microsoft Entra B2B, siga este padrão:

Screenshot shows the integration of LOB applications.

Passo Description
1. 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 a etapa #2
2. 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 na Etapa #1.
3. A API do Microsoft Graph provisiona o Usuário Convidado na ID do Microsoft Entra.
4. A API do Microsoft Graph retorna o status de sucesso/falha 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 que é enviado para o email do usuário convidado. Opcionalmente, você pode suprimir o email da Microsoft e enviar seu próprio email personalizado.
5. (Opcional) Se você quiser 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.
6. (Opcional) A API do Microsoft Graph faz as atualizações desejadas para o Microsoft Entra ID.
7. (Opcional) A API do Microsoft Graph retorna o status de sucesso/falha para o aplicativo.
8. O aplicativo provisiona o usuário para seu próprio diretório de usuário de banco de dados/back-end usando o atributo object ID do usuário como o ID imutável.
9. O aplicativo apresenta o status de sucesso/falha para o usuário final.

Se a atribuição for necessária para acessar o aplicativo LOB, o Usuário convidado também deverá ser atribuído ao aplicativo com uma função de aplicativo apropriada. Isso pode ser feito como outra chamada de API adicionando o convidado convidado a um grupo (etapas #5-7) ou automatizando a associação ao grupo com grupos dinâmicos do Microsoft Entra. O uso de grupos dinâmicos não exigiria outra chamada de API pelo aplicativo. No entanto, a associação ao grupo não seria atualizada tão rapidamente em comparação com a adição de um usuário a um grupo imediatamente após o convite do usuário.

Etapa 1: Verificar se o usuário externo já existe

É possível que o usuário externo tenha sido previamente convidado e integrado. O aplicativo LOB deve verificar se o usuário já existe no diretório. Há muitas abordagens, no entanto, a mais simples envolve fazer uma chamada de API para a API do Microsoft Graph e apresentar as possíveis 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, o usuário já existe. Você deve apresentar os usuários retornados ao usuário convidado e permitir que eles escolham qual usuário externo desejam conceder acesso. Você deve continuar a fazer chamadas de API apropriadas ou acionar outros processos para conceder a esse usuário acesso ao aplicativo em vez de prosseguir com a etapa de convite.

Etapa 2: criar e enviar convite

Se o usuário externo ainda não existir no diretório, você pode usar o Microsoft Entra B2B para convidar o usuário e integrá-lo ao seu locatário do Microsoft Entra. Como desenvolvedor de aplicativos, você precisa determinar o que incluir na solicitação de convite para a API do Microsoft Graph.

No mínimo, você precisa:

  • Solicitar que o usuário final forneça o endereço de e-mail do usuário externo.

  • Determine o URL do convite. Esse URL é para onde o usuário convidado é redirecionado depois de autenticar e resgatar o convite B2B. A URL pode ser uma página de destino genérica para o aplicativo ou determinada dinamicamente pelo aplicativo LOB com base em onde o usuário final disparou o convite.

Mais sinalizadores e atributos a serem considerados para inclusão na solicitação de convite:

  • Nome para exibição do usuário convidado.
  • Determine se você deseja usar o email de convite padrão da Microsoft ou suprimir o email padrão para criar o seu próprio.

Depois que o aplicativo tiver coletado as informações necessárias e determinado quaisquer outros sinalizadores ou informações a serem incluídos, o aplicativo deve POSTAR a solicitação para o gerenciador de convites da API do Microsoft Graph. Verifique se o registro do aplicativo tem as permissões apropriadas 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 a lista completa de opções disponíveis para o corpo JSON do convite, confira o tipo de recurso de convite - Microsoft Graph v1.0.

Os desenvolvedores de aplicativos podem, alternativamente, integrar usuários externos usando a inscrição de autoatendimento do Microsoft Entra ou pacotes de acesso de gerenciamento de direitos. Você pode criar seu botão de convite em seu aplicativo LOB que dispara um e-mail personalizado contendo uma URL de inscrição de autoatendimento predefinida ou uma URL de pacote de acesso. O usuário convidado, em seguida, autosserviço a bordo e acessar o aplicativo.

Etapa 3: Escrever outros atributos para o Microsoft Entra ID (opcional)

Importante

Conceder permissão a um aplicativo para atualizar usuários em seu diretório é uma ação altamente privilegiada. Você deve tomar medidas para proteger e monitorar seu aplicativo LOB se conceder ao aplicativo essas permissões altamente privilegiadas.

Sua organização ou o aplicativo LOB pode precisar armazenar mais informações para uso futuro, como emissão de declarações em tokens ou políticas de autorização granulares. Seu aplicativo pode fazer outra chamada de API para atualizar o usuário externo depois que ele for convidado/criado no Microsoft Entra ID. Isso requer que seu aplicativo tenha permissões de API extras e exigiria uma chamada extra para a API do Microsoft Graph.

Para atualizar o usuário, você precisa usar o ID do objeto do Usuário convidado recém-criado recebido na resposta da chamada de API de convite. Este é o valor de ID na resposta da API da verificação de existência ou do convite. Você pode gravar em qualquer atributo padrão ou atributos de extensão personalizados que possa ter criado.

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 - Microsoft Graph v1.0.

Etapa 4: 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 deverá ser atribuído ao aplicativo, caso contrário, o usuário não poderá obter acesso independentemente da autenticação bem-sucedida. Para conseguir isso, você deve fazer outra chamada de API para adicionar o usuário externo convidado a um grupo específico. O grupo pode ser atribuído ao aplicativo e mapeado para uma função específica do aplicativo.

Por exemplo:

Permissões: atribua a função de atualizador de grupo ou uma função personalizada ao aplicativo corporativo e defina o escopo da atribuição de função apenas aos grupos que esse aplicativo deve atualizar. 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 - Microsoft Graph v1.0.

Como alternativa, você pode usar grupos dinâmicos do Microsoft Entra, que podem atribuir automaticamente usuários ao grupo com base nos atributos do usuário. No entanto, se o acesso do usuário final for sensível ao tempo, essa não será a abordagem recomendada, pois os grupos dinâmicos podem levar até 24 horas para serem preenchidos.

Se preferir usar grupos dinâmicos, não será necessário adicionar os usuários a um grupo explicitamente com outra chamada de API. Crie um grupo dinâmico que adicione automaticamente o usuário como membro do grupo com base em atributos disponíveis, como userType, email ou um atributo personalizado. Para obter mais informações, consulte Criar ou editar um grupo dinâmico e obter status.

Etapa 5: Provisionar o usuário convidado para o aplicativo

Depois que o usuário externo convidado tiver sido provisionado para o Microsoft Entra ID, a API do Microsoft Graph retornará uma resposta com as informações necessárias do usuário, como ID do objeto e email. O aplicativo LOB pode então provisionar o usuário para seu próprio diretório/banco de dados. Dependendo do tipo de aplicativo e do tipo de diretório interno que o aplicativo usa, a implementação real desse provisionamento varia.

Com o usuário externo provisionado no Microsoft Entra ID e no aplicativo, o aplicativo LOB agora pode notificar o usuário final que iniciou o convite de que o processo foi bem-sucedido. O usuário convidado pode obter SSO com sua própria identidade sem que a organização convidadora precise integrar e emitir credenciais extras. O Microsoft Entra ID pode impor políticas de autorização, como Acesso Condicional, autenticação multifator do Microsoft Entra e Proteção de Identidade baseada em risco.

Outras considerações

  • Certifique-se de que o tratamento adequado de erros seja feito dentro do aplicativo LOB. O aplicativo deve validar se cada chamada de API foi bem-sucedida. Se não forem bem-sucedidas, tentativas extras ou a apresentação de mensagens de erro ao usuário final serão apropriadas.

  • Se você precisar que o aplicativo LOB atualize os usuários externos depois que eles forem convidados, considere conceder uma função personalizada que permita que o aplicativo atualize apenas os usuários e atribua o escopo a uma unidade administrativa dinâmica. Por exemplo, você pode criar uma unidade administrativa dinâmica para conter todos os usuários onde usertype = guest. Depois que o usuário externo é integrado ao Microsoft Entra ID, leva algum tempo para que ele seja adicionado à unidade administrativa. Portanto, o aplicativo LOB precisa tentar atualizar o usuário depois de algum tempo e pode levar mais de uma tentativa se houver atrasos. Apesar desses atrasos, essa é a melhor abordagem disponível para permitir que o aplicativo LOB atualize usuários externos sem conceder permissão para atualizar qualquer usuário no diretório.