Adicionar um fluxo de trabalho de aprovação personalizado à inscrição de autoatendimento

Com conectores de API, você pode integrar com seus próprios fluxos de trabalho de aprovação personalizados com inscrição de autoatendimento para gerenciar quais contas de usuário convidado são criadas em seu locatário.

Este artigo dá um exemplo de como integrar com um sistema de aprovação. Neste exemplo, o fluxo de usuário de inscrição de autoatendimento coleta dados do usuário durante o processo de inscrição e os passa para o sistema de aprovação. Em seguida, o sistema de homologação pode:

• Aprove automaticamente o usuário e permita que o Microsoft Entra ID crie a conta de usuário.
• Acione uma revisão manual. Se a solicitação for aprovada, o sistema de aprovação usará o Microsoft Graph para provisionar a conta de usuário. O sistema de aprovação também pode notificar o utilizador de que a sua conta foi criada.

Importante

• A partir de 12 de julho de 2021, se os clientes do Microsoft Entra B2B configurarem novas integrações do Google para uso com a inscrição de autoatendimento para seus aplicativos personalizados ou de linha de negócios, a autenticação com identidades do Google não funcionará até que as autenticações sejam movidas para as visualizações da Web do sistema. Mais informações.
• A partir de 30 de setembro de 2021, o Google está desativando o suporte de login incorporado à visualização da Web. Se seus aplicativos autenticarem usuários com uma visualização da Web incorporada e você estiver usando a federação do Google com o Azure AD B2C ou o Microsoft Entra B2B para convites de usuários externos ou inscrição de autoatendimento, os usuários do Google Gmail não poderão se autenticar. Mais informações.

Registar um pedido para o seu sistema de aprovação

Gorjeta

As etapas neste artigo podem variar ligeiramente com base no portal a partir do qual você começou.

Você precisa registrar seu sistema de aprovação como um aplicativo em seu locatário do Microsoft Entra para que ele possa se autenticar com o ID do Microsoft Entra e ter permissão para criar usuários. Saiba mais sobre noções básicas de autenticação e autorização para o Microsoft Graph.

1. Entre no centro de administração do Microsoft Entra como pelo menos um Administrador de Usuário.
2. Navegue até Registros do aplicativo Aplicativos de identidade>>e selecione Novo registro.
3. Insira um Nome para o aplicativo, por exemplo, Aprovações de inscrição.
4. Selecione Registar. Você pode deixar outros campos em seus padrões.

1. Em Gerenciar no menu à esquerda, selecione Permissões de API e, em seguida, selecione Adicionar uma permissão.
2. Na página Solicitar permissões da API, selecione Microsoft Graph e, em seguida, selecione Permissões de aplicativo.
3. Em Selecionar permissões, expanda Usuário e marque a caixa de seleção User.ReadWrite.All . Essa permissão permite que o sistema de aprovação crie o usuário após a aprovação. Em seguida, selecione Adicionar permissões.

9. Na página Permissões da API, selecione Conceder consentimento de administrador para (seu nome de locatário) e selecione Sim.
10. Em Gerenciar no menu à esquerda, selecione Certificados & segredos e, em seguida, selecione Novo segredo do cliente.
11. Insira uma Descrição para o segredo, por exemplo , Segredo do cliente de aprovações, e selecione a duração para quando o segredo do cliente expirar. Em seguida, selecione Adicionar.
12. Copie o valor do segredo do cliente. Os valores secretos do cliente podem ser visualizados apenas imediatamente após a criação. Certifique-se de salvar o segredo quando criado, antes de sair da página.

13. Configure seu sistema de aprovação para usar a ID do aplicativo como a ID do cliente e o segredo do cliente que você gerou para autenticar com a ID do Microsoft Entra.

Criar os conectores de API

Em seguida, você criará os conectores de API para seu fluxo de usuário de inscrição de autoatendimento. A API do seu sistema de aprovação precisa de dois conectores e pontos de extremidade correspondentes, como os exemplos mostrados abaixo. Esses conectores de API fazem o seguinte:

