Configurar o Microsoft ADFS com o Flex

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

Este guia percorrerá as etapas para configurar o ADFS como o IdP (Identity Provider, Provedor de identidade) para o Twilio Flex e pressupõe que você já tenha implantado a função de servidor ADFS. É possível saber mais sobre como implantar um farm de servidores ADFS na documentação da Microsoft.

Este guia foi escrito usando‐se o ADFS for Server 2019. Embora seja possível prever que essas etapas serão relativamente estáveis entre as versões, caso você tenha problemas, fique à vontade para informar a equipe da Twilio usando o widget de feedback no canto superior direito da página.

Execução do Assistente de configuração do ADFS

Caso o ADFS jamais tenha sido configurado neste servidor, talvez o assistente de configuração precise ser executado. Essas configurações não são específicas do Twilio.

1. Pressupondo‐se que você não tenha servidores, convém criar o primeiro servidor de federação em um farm de servidores de federação.

2. Na próxima etapa, você precisará especificar qual conta deve ser usada durante a configuração do servidor.

3. Em seguida, você precisará especificar as propriedades do serviço. Como os usuários verão o nome de exibição no login, convém usá‐lo para marcar o contact center para agentes e outras pessoas que façam login no contact center do Flex.

4. Especifique a conta de usuário do domínio de sua preferência.

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

Todas as verificações de pré‐requisito devem ser aprovadas com êxito. Depois disso, clique em "Configure" (Configurar) para concluir a instalação.

Configuração da relação de confiança da parte confiável

Na interface do ADFS, adicione uma relação de confiança da parte confiável.

Verifique se Claim Aware está selecionado.

Na próxima etapa, selecione Enter data about the relying party manually.

Forneça um nome de exibição (por exemplo, Twilio Flex).

Como não há necessidade de especificar um certificado, é possível avançar à configuração do URL. Marque Enable support for SAML 2.0 WebSSO protocol. O URL do serviço SSO SAML 2.0 da parte confiá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.

Continue e permita que todos participem da política de controle de acesso

E clique em "Next" (Avançar) para adicionar a relação de confiança

Por fim, clique em "Close" (Fechar) para concluir a configuração da relação de confiança.

Edição da política de emissão das reivindicações/regras de reivindicação

Atributos LDAP

No painel "Actions" (Ações), escolha "Edit the Claim Issuance Policy" (Editar a política de emissão das reivindicações). Na janela pop‐up exibida, adicione uma nova regra.

Para o modelo de regra da solicitação, selecione "Send LDAP Attributes as Claims" (Enviar atributos LDAP como reivindicações). Em seguida, clique em "Next" (Avançar).

A página "Configure Rule" (Configurar regra) é exibida.

Forneça um nome para a reivindicação.

As funções são definidas adicionando‐se: "agent or admin" para o departamento do perfil do usuário.

Atributo LDAP	Tipo de reivindicação de saída
Endereços de e‐mail	Endereço de e‐mail
Endereços de e‐mail	e‐mail
Nome de exibição	full_name
Departamento	funções

Se o campo "Department" (Departamento) já estiver em uso, a atribuição do grupo também poderá ser usada na aprovação de funções. Essa configuração usaria Token-Groups, em vez de Department, assim

Atributo LDAP	Tipo de reivindicação de saída
Token-Groups – Nomes não qualificados	funções

Estes são os campos obrigatórios do Flex, embora seja possível visitar os documentos de configuração do Flex SSO para consultar uma lista completa de campos possíveis que podem ser adicionados.

Clique no botão "Finish" (Concluir) quando terminar e adicione outra regra.

Transformação de reivindicações de entrada

Para essa regra, selecione Transform an Incoming Claim.

Configure a regra de reivindicação assim:

Campo	Valor
Nome da regra de reivindicação	ID do nome
Tipo de reivindicação de entrada	Endereço de e‐mail
Tipo de reivindicação de saída	ID do nome
Formato do ID do nome de saída	E‐mail

Por fim, selecione Pass through all claim values e, em seguida, conclua a configuração da regra.

PowerShell

Por padrão, somente a asserção é assinada, mas, para que a integração funcione, a asserção e a mensagem precisam ser assinadas. Essa configuraçã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

Você pode verificar a configuração usando o seguinte comando:

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

SamlResponseSignature será definido como MessageAndAssertion.

Coletar dados do ADFS

Obter o certificado do ADFS

Agora você precisará obter alguns dados do ADFS que serão usados para configurar o lado do Twilio da integração do IdP.

Primeiro, vá até "Service" (Serviço) -> Certificates (Certificados) e clique com o botã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). Forneça um nome e selecione um local para exportá‐lo. Como você precisará copiar o conteúdo do certificado, verifique se é capaz de encontrá‐lo para as próximas etapas!

Registre o URL do provedor de identidade

Por padrão, o URL do provedor de identidade deve ser algo como http://<FQDN>/adfs/services/trust, em que FQDN é o nome de domínio totalmente qualificado associado à conta.

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

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

Configuração do Twilio

Agora está tudo pronto para configurar o Twilio a fim de conectar pessoas ao Flex usando o ADFS. Faça login no Twilio Console e navegue até a página Flex -> Single Sign On (Logon único).

Preencha o formulário assim:

Campo	Valor
Nome amigável	Um nome de sua preferência (por exemplo, ADFS)
Certificado X.509	Copie e cole o conteú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 padrão	`https://flex.twilio.com/<runtime-domain>`. O domínio de runtime pode ser encontrado no Twilio Console em "Functions" (Funções), "Assets" (Ativos) e em outras partes do Twilio Runtime. Ele estará no formato `random-noun-1234`.
URL de SSO do Twilio	Selecione `Uses iam.twilio.com`
Faça login usando o pop‐up	Isso é opcional. A integração SSO deve funcionar com ou sem esse recurso habilitado.

Como testar

Se tudo tiver sido configurado corretamente, agora será possível navegar até flex.twilio.com/<runtime-domain>, e você será redirecionado para a página de login do ADFS.

Depois de clicar em Sign In, você deverá ser redirecionado para o Flex!

Resolução de problemas

Para ajudar na resolução de problemas, instale a extensão do Chrome SAML Tracer. Essa ferramenta analisará as respostas SAML para facilitar a revisão durante a resolução de problemas.

Redirecionado para uma caixa de diálogo "Username / Password" (Nome de usuário/senha) do Twilio

Esse erro normalmente ocorre quando a transformação da reivindicação não foi definida corretamente. A resposta SAML será 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 válida, verifique se o campo "Identity Provider Issuer" (Emissor do provedor de identidade) na página Flex SSO Console está correto.

A resposta SAML não tem um atributo "role"

Essa resposta é causada porque as funções não estão sendo passadas para as reivindicações. Verifique a configuração das reivindicações no ADFS e examine o atributo roles.

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.

Precisa de ajuda?

Obrigado pelo seu feedback!

Obrigado pelo seu feedback!