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.
2. Na próxima etapa, você precisará especificar qual conta deve ser usada durante a configuração do servidor.
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.
4. Especifique a conta de usuário do domínio de sua preferência.
5. Por fim, especifique ou crie um banco de dados.
Todas as verificações de pré‐requisito devem ser aprovadas com êxito. Depois disso, clique em "Configure" (Configurar) para concluir a instalação.
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.
Verifique se Claim Aware
está selecionado.
Na próxima etapa, selecione Enter data about the relying party manually
.
Forneça um nome de exibição (por exemplo, Twilio Flex
).
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.
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.
E clique em "Next" (Avançar) para adicionar a relação de confiança
Por fim, clique em "Close" (Fechar) para concluir a configuração da relação de confiança.
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.
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).
A página "Configure Rule" (Configurar regra) é exibida.
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
.
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 |
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!
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
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).
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.
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.