• Verifique o status de aprovação. Envie uma chamada para o sistema de aprovação imediatamente após um usuário entrar com um provedor de identidade para verificar se o usuário tem uma solicitação de aprovação existente ou já foi negada. Se o seu sistema de aprovação fizer apenas decisões de aprovação automáticas, este conector de API pode não ser necessário. Exemplo de um conector de API "Verificar status de aprovação".

• Solicitar aprovação - Envie uma chamada para o sistema de aprovação depois que um usuário concluir a página de coleta de atributos, mas antes que a conta de usuário seja criada, para solicitar aprovação. O pedido de aprovação pode ser concedido automaticamente ou revisto manualmente. Exemplo de um conector de API "Solicitar aprovação".

Para criar esses conectores, siga as etapas em Criar um conector de API.

Habilitar os conectores de API em um fluxo de usuário

Agora você adicionará os conectores de API a um fluxo de usuário de inscrição de autoatendimento com estas etapas:

1. Entre no centro de administração do Microsoft Entra como pelo menos um Administrador de Usuário.

2. Navegue até Identidades>externas Fluxos>de usuário e selecione o fluxo de usuário para o qual você deseja habilitar o conector de API.

3. Selecione conectores de API e, em seguida, selecione os pontos de extremidade de API que você deseja invocar nas seguintes etapas no fluxo de usuário:

   • Depois de federar com um provedor de identidade durante a inscrição: selecione seu conector de API de status de aprovação, por exemplo , Verificar status de aprovação.
   • Antes de criar o usuário: selecione o conector da API de solicitação de aprovação, por exemplo , Solicitar aprovação.

1. Selecione Guardar.

Controle o fluxo de inscrição com respostas da API

Seu sistema de aprovação pode usar suas respostas quando chamado para controlar o fluxo de inscrição.

Solicitação e respostas para o conector da API "Verificar status de aprovação"

Exemplo da solicitação recebida pela API do conector da API "Verificar status de aprovação":

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ //Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

As declarações exatas enviadas para a API dependem de quais informações são fornecidas pelo provedor de identidade. 'e-mail' é sempre enviado.

Resposta de continuação para "Verificar status de aprovação"

O ponto de extremidade da API Verificar status de aprovação deve retornar uma resposta de continuação se:

• O usuário não solicitou uma aprovação anteriormente.

Exemplo de resposta de continuação:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue"
}

Resposta de bloqueio para "Verificar status de aprovação"

O ponto de extremidade da API Verificar status de aprovação deve retornar uma resposta de bloqueio se:

• A aprovação do usuário está pendente.
• O usuário foi negado e não deve ter permissão para solicitar aprovação novamente.

Seguem-se exemplos de respostas de bloqueio:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your access request is already processing. You'll be notified when your request has been approved.",
}

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your sign up request has been denied. Please contact an administrator if you believe this is an error",
}

Solicitação e respostas para o conector da API "Solicitar aprovação"

Exemplo de uma solicitação HTTP recebida pela API do conector da API "Solicitação de aprovação":

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

As declarações exatas enviadas para a API dependem de quais informações são coletadas do usuário ou fornecidas pelo provedor de identidade.

Resposta de continuação para "Solicitar aprovação"

O ponto de extremidade da API de aprovação de solicitação deve retornar uma resposta de continuação se:

• O usuário pode ser aprovado automaticamente.

Exemplo de resposta de continuação:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue"
}

Importante

Se uma resposta de continuação for recebida, o Microsoft Entra ID criará uma conta de usuário e direcionará o usuário para o aplicativo.

Resposta de bloqueio para "Solicitar aprovação"

O ponto de extremidade da API de aprovação de solicitação deve retornar uma resposta de bloqueio se:

• Uma solicitação de aprovação de usuário foi criada e agora está pendente.
• Uma solicitação de aprovação do usuário foi negada automaticamente.

