Menu

Configurar o Microsoft ADFS com o Flex

O ADFS (Active Directory Federation Services) é um componente de software desenvolvido pela Microsoft que pode ser executado em sistemas operacionais Windows Server. Ele oferece aos usuários acesso de logon único a sistemas e aplicativos localizados além das fronteiras organizacionais

Este guia percorrerá as etapas para configurar o ADFS como o IdP (Identity Provider, Provedor de identidade) para o Twilio Flex e pressupõe que você já tenha implantado a função de servidor ADFS. É possível saber mais sobre como implantar um farm de servidores ADFS na documentação da Microsoft.

Este guia foi escrito usando‐se o ADFS for Server 2019. Embora seja possível prever que essas etapas serão relativamente estáveis entre as versões, caso você tenha problemas, fique à vontade para informar a equipe da Twilio usando o widget de feedback no canto superior direito da página.

Execução do Assistente de configuração do ADFS

Caso o ADFS jamais tenha sido configurado neste servidor, talvez o assistente de configuração precise ser executado. Essas configurações não são específicas do Twilio.

1. Pressupondo‐se que você não tenha servidores, convém criar o primeiro servidor de federação em um farm de servidores de federação.

ADFS Wizard Step 1

2. Na próxima etapa, você precisará especificar qual conta deve ser usada durante a configuração do servidor.

ADFS Wizard Step 2

3. Em seguida, você precisará especificar as propriedades do serviço. Como os usuários verão o nome de exibição no login, convém usá‐lo para marcar o contact center para agentes e outras pessoas que façam login no contact center do Flex.

ADFS  Wizard Step 3

4. Especifique a conta de usuário do domínio de sua preferência.

ADFS Wizard Step 4

5. Por fim, especifique ou crie um banco de dados.

ADFS Wizard Step 5

Todas as verificações de pré‐requisito devem ser aprovadas com êxito. Depois disso, clique em "Configure" (Configurar) para concluir a instalação.

ADFS Wizard Step 6

Configuração da relação de confiança da parte confiável

Na interface do ADFS, adicione uma relação de confiança da parte confiável.

Add RPT 1

Verifique se Claim Aware está selecionado.

Add RPT Step 2

Na próxima etapa, selecione Enter data about the relying party manually.

Add RPT Step 3

Forneça um nome de exibição (por exemplo, Twilio Flex).

Add RPT Step 4

Como não há necessidade de especificar um certificado, é possível avançar à configuração do URL. Marque Enable support for SAML 2.0 WebSSO protocol. O URL do serviço SSO SAML 2.0 da parte confiável deve conter:

https://iam.twilio.com/v1/Accounts/ACXXXXXXXXXXXX/saml2/metadata

Substitua AC por seu AccountSID.

Add RPT Step 6 (Five skipped for simplicity)

On the next step, enter https://iam.twilio.com/v1/Accounts/ACXXXXXXXXXXXX/saml2 as the relying party trust identifier and click 'Add'. Be sure to replace ACXXX with your AccountSID.

002 Add RPT Step 7
Continue e permita que todos participem da política de controle de acesso

Add RPT Step 8

E clique em "Next" (Avançar) para adicionar a relação de confiança

Add RPT Step 9

Por fim, clique em "Close" (Fechar) para concluir a configuração da relação de confiança.

Add RPT Step 10

Edição da política de emissão das reivindicações/regras de reivindicação

Atributos LDAP

No painel "Actions" (Ações), escolha "Edit the Claim Issuance Policy" (Editar a política de emissão das reivindicações). Na janela pop‐up exibida, adicione uma nova regra.

Claims Issuance Step 1

Para o modelo de regra da solicitação, selecione "Send LDAP Attributes as Claims" (Enviar atributos LDAP como reivindicações). Em seguida, clique em "Next" (Avançar).

Claims Issuance Step 2

A página "Configure Rule" (Configurar regra) é exibida.

Claims Issuance Step 3

Forneça um nome para a reivindicação.

As funções são definidas adicionando‐se: "agent or admin" para o departamento do perfil do usuário.

Atributo LDAP Tipo de reivindicação de saída
Endereços de e‐mail Endereço de e‐mail
Endereços de e‐mail e‐mail
Nome de exibição full_name
Departamento funções

Se o campo "Department" (Departamento) já estiver em uso, a atribuição do grupo também poderá ser usada na aprovação de funções. Essa configuração usaria Token-Groups, em vez de Department, assim

Atributo LDAP Tipo de reivindicação de saída
Token-Groups – Nomes não qualificados funções

Estes são os campos obrigatórios do Flex, embora seja possível visitar os documentos de configuração do Flex SSO para consultar uma lista completa de campos possíveis que podem ser adicionados.

Clique no botão "Finish" (Concluir) quando terminar e adicione outra regra.

Transformação de reivindicações de entrada

Para essa regra, selecione Transform an Incoming Claim.

Transform Incoming Claim Step 1

Configure a regra de reivindicação assim:

Campo Valor
Nome da regra de reivindicação ID do nome
Tipo de reivindicação de entrada Endereço de e‐mail
Tipo de reivindicação de saída ID do nome
Formato do ID do nome de saída E‐mail

Transform Incoming Claim Step 2

