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 Azure AD 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

Registrar um aplicativo para seu sistema de aprovação

É necessário registrar seu sistema de aprovação como um aplicativo no locatário do Azure AD para que ele possa ser autenticado com o Azure AD 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 Portal do Azure como administrador do Microsoft Azure AD.

  2. Em Serviços do Azure, selecione Azure Active Directory.

  3. No menu à esquerda, selecione Registros de aplicativo e, em seguida, escolha Novo registro.

  4. Insira um Nome para o aplicativo, por exemplo, Aprovações para inscrição.

  5. Selecione Registrar. É possível deixar outros campos com seus respectivos valores padrão.

    Screenshot that highlights the Register button.

  6. Em Gerenciar no menu à esquerda, selecione Permissões de APIe, em seguida, selecione Adicionar uma permissão.

  7. Na página Solicitar permissões de API, escolha Microsoft Graph e, em seguida, selecione Permissões do Aplicativo.

  8. 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.

    Register an application page

  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 & 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.

    Copy the client secret for use in the approval system

  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 Azure AD.

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".

    Check approval status API connector configuration

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

    Request approval API connector configuration

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 Portal do Azure como administrador do Microsoft Azure AD.

  2. Em Serviços do Azure, selecione Azure Active Directory.

  3. No menu à esquerda, selecione Identidades Externas.

  4. Selecione Fluxos de usuárioe, em seguida, selecione o fluxo de usuário para o qual deseja habilitar o conector de API.

  5. 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.

    Add APIs to the user flow

  6. 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 para a 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 para a API dependem de quais informações são 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 Azure AD 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:

Example pending approval page

Criação de conta de usuário após aprovação manual

Depois de obter a aprovação manual, o sistema de aprovação personalizado 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"
}
  1. 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 Azure Active Directory ou conta de usuário Microsoft

Se um usuário entrar com uma conta federada do Azure Active Directory 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"
}
  1. 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>"
    }
}
  1. 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