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 até duas 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. 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. 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 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 até duas 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. 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.
- Definida a configuração de SSO com JWT, clique em Ativada para poder atribuir essa opção a usuários.
- Clique em Salvar.
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
- Se você está atribuindo uma configuração de SSO a membros da equipe, selecione Autenticação externa para exibir as opções de autenticação.
Essas opções já são exibidas para usuários finais.
- Clique na opção Single sign-on (SSO) na seção Autenticação externa e selecione os nomes das configurações de SSO que 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. Para exigir que os usuários acessem usando o método de SSO principal, consulte Como permitir apenas a entrada usando a autenticação de SSO.
- Clique em Salvar.
Como permitir apenas a entrada usando a autenticação de SSO
- 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
- Em Como os usuários finais ou membros da equipe entram no sistema, selecione Redirecionar para o SSO e clique em Salvar.
- Na Central de administração, clique em Conta na barra lateral e selecione Segurança > Avançado.
- Clique na aba Autenticação e selecione uma opção de Contorno do SSO.
Você pode escolher apenas Responsável pela conta ou todos os Administradores (incluindo o Responsável pela conta) para receberem acesso à conta se o provedor de acesso externo sair do ar.
Para ter acesso, o responsável pela conta ou um administrador solicita o recebimento de um e-mail contendo um link de acesso único. Ao clicar no link, a pessoa tem acesso à conta. Não é necessária uma senha. Consulte Acesso à conta se as senhas estiverem desativadas.
- 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 são sincronizadas com sua conta do Zendesk. Por exemplo, se um usuário for adicionado em seu sistema interno, ele também será adicionado automaticamente à sua conta do Zendesk. Se um usuário for apagado do seu sistema interno, ele não conseguirá mais entrar no Zendesk (mas a conta dele continuará existindo 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. Consulte Desativação de e-mails de notificação de senhas do Zendesk.
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
Quando um usuário é adicionado a uma conta do Zendesk, uma notificação automática por e-mail pode ser enviada ao usuário, pedindo que ele confirme seu endereço de e-mail e crie um nome de usuário e uma senha.
Um perfil de usuário do Zendesk é criado para qualquer novo usuário que acesse sua conta do Zendesk com SAML ou JWT. Como eles são autenticados com uma senha que não é do Zendesk, o perfil é criado sem uma senha porque eles não precisam entrar no Zendesk. No entanto, por padrão, cada novo usuário recebe um e-mail notificando-o para confirmar o endereço de e-mail e criar um nome de usuário e uma 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 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
É importante ressaltar que se você usar um método 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. Peça que esses usuários redefinam sua senha na página de entrada do Zendesk para que tenham acesso.
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, redirecione o usuário junto com a carga de JWT para o seguinte ponto de extremidade do Zendesk:
https://seusubdominio.zendesk.com/access/jwt
A carga deve ser codificada em base64 e anexada à URL como uma cadeia de caracteres de consulta.
A nova carga de JWT deve ser enviada ao seu subdomínio do Zendesk Support utilizando o protocolo https. Exemplo:
https://yoursubdmain.zendesk.com/access/jwt?jwt={payload} Não há suporte para subdomínios com mapeamento do host.
Atributos de JWT
Envie atributos para o Zendesk como um hash codificado em base64 (Ruby) ou dicionário (Python). 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 abaixo, 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 | Descrição |
|---|---|
| iat | 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 | ID do token da web JSON. Uma ID exclusiva do token, usada pelo Zendesk para evitar ataques de reprodução do token. |
| E-mail do usuário que se conectará, usado para identificar exclusivamente o registro do usuário no Zendesk Support. | |
| name | O nome desse usuário. O usuário será criado ou atualizado no Zendesk Support de acordo com isso. |
| Atributo | Descrição |
|---|---|
| external_id | 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) |
A localidade no Zendesk Support, especificada como um número. |
| organization | 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 | 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 | Um número de telefone, especificado em uma cadeia de caracteres. |
| tags | 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 | URL para uma foto a ser definida no perfil do usuário. |
| role | 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 | Aplicável apenas se a função do usuário for de agente. |
| user_fields |
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. Exemplo:https://mycompany.zendesk.com/access/jwt?jwt=payload&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 código de implementação de JWT
A implementaçã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 seguinte repositório de SSO do JWT no GitHub:
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.
0 Comentários
Por favor, entre para comentar.