Por fim, selecione Pass through all claim values e, em seguida, conclua a configuração da regra.

PowerShell

Por padrão, somente a asserção é assinada, mas, para que a integração funcione, a asserção e a mensagem precisam ser assinadas. Essa configuração pode ser definida por meio do PowerShell.

Em todos os comandos, substitua ACXXX pelo Account SID (SID da conta).

No Administrator Powershell, execute o seguinte comando:

Set-AdfsRelyingPartyTrust -TargetIdentifier https://iam.twilio.com/v1/Accounts/ACXXXXXX/saml2/metadata -SamlResponseSignature MessageAndAssertion

Você pode verificar a configuração usando o seguinte comando:

Get-AdfsRelyingPartyTrust -Identifier https://iam.twilio.com/v1/Accounts/ACXXXXX/saml2/metadata

SamlResponseSignature será definido como MessageAndAssertion.

Coletar dados do ADFS

Obter o certificado do ADFS

Agora você precisará obter alguns dados do ADFS que serão usados para configurar o lado do Twilio da integração do IdP.

Primeiro, vá até "Service" (Serviço) -> Certificates (Certificados) e clique com o botão direito do mouse em Token-signing certificate. Veja o certificado. Na guia "Details" (Detalhes), clique em Copy to File. Exporte como Base-64 encoded X.509 (.CER). Forneça um nome e selecione um local para exportá‐lo. Como você precisará copiar o conteúdo do certificado, verifique se é capaz de encontrá‐lo para as próximas etapas!

ADFS Certificate Details Tab

Registre o URL do provedor de identidade

Por padrão, o URL do provedor de identidade deve ser algo como http://<FQDN>/adfs/services/trust, em que FQDN é o nome de domínio totalmente qualificado associado à conta.

Para validá‐lo, abra o seguinte arquivo XML pelo servidor ADFS: https://localhost/FederationMetadata/2007-06/FederationMetadata.xml

ADFS XML Entity ID

Observe o atributo EntityID; ele deve ser o URL do provedor de identidade.

Configuração do Twilio

Agora está tudo pronto para configurar o Twilio a fim de conectar pessoas ao Flex usando o ADFS. Faça login no Twilio Console e navegue até a página Flex -> Single Sign On (Logon único).

Twilio Flex SSO Page

Preencha o formulário assim:

Campo Valor
Nome amigável Um nome de sua preferência (por exemplo, ADFS)
Certificado X.509 Copie e cole o conteúdo do certificado X.509 aberto anteriormente usando uma ferramenta como o Bloco de Notas. Deve ser uma string de texto longa.
Emissor do provedor de identidade O URL do provedor de identidade recebido anteriormente; por exemplo,http://<FQDN>/adfs/services/trust
URL de Single Sign-On https://<FQDN>/adfs/ls
URL de redirecionamento padrão https://flex.twilio.com/<runtime-domain>. O domínio de runtime pode ser encontrado no Twilio Console em "Functions" (Funções), "Assets" (Ativos) e em outras partes do Twilio Runtime. Ele estará no formato random-noun-1234.
URL de SSO do Twilio Selecione Uses iam.twilio.com
Faça login usando o pop‐up Isso é opcional. A integração SSO deve funcionar com ou sem esse recurso habilitado.

Como testar

Se tudo tiver sido configurado corretamente, agora será possível navegar até flex.twilio.com/<runtime-domain>, e você será redirecionado para a página de login do ADFS.

Depois de clicar em Sign In, você deverá ser redirecionado para o Flex!

Resolução de problemas

Para ajudar na resolução de problemas, instale a extensão do Chrome SAML Tracer. Essa ferramenta analisará as respostas SAML para facilitar a revisão durante a resolução de problemas.

Redirecionado para uma caixa de diálogo "Username / Password" (Nome de usuário/senha) do Twilio

Esse erro normalmente ocorre quando a transformação da reivindicação não foi definida corretamente. A resposta SAML será algo como:

</ds:X509Certificate>
            </ds:X509Data>
        </KeyInfo>
    </ds:Signature>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Requester">
            <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy" />
        </samlp:StatusCode>
    </samlp:Status>
</samlp:Response>

Anote o valor InvalidNameIDPolicy no StatusCode do requisitante.

Caso a resposta SAML seja aparentemente válida, verifique se o campo "Identity Provider Issuer" (Emissor do provedor de identidade) na página Flex SSO Console está correto.

A resposta SAML não tem um atributo "role"

Essa resposta é causada porque as funções não estão sendo passadas para as reivindicações. Verifique a configuração das reivindicações no ADFS e examine o atributo roles.

Classifique esta página:

Precisa de ajuda?

Às vezes, todos nós precisamos; a programação é difícil. Receba ajuda agora da nossa equipe de suporte, ou confie na sabedoria da multidão navegando pelo Stack Overflow Collective da Twilio ou buscando a tag Twilio no Stack Overflow.

Obrigado pelo seu feedback!

Selecione o(s) motivo(s) para seu feedback. As informações adicionais que você fornece nos ajudam a melhorar nossa documentação:

Enviando seu feedback...
🎉 Obrigado pelo seu feedback!
Algo deu errado. Tente novamente.

Obrigado pelo seu feedback!

thanks-feedback-gif