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

Com os conectores de API, é possível integrar com seus próprios fluxos de trabalho de aprovação personalizados com inscrição de autoatendimento para poder gerenciar quais contas de usuário convidado são criadas em seu locatário.

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

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

Importante

• A partir de 12 de julho de 2021, se os clientes do Microsoft Entra B2B configurarem novas integrações com o Google para serem usadas com a inscrição por autoatendimento em 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 exibições da Web do sistema. Saiba mais.
• A partir de 30 de setembro de 2021, o Google deixará de dar suporte para o logon de exibição da Web integrado. Caso seus aplicativos autentiquem usuários com um modo de exibição da Web inserido e você use a federação do Google com o Azure AD B2C ou o Microsoft Entra B2B para convites de usuário externo ou de inscrição por autoatendimento, os usuários do Gmail não poderão se autenticar. Saiba mais.

Registrar um aplicativo para seu sistema de aprovação

Dica

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

É necessário registrar seu sistema de aprovação como um aplicativo no locatário do Microsoft Entra para que ele possa ser autenticado com o Microsoft Entra ID e tenha permissão para criar usuários. Saiba mais sobre Noções básicas de autenticação e autorização para Microsoft Graph.

1. Entre no centro de administração do Microsoft Entra como, no mínimo, Administrador de Usuários.
2. Navegue até Identidade>Aplicativos>Registros de aplicativo e, em seguida, selecione Novo registro.
3. Insira um Nome para o aplicativo, por exemplo, Aprovações para inscrição.
4. Selecione Registrar. É possível deixar outros campos com seus respectivos valores padrão.

1. Em Gerenciar no menu à esquerda, selecione Permissões de APIe, em seguida, selecione Adicionar uma permissão.
2. Na página Solicitar permissões de API, escolha Microsoft Graph e, em seguida, selecione Permissões do Aplicativo.
3. Em Selecionar permissões, expanda o Usuárioe 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 de API, escolha Conceder consentimento de administrador para (nome do seu locatário) e, em seguida, escolha Sim.
10. Em Gerenciar no menu à esquerda, selecione Certificados e segredos e, em seguida, escolha Novo segredo do cliente.
11. Insira uma Descrição para o segredo, por exemplo, Aprovações do cliente secretoe selecione a duração de quando o segredo do cliente Expira. Em seguida, selecioneAdicionar.
12. Copie o valor do segredo do cliente. Os valores de segredo do cliente podem ser visualizados apenas imediatamente após a criação. Salve o segredo ao criá-lo, 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 gerou para autenticar com o Microsoft Entra ID.

Criar os conectores de API

Em seguida, você criará os conectores de API para seu fluxo de usuário de inscrição de autoatendimento. Sua API do 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:

• Verificação do status de aprovação. Envie uma chamada para o sistema de aprovação imediatamente depois que um usuário entrar com um provedor de identidade para verificar se o usuário tem uma solicitação de aprovação existente ou se já foi negado. Se o seu sistema de aprovação apenas tomar decisões de aprovação automática, esse conector de API poderá não ser necessário. Exemplo de um conector de API "Verificar o status de aprovação".

• Solicitação de aprovação – envie uma chamada para o sistema de aprovação depois que um usuário concluir a página de coleção de atributos, mas antes de a conta de usuário ser criada, para solicitar aprovação. A solicitação de aprovação pode ser automaticamente concedida ou examinada manualmente. Exemplo de um conector de API de "Solicitação de 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 adicione 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, no mínimo, Administrador de Usuários.

2. Navegue até Identidade>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 APIe, em seguida, selecione os pontos de extremidade de API que deseja invocar nas etapas a seguir no fluxo do usuário:

   • Após a federação com um provedor de identidade durante a inscrição: selecione seu conector de API de status de aprovação, como por exemplo, Verificar o status de aprovação.
   • Antes de criar o usuário: Selecione o conector de API de solicitação de aprovação, como por exemplo Solicitar aprovação.

1. Clique em Salvar.

Controlar o fluxo de inscrição com respostas de 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 de API "Verificar status de aprovação"

Exemplo da solicitação recebida pela API do conector de 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 à API dependem de quais informações são fornecidas pelo provedor de identidade. 'email ' é sempre enviado.

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

O ponto de extremidade da API Verificar status de aprovação deverá 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 deverá 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.

Os seguintes são 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 de API "Solicitar aprovação"

Exemplo de uma solicitação HTTP recebida pela API do conector de API "Solicitar 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 à API dependem de quais informações são coletadas do usuário ou foram fornecidas pelo provedor de identidade.

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

O ponto de extremidade da API Solicitar aprovação deverá 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 criará uma conta de usuário e direcionará o usuário para o aplicativo.

Bloqueio de resposta para "Solicitar aprovação"

O ponto de extremidade da API Solicitar aprovação deverá 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 de usuário foi negada automaticamente.

Os seguintes são 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 usuário após aprovação manual

Depois do sistema de aprovação personalizado obter 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 um email de senha de uso único

Importante

O sistema de aprovação deve verificar explicitamente que identities, identities[0] e identities[0].issuer estão presentes e que identities[0].issuer é igual a 'facebook', 'google' ou 'mail' para usar esse método.

Se o usuário tiver entrado com uma conta do Google ou Facebook ou uma senha de uso único de email, será possível usar a API de criação de usuário.

1. O sistema de aprovação usa o recebe a solicitação HTTP do fluxo do 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 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	Obrigatório	Descrição
userPrincipalName	Yes	Pode ser gerado por meio da email declaração enviada para a API, substituindo o caractere @ por _ e esperando-o previamente para #EXT@<tenant-name>.onmicrosoft.com.
accountEnabled	Yes	Deve ser definido como true.
mail	Yes	Equivalente à declaração email enviada para a API.
userType	Sim	Deve ser Guest. Designa esse usuário como um usuário convidado.
identidades	Yes	As informações de identidade federada.
<otherBuiltInAttribute>	Não	Outros atributos internos como displayName, city e outros. Os nomes de parâmetro são os mesmos que os parâmetros enviados pelo conector de API.
<extension_{extensions-app-id}_CustomAttribute>	Não	Atributos personalizados sobre o usuário. Os nomes de parâmetro são os mesmos que os parâmetros enviados pelo conector de API.

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

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

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

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 a 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óximas etapas

• Adicionar um fluxo dos usuários de inscrição por autoatendimento
• Adicionar um conector de API
• Proteger o conector de API
• inscrição por autoatendimento para usuários convidados com o exemplo de aprovação manual.