O single sign-on é um mecanismo que permite que você autentique os usuários nos sistemas e, posteriormente, informe ao Zendesk que o usuário foi autenticado. Se você usa single sign-on com Token da web JSON (JWT), um usuário é automaticamente verificado com o provedor de identidade na entrada. Em seguida, o usuário recebe permissão para acessar o Zendesk sem que sejam solicitadas credenciais de entrada independentes.
Como administrador do Zendesk, sua função consiste em ativar as opções de SSO. Este artigo descreve como ativar várias configurações de single sign-on com JWT que podem ser usadas para autenticar membros da equipe (administradores e agentes, incluindo agentes light e colaboradores), usuários finais ou ambos.
No centro do single sign-on está um mecanismo de segurança que permite que o Zendesk confie nas solicitações de acesso que recebe de seus sistemas. O Zendesk libera acesso apenas aos usuários que você autenticou. O SSO do Zendesk conta com o JWT para assegurar a troca de dados de autenticação do usuário.
- Como funciona o SSO com JWT no Zendesk
- Requisitos para ativação de SSO com JWT
- Ativação de SSO com JWT
- Atribuição de SSO com JWT a usuários
- Gerenciamento de usuários no Zendesk após ativação de SSO com JWT
- Geração de um novo segredo compartilhado
- Alternância de métodos de autenticação
- Informações adicionais sobre o JWT
A equipe de TI de uma empresa em geral é responsável pela configuração e pelo gerenciamento do sistema de autenticação com JWT da empresa. Sua função é implementar o SSO para o Zendesk no sistema. Indique o tópico deste artigo para a equipe:
Artigos relacionados:
Como funciona o SSO com JWT no Zendesk
Depois de ativar o SSO, as solicitações de acesso são encaminhadas para uma página externa ao Zendesk Support.
Etapas do processo de autenticação de SSO com JWT:
- Um usuário não autenticado acessa a URL de seu Zendesk Support. Por exemplo: https://seusubdominio.zendesk.com/.
- O mecanismo de SSO do Zendesk reconhece que o SSO está ativado e que o usuário não está autenticado.
- O Zendesk busca identificar se o usuário não autenticado é um usuário final ou membro da equipe e redireciona o usuário para a página de entrada remota apropriada da sua organização. Por exemplo: https://minhaempresa.com/zendesk/sso.
- Um script no servidor remoto autentica o usuário usando o processo de acesso próprio de sua empresa.
- O sistema de autenticação cria uma solicitação JWT que contém os dados do usuário relevantes.
- O sistema de autenticação redireciona o usuário para o seguinte ponto de extremidade do Zendesk com a carga do JWT:
https://seusubdominio.zendesk.com/access/jwt
- O Zendesk verifica o token e analisa os detalhes do usuário a partir da carga do JWT e concede uma sessão ao usuário.
Como você pode observar, esse processo baseia-se em redirecionamentos do navegador e na transmissão de mensagens assinadas usando o JWT. Os redirecionamentos acontecem exclusivamente no navegador, sem conexão direta entre o Zendesk e seus sistemas, para que você possa manter seus scripts de autenticação seguros atrás de seu firewall corporativo.
Requisitos para ativação de SSO com JWT
Reúna-se com a equipe de sua empresa responsável pelo sistema de autenticação com JWT (em geral, a equipe de TI) para assegurar que o tráfego associado ao Zendesk é via HTTPS, não HTTP.
- A URL de acesso remoto para onde os usuários do Zendesk devem ser redirecionados quando tentam acessar o Zendesk.
- (Opcional) A URL de saída remota para onde o Zendesk possa redirecionar os usuários após saírem do Zendesk.
- (Opcional) Uma lista de intervalos de IP para redirecionar os usuários à opção de entrada apropriada. Os usuários que fazem solicitações dos intervalos de IP especificados são encaminhados ao formulário de acesso com autenticação com JWT remota. Os usuários que fazem solicitações de endereços IP fora dos intervalos especificados são encaminhados ao formulário normal de acesso do Zendesk. Se você não especificar um intervalo, todos os usuários são redirecionados ao formulário de acesso com autenticação remota.
A equipe de TI poderá exigir informações adicionais da Zendesk para configurar a implementação do JWT. Indique à equipe a Planilha de implementação técnica deste artigo.
Depois de confirmar que atende aos requisitos e têm todas as informações necessárias, você estará com tudo pronto para ativar o SSO com JWT.
Ativação de SSO com JWT
Os administradores podem ativar o single sign-on com JWT apenas para usuários finais, apenas para membros da equipe (incluindo agentes light e colaboradores) ou para os dois grupos. É possível criar várias configurações de SSO com JWT. Antes de começar, obtenha as informações necessárias da equipe de TI de sua empresa. Consulte Requisitos para ativação de SSO com JWT.
Como ativar o single sign-on com JWT
- Na Central de administração, clique em
Conta na barra lateral e selecione Segurança > Single sign-on. - Clique em Criar configuração de SSO e selecione Token da web JSON.
- Insira um Nome da configuração único.
- Em URL de acesso remoto, insira a URL para a qual os usuários devem ser redirecionados quando tentam acessar a URL de seu Zendesk.
O Zendesk adiciona automaticamente o parâmetro brand_id à URL. Essa é a marca Zendesk Support onde o usuário estava quando tentou acessar o sistema.
- (Opcional) Em URL de saída remota, insira uma URL de saída para onde os usuários devem ser redirecionados após saírem do Zendesk.
O Zendesk adiciona automaticamente os parâmetros email, external_id e brand_id à URL de saída. Caso prefira não ter as informações de e-mail ou de ID externa na URL, especifique parâmetros em branco na URL de saída. Por exemplo:
https://www.xyz.com/user/signout/?email=&external_id=
Observação: se você estiver usando um aplicativo Ember.js, precisará alterar a URL de saída para usar parâmetros em branco antes do hash. Por exemplo,https://somedomain.com/?brand_id=&return_to=&email=#/zendesk-login/. - (Opcional) Em Intervalos de IP, insira uma lista de intervalos de IP se você deseja redirecionar os usuários à opção de acesso apropriada.
Os usuários que fazem solicitações dos intervalos de IP especificados são encaminhados ao formulário de acesso com autenticação com JWT. Os usuários que fazem solicitações de endereços IP fora dos intervalos especificados são encaminhados ao formulário normal de acesso do Zendesk. Não especifique um intervalo se quiser que todos os usuários sejam redirecionados ao formulário de acesso com autenticação com JWT.
- Se você usar external_IDs para seus usuários, pode atualizá-las no Zendesk Support selecionando Ativado em Atualizar IDs externas?.
- Informe o Segredo compartilhado à sua equipe de TI. A equipe precisará dele para a implantação do JWT. Importante: mantenha o segredo compartilhado em segurança. Caso ele seja comprometido, todos os dados de sua conta do Support estarão em risco.
- Selecione Mostrar botão quando os usuários entrarem para adicionar um botão Continuar com o SSO à página de entrada do Zendesk.
Você pode personalizar o rótulo do botão inserindo um valor no campo Nome do botão. Rótulos de botão personalizados são úteis se você adicionar vários botões de SSO à página de entrada. Consulte Adição de botões "Continuar com o SSO" à página de entrada do Zendesk para obter mais informações.
- Clique em Salvar.
Por padrão, as configurações de SSO do Enterprise estão inativas. É preciso atribuir a configuração de SSO a usuários para ativá-la.
Atribuição de SSO com JWT a usuários
Depois de criar a configuração de SSO com JWT, atribua-a usuários finais, membros da equipe ou ambos para ativá-la.
Como atribuir uma configuração de SSO a membros da equipe ou usuários finais
- Abra as configurações de segurança para membros da equipe ou usuários finais.
- Na Central de administração, clique em Conta na barra lateral e selecione Segurança > Autenticação de membro da equipe.
- Na Central de administração, clique em Conta na barra lateral e selecione Segurança > Autenticação de usuário final.
- Na Central de administração, clique em
- Selecione Autenticação externa para mostrar as opções de autenticação.
- Selecione os nomes das configurações de SSO que você deseja usar.
O single sign-on pode não atender a todos os casos de uso, então a autenticação do Zendesk permanece ativa por padrão.
- Selecione como você gostaria de permitir a entrada de usuários.
A opção Deixar que eles escolham permite que os usuários entrem usando qualquer método de autenticação ativo. Consulte Diferentes maneiras de permitir que usuários entrem no Zendesk.
A opção Redirecionar para o SSO apenas permite que usuários se autentiquem usando a configuração de SSO principal. Os usuários não veem opções adicionais de entrada, mesmo que essas opções de autenticação estejam ativas. Quando você seleciona Redirecionar para o SSO, o campo SSO principal aparece para que selecione a configuração de SSO principal.
- Clique em Salvar.
Gerenciamento de usuários no Zendesk após ativação de SSO com JWT
Depois de ativar o single sign-on com JWT no Zendesk, as alterações feitas em usuários fora do Zendesk não são sincronizadas automaticamente com sua conta do Zendesk. Os usuários são atualizados no Zendesk no ponto de autenticação. Por exemplo, se um usuário for adicionado ao seu sistema interno, ele será adicionado à sua conta quando entrar no Zendesk. Se um usuário for apagado do sistema interno, ele não poderá mais acessar o Zendesk. No entanto, a conta dele ainda existirá no Zendesk.
Por padrão, os únicos dados do usuário armazenados no Zendesk quando o single sign-on está ativado são o nome e o endereço de e-mail do usuário. O Zendesk não armazena senhas. Por isso, você deve desativar as notificações automáticas por e-mail do Zendesk sobre senhas.
Para melhorar a experiência do cliente, você pode querer armazenar no Zendesk outros dados além do nome e do endereço de e-mail do usuário. Para tal, você pode usar os atributos adicionais de JWT.
Desativação de e-mails de notificação de senhas do Zendesk
Um perfil de usuário do Zendesk é criado para qualquer novo usuário que acesse sua conta do Zendesk por meio de single sign-on com SAML, JWT ou OpenID Connect (OIDC). Como os usuários são autenticados por meio de um IdP com uma senha que não é do Zendesk, o perfil é criado sem uma senha porque eles não precisam entrar diretamente no Zendesk.
Como os novos usuários que entram no Zendesk por meio de SSO são verificados com um IdP, eles não recebem notificações por e-mail para verificar suas respectivas contas. No entanto, ainda é recomendável desativar essas notificações por e-mail automatizadas para evitar que elas sejam enviadas caso o IdP não verifique o usuário com sucesso. No caso do SSO, a verificação do usuário deve sempre ocorrer por meio do IdP.
Como desativar e-mails de notificação de senha
- Na Central de administração, clique em
Pessoas na barra lateral e selecione Configuração > Usuários finais. - Na seção E-mails para a conta, desmarque a opção Também enviar um e-mail de boas-vindas quando um novo usuário é criado por um agente ou administrador.
- Desmarque a opção Permitir que os usuários alterem suas senhas.
Geração de um novo segredo compartilhado
Em alguns casos, por exemplo se o segredo estiver comprometido, talvez você precise emitir um novo segredo JWT compartilhado e informá-lo à equipe de TI ou ao provedor de identidade externo. Você pode gerar um novo segredo JWT compartilhado na Central de administração do Zendesk. Essa ação criará um novo segredo e invalidará o antigo. Informe seu novo segredo compartilhado ao provedor de identidade externo ou à equipe de TI para que a autenticação SSO da conta da Zendesk continue funcionando.
Como gerar um novo segredo compartilhado
- Na Central de administração, clique em Conta na barra lateral e selecione Segurança > Single sign-on.
- Passe o cursor do mouse sobre a configuração com JWT para a qual o novo segredo compartilhado será criado, clique no ícone do menu de opções (
) e selecione Editar. - Role até Segredo compartilhado no final da página de configuração e clique em Redefinir segredo.
Uma mensagem de confirmação será exibida.
- Para confirmar a redefinição, clique em Redefinir segredo.
Você verá um novo Segredo compartilhado em texto sem formatação.
- Clique em Copiar para gerar uma cópia do novo segredo e compartilhá-lo com a sua equipe de TI ou com o provedor de identidade externo.
- Salve suas alterações.
Alternância de métodos de autenticação
se você utilizar um método de SSO de terceiros para criar e autenticar usuários no Zendesk e depois trocar para a autenticação do Zendesk, esses usuários não terão uma senha disponível para o acesso. Para que tenham acesso, peça que esses usuários redefinam suas próprias senhas na página de entrada do Zendesk.
Informações adicionais sobre o JWT
O JWT é um padrão aberto que é conduzido pelo conselho de padrões internacionais IETF e apoiado por grandes empresas do setor de tecnologia (por exemplo, Microsoft, Facebook e Google).
Os elementos constitutivos fundamentais do JWT são componentes muito compreensíveis e o resultado é uma especificação bastante simples, disponível aqui http://tools.ietf.org/html/draft-jones-json-web-token-10. Há muitas implementações de software livre da especificação do JWT que abrangem as tecnologias mais modernas. Isso significa que você pode configurar o single sign-on com JWT sem muitas dificuldades.
Uma informação importante é que a carga do JWT é meramente embutida e assinada e não criptografada. Por isso, não coloque dados confidenciais na tabela de hash. O JWT funciona com a serialização do JSON transmitido para uma cadeia de caracteres. A cadeia de caracteres é codificada na base 64 e cria um HMAC da cadeia de caracteres na base 64 que depende do segredo compartilhado. Isso produz uma assinatura que o lado do destinatário pode usar para validar o usuário.
Planilha de trabalho para implementação técnica
Esta seção se destina à equipe responsável na empresa pelo sistema de autenticação com JWT da empresa. Ela apresenta detalhes sobre a implementação de SSO com JWT do Zendesk.
Tópicos discutidos:
Algoritmo de JWT
Especifique HS256 como o algoritmo JWT no cabeçalho da sua carga de JWT:
{
"typ":"JWT",
"alg":"HS256"
}HS256 quer dizer HMAC SHA 256, um algoritmo de criptografia de 256 bits criado pela Agência de Segurança Nacional dos Estados Unidos.
Ponto de extremidade de JWT do Zendesk
Após a autenticação do usuário, crie a carga JWT e envie uma solicitação POST que contenha a carga de JWT enviada para o seguinte ponto de extremidade do Zendesk:
https://seusubdominio.zendesk.com/access/jwt
A carga deve ter codificação base64 e envio por formulário de um cliente. Enviar a carga com uma solicitação axios, fetch ou AJAX do lado do cliente não funciona, pois a solicitação será bloqueada pela política de mesma origem do cliente. Fazer uma solicitação POST do seu servidor também não funciona, pois os cookies usados para a autenticação no navegador do usuário não são definidos corretamente.
A nova carga de JWT deve ser enviada ao seu subdomínio do Zendesk Support utilizando o protocolo https. Por exemplo:
https://yoursubdomain.zendesk.com/access/jwtNão há suporte para subdomínios com mapeamento do host.
Atributos de JWT
Envie os atributos de JWT usando um hash (Ruby) ou dicionário (Python). O JWT deve ter uma codificação base64. Exemplo usando Ruby:
payload = JWT.encode({
:email => "bob@example.com", :name => "Bob", :iat => Time.now.to_i, :jti => rand(2<<64).to_s
}, "Our shared secret")O Zendesk requer um endereço de e-mail para identificar o usuário de maneira exclusiva. Além dos atributos necessários mostrados na tabela a seguir, você tem a opção de enviar dados de perfil de usuário adicionais. Os dados são sincronizados entre seu sistema de gerenciamento de usuários e o Zendesk Support.
| Atributo | Tipo de dado | Descrição |
|---|---|---|
| iat | data numérica | Emitido no momento em que o token foi gerado, é usado para ajudar a garantir que um determinado token seja usado logo depois de ter sido gerado. O valor deve ser a quantidade de segundos desde a Era UNIX. O Zendesk permite até três minutos de defasagem horária, por isso lembre-se de configurar o protocolo NTP ou similar em seus servidores. |
| jti | cadeia de caracteres | ID do token da web JSON. Uma ID exclusiva do token, usada pelo Zendesk para evitar ataques de reprodução do token. |
| cadeia de caracteres | E-mail do usuário que se conectará, usado para identificar exclusivamente o registro do usuário no Zendesk Support. | |
| name | cadeia de caracteres | O nome desse usuário. O usuário será criado ou atualizado no Zendesk Support de acordo com isso. |
| Atributo | Tipo de dado | Descrição |
|---|---|---|
| external_id | cadeia de caracteres | Caso seus usuários sejam identificados de maneira exclusiva por algo diferente de um endereço de e-mail e seus e-mails estejam sujeitos a alterações, envie a id exclusiva do seu sistema. Especifica a ID como uma cadeia de caracteres. |
| locale (para usuários finais) locale_id (para agentes) |
inteiro | A localidade no Zendesk Support, especificada como um número. |
| organization | cadeia de caracteres | O nome de uma organização à qual o usuário será adicionado. Se a opção Permitir que os usuários pertençam a diversas organizações estiver ativada, outras organizações são anexadas à organização original e são consideradas organizações secundárias. Isso não apaga as adesões existentes. Se você quiser transmitir diversos nomes de organizações ao mesmo tempo, use o atributo organizations_ids. Os nomes das organizações precisam ser transmitidos em uma cadeia de caracteres, separados por vírgulas. |
| organization_id | inteiro | A ID externa da organização na API do Zendesk. Se tanto a organização quanto a organization_id forem fornecidas, a organização será ignorada. Se a opção Permitir que os usuários pertençam a diversas organizações estiver ativada, outras organizações são anexadas à organização original e são consideradas organizações secundárias. Isso não apaga as adesões existentes. Se você quiser transmitir diversas IDs de organizações ao mesmo tempo, use o atributo organization_ids. As IDs das organizações precisam ser transmitidas em uma cadeia de caracteres, separadas por vírgulas. |
| phone | cadeia de caracteres | Um número de telefone, especificado em uma cadeia de caracteres. O número de telefone deve manter conformidade com o plano de numeração de telefones internacional E.164. Por exemplo: +15551234567. Os números E.164 são números internacionais com um prefixo de discagem do país, geralmente um código de área e um número de assinante. Um número de telefone E.164 válido precisa incluir um código de ligação do país. |
| tags | matriz | Essa é uma matriz de tags JSON a serem definidas no usuário. Essas tags substituirão todas as demais tags existentes no perfil do usuário. |
| remote_photo_url | cadeia de caracteres | URL para uma foto a ser definida no perfil do usuário. |
| role | cadeia de caracteres | A função do usuário. Esse valor pode ser definido como end_user, agent ou admin. O padrão é end_user. Se a função do usuário for diferente no Zendesk Support, a função será alterada no Zendesk Support. |
| custom_role_id | inteiro | Aplicável apenas se a função do usuário for de agente. |
| user_fields | objeto |
Um hash de JSON da chave de campo de usuário personalizado e os valores a serem definidos no usuário. O campo de usuário personalizado deve existir para definir o valor do campo. Cada campo de usuário personalizado é identificado por sua chave de campo, encontrada nas configurações do administrador dos campos de usuário. O formato dos valores de data é aaaa-mm-dd. Se uma chave ou valor de campo de usuário personalizado for inválido, atualizar esse campo resultará em erro e o usuário ainda poderá acessar com êxito. Para obter mais informações sobre os campos de usuário personalizados, consulte Inclusão de campos personalizados aos usuários.
Observação: enviar valores null no atributo user_fields remove quaisquer valores existentes nos campos correspondentes.
|
Parâmetro da URL de acesso remoto (return_to)
Você tem a opção de transmitir ou não o parâmetro return_to, mas nós recomendamos que você o faça para oferecer uma experiência melhor para o usuário. Quando o Zendesk redireciona um usuário para sua página de acesso remoto, ele passa um parâmetro de URL return_to. O parâmetro contém a página à qual o Zendesk retornará o usuário depois que o sistema autenticar esse usuário. Anexe o nome e o valor do parâmetro ao ponto de extremidade de JWT do Zendesk.
Por exemplo, suponha que um agente que saiu do sistema clique no link a seguir para abrir um ticket no Support: https://minhaempresa.zendesk.com/tickets/1232. O fluxo é o seguinte:
- Ao clicar, o Zendesk redireciona o usuário para sua URL de acesso remoto e anexa este parâmetro
return_toà URL:https://mycompany.com/zendesk/sso?return_to=https://mycompany.zendesk.com/tickets/123 - Seu sistema de autenticação recebe o parâmetro
return_toda URL e, após a autenticação do usuário, anexa-o ao ponto de extremidade de JWT do Zendesk ou o adiciona ao corpo da solicitação.. Por exemplo:https://mycompany.zendesk.com/access/jwt?&return_to=https://mycompany.zendesk.com/tickets/123 - O Zendesk usa o parâmetro para abrir a página do ticket para o agente.
O parâmetro return_to é uma URL absoluta para a interface do agente e uma relativa para a central de ajuda.
return_to contiver seus próprios parâmetros de URL, certifique-se de que seu URI de script codifique todo o valor return_to ao enviar o token JWT. Tratamento de erro
Se o Zendesk encontrar um erro durante o processamento de uma solicitação de acesso com JWT, ele enviará uma mensagem explicando o problema. Se você especificou uma URL de saída remota quando configurou a integração com JWT, ela redirecionará para essa URL e transmitirá uma “mensagem” e um parâmetro “kind”. Em caso de erro, o parâmetro “kind” sempre terá o valor “error” (erro). A Zendesk recomenda que você tenha uma URL de saída remota, além das mensagens de acesso do Zendesk, junto com o tipo. A maioria dos erros que ocorrem são aqueles que você tentará corrigir. Exemplos incluem a dessincronização de relógio, o alcance dos limites de taxa, os tokens inválidos etc.
Exemplos de envio por formulário
A carga de JWT deve ser enviada por meio de um formulário de um navegador para o seguinte ponto de extremidade do Zendesk:
https://yoursubdomain.zendesk.com/access/jwtO Zendesk fornece uma série de exemplos para diversas pilhas de tecnologia no repositório de SSO com JWT da Zendesk no GitHub. Você deve enviar a carga de JWT por meio de um formulário de um navegador para garantir que os cookies sejam definidos corretamente no navegador e que a solicitação não seja bloqueada pelo mecanismo CORS.
Resposta
A resposta deve ser HTML com um status 200 OK. O formato da resposta é o seguinte:
<html><body>You are being <a href="">redirected</a>.</body></html>Se href corresponder ao valor return_to, então o usuário foi autenticado com êxito e os cookies devem ser definidos. Se href começar com https://SUBDOMAIN.zendesk.com/access/unauthenticated, então o Zendesk não conseguiu autenticar o usuário.
Exemplos de geração de JWT
A codificação prática do JWT é muito direta e a maioria das linguagens modernas tem bibliotecas disponíveis com suporte. O Zendesk fornece uma série de exemplos para diversas pilhas no repositório de SSO com JWT no GitHub:
O código de geração JWT é para a implementação do servidor. Você pode passar o JWT gerado de volta para a página de acesso e, então, iniciar o envio do formulário do navegador.
Se você implementou o JWT em qualquer outra pilha, gostaríamos de incluir seu exemplo. Comente este artigo para compartilhar o que você implementou.
Caso você execute IIS/AD e não queira desenvolver sua própria solução .NET, nós fornecemos implementação total em ASP clássico, que precisará apenas que você ajuste algumas variáveis. Baixe o script de autenticação de ASP no GitHub.