Seguem-se exemplos de respostas de bloqueio:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your account is now waiting for approval. You'll be notified when your request has been approved.",
}

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your sign up request has been denied. Please contact an administrator if you believe this is an error",
}

O userMessage na resposta é exibido para o usuário, por exemplo:

Criação de conta de utilizador após aprovação manual

Depois que o sistema de aprovação personalizado obtém a aprovação manual, ele cria uma conta de usuário usando o Microsoft Graph. A maneira como seu sistema de aprovação provisiona a conta de usuário depende do provedor de identidade que foi usado pelo usuário.

Para um usuário federado do Google ou Facebook e senha única por e-mail

Importante

O sistema de aprovação deve verificar explicitamente se identities, identities[0] e identities[0].issuer estão presentes e que identities[0].issuer é igual a «facebook», «google» ou «mail» para utilizar este método.

Se o utilizador tiver iniciado sessão com uma conta Google ou Facebook ou um código de acesso único por e-mail, pode utilizar a API de criação de utilizador.

1. O sistema de aprovação usa recebe a solicitação HTTP do fluxo de usuário.

POST <Approvals-API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@outlook.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value",
 "ui_locales":"en-US"
}

2. O sistema de aprovação usa o Microsoft Graph para criar uma conta de usuário.

POST https://graph.microsoft.com/v1.0/users
Content-type: application/json

{
 "userPrincipalName": "johnsmith_outlook.com#EXT@contoso.onmicrosoft.com",
 "accountEnabled": true,
 "mail": "johnsmith@outlook.com",
 "userType": "Guest",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value"
}

Parâmetro	Necessário	Description
userPrincipalName	Sim	Pode ser gerado pegando a email declaração enviada para a API, substituindo o @caractere por _, e pré-pendente para #EXT@<tenant-name>.onmicrosoft.com.
accountEnabled	Sim	Deve ser definido como true.
correio	Sim	Equivalente à email declaração enviada para a API.
userType	Sim	Deve ser Guest. Designa este utilizador como utilizador convidado.
identidades	Sim	As informações de identidade federada.
<otherBuiltInAttribute>	Não	Outros atributos internos como displayName, city, e outros. Os nomes dos parâmetros são os mesmos que os parâmetros enviados pelo conector da API.
<extension_{extensions-app-id}_CustomAttribute>	Não	Atributos personalizados sobre o usuário. Os nomes dos parâmetros são os mesmos que os parâmetros enviados pelo conector da API.

Para um usuário federado do Microsoft Entra ou usuário da conta da Microsoft

Se um usuário entrar com uma conta federada do Microsoft Entra ou uma conta da Microsoft, você deverá usar a API de convite para criar o usuário e, opcionalmente, a API de atualização do usuário para atribuir mais atributos ao usuário.

1. O sistema de aprovação recebe a solicitação HTTP do fluxo de usuários.

POST <Approvals-API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value",
 "ui_locales":"en-US"
}

2. O sistema de aprovação cria o convite usando o email fornecido pelo conector da API.

POST https://graph.microsoft.com/v1.0/invitations
Content-type: application/json

{
    "invitedUserEmailAddress": "johnsmith@fabrikam.onmicrosoft.com",
    "inviteRedirectUrl" : "https://myapp.com"
}

Exemplo da resposta:

HTTP/1.1 201 OK
Content-type: application/json

{
    ...
    "invitedUser": {
        "id": "<generated-user-guid>"
    }
}

3. O sistema de aprovação usa o ID do usuário convidado para atualizar a conta do usuário com atributos de usuário coletados (opcional).

PATCH https://graph.microsoft.com/v1.0/users/<generated-user-guid>
Content-type: application/json

{
    "displayName": "John Smith",
    "city": "Redmond",
    "extension_<extensions-app-id>_AttributeName": "custom attribute value"
}

Próximos passos

• Adicionar um fluxo de usuário de inscrição de autoatendimento
• Adicionar um conector de API
• Proteja seu conector de API
• Inscrição de autoatendimento para usuários convidados com amostra de aprovação manual.