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

Aplica-se a: Locatários da força de trabalho Locatários externos (saiba mais)

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

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.

Registrar um aplicativo para seu sistema de aprovação

É 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 as 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ários.
2. Navegue atéregistros do aplicativo> e selecione Novo registro.
3. Insira um nome para o aplicativo, por exemplo, Aprovações de 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 API e, em seguida, selecione Adicionar uma permissão.
2. Na página Solicitar permissões de API , selecione o 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 de permissões de API , selecione Conceder consentimento do administrador para (seu nome de locatário) e selecione Sim.
10. Em Gerenciar no menu à esquerda, selecione Certificados &segredos e selecione Novo segredo do cliente.
11. Insira uma Descrição para o segredo, por exemplo, segredo do cliente Aprovações, e selecione a duração até a expiração do segredo do cliente. Em seguida, selecione Adicionar.
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 você gerou para autenticar com a ID do Microsoft Entra.

Criar os conectores de API

Em seguida, você criará os conectores de API para o 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:

• Verifique o 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".

• Solicitar aprovação – Enviar uma chamada para o sistema de aprovação depois que um usuário concluir a página de coleta 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 para 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 pelo menos um Administrador de Usuários.

2. Navegue para Entra ID>Identidades Externas>Fluxos de Usuário e selecione o fluxo de usuário que você deseja habilitar para o conector de API.

3. Selecione conectores de API e 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 o conector da API de status de aprovação, por exemplo, verifique o 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 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 endpoint 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 Check de 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.

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 endpoint da API de aprovação de solicitação deve retornar uma resposta de continuidade 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 de aprovação de solicitaçã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 que o sistema de aprovação personalizado obtém 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 entrou com uma conta do Google ou facebook ou senha única de email, você pode usar a API de criação do 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
Nome Principal do Usuário	Sim	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.
conta ativada	Sim	Deve ser definido como true.
correio	Sim	Equivalente à declaração email enviada para a API.
tipoDeUsuário	Sim	Deve ser Guest. Designa esse usuário como um usuário convidado.
identidades	Sim	As informações de identidade federada.
<outroAtributoEmbutido>	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.
<extensão_{extensions-app-id}_AtributoPersonalizado>	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 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 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 de inscrição de usuário autônomo
• Adicionar um conector de API
• Proteger seu conector de API
• Inscrição de autoatendimento para usuários convidados com exemplo de aprovação manual.