Ativação de single sign-on com JWT (Token da web JSON)

Caminho rápido: Central de administração > Conta > Segurança > Single sign-on

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 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.

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 se baseia na tecnologia Token da web JSON (JWT), que protege a troca de dados de autenticação de usuários.

Este artigo abrange as seções a seguir:

• 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:

• Planilha de trabalho para implementação técnica

Artigos relacionados:

• Opções de single sign-on (SSO) no Zendesk
• Uso de SAML para single sign-on

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:

1. Um usuário não autenticado acessa a URL de seu Zendesk Support. Exemplo: https://seusubdominio.zendesk.com/.
2. O mecanismo de SSO do Zendesk reconhece que o SSO está ativado e que o usuário não está autenticado.
3. A Zendesk redireciona o usuário para a página de entrada remota de sua organização. Exemplo: https://minhaempresa.com/zendesk/sso.
4. Um script no servidor remoto autentica o usuário usando o processo de acesso próprio de sua empresa.
5. O sistema de autenticação cria uma solicitação JWT que contém os dados do usuário relevantes.
6. 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

7. 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 responsável em sua empresa pelo sistema de autenticação com JWT (em geral, uma equipe do departamento de TI) e solicite estas informações:

• 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.

Consulte a equipe para confirmar que o tráfego associado ao Zendesk é via HTTPS e não HTTP.

Depois, insira as informações no Support para ativar o single sign-on. Consulte Ativação de SSO com JWT.

A equipe de TI poderá exigir informações adicionais da Zendesk para configurar a implementação do SAML. Indique à equipe a Planilha de implementação técnica deste artigo.

Ativação de SSO com JWT

Você pode ativar o single sign-on com JWT apenas para usuários finais, apenas para membros da equipe (agentes e administradores) ou para os dois grupos. Se você estiver usando JWT e SAML, deve selecionar um deles como o método de autenticação principal. Ao acessar o Zendesk, os usuários serão redirecionados para sua página de entrada principal. Os usuários podem acessar o sistema com o método secundário acessando a página de entrada secundária. Para obter detalhes, consulte Uso de diferentes SSOs (single sign-on) com SAML e JWT para agentes e usuários finais.

Você deve entrar no Zendesk Support como administrador para ativar o single sign-on com JWT.

Como ativar o single sign-on com JWT

1. Na Central de administração, clique no ícone Conta () na barra lateral e selecione Segurança > Single sign-on.
2. Em Token da web JSON, clique em Configure.
3. 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.

4. Em URL de saída remota, insira a URL à qual o Zendesk retornará os usuários depois que eles saírem.

   O Zendesk adiciona automaticamente os parâmetros email, external_id e brand_id à URL. 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/.
5. (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.

6. Se você usar external_IDs para seus usuários, pode atualizá-las no Zendesk Support selecionando Ativado em Atualizar IDs externas?.
7. Informe o Segredo compartilhado à sua equipe de TI. A equipe precisará dele na 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.
8. Definida a configuração de SSO com JWT, clique em Ativada para poder atribuir essa opção a usuários.
9. Clique em Salvar.

Atribuição de SSO com JWT a usuários

Feita a configuração da opção de SSO com JWT, atribua essa opção de SSO para usuários finais, membros da equipe ou ambos.

1. Abra as configurações de segurança para membros da equipe ou usuários finais.
   • Na Central de administração, clique no ícone Conta () na barra lateral e selecione Segurança > Autenticação de membro da equipe.
   • Na Central de administração, clique no ícone Conta () na barra lateral e selecione Segurança > Autenticação de usuário final.
2. Selecione Token da web JSON como a opção Single sign-on (SSO) na seção Autenticação externa.
3. Se desejar que todos os usuários usem o método de single sign-on, desmarque a opção Autenticação do Zendesk.

   As senhas do Zendesk serão permanentemente apagadas da conta em até 24 horas.

4. Se você desativou as senhas do Zendesk, selecione a opção de menu que especifica se o acesso à conta será concedido apenas ao responsável pela conta ou aos administradores (incluindo o responsável pela conta) caso o provedor de acesso fique inativo.

   

   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.

5. 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. Consulte Obtenção de dados do usuário adicionais.

Geração de um novo segredo compartilhado

Em alguns casos, talvez você precise emitir um novo segredo JWT compartilhado e informá-lo à equipe de TI ou ao provedor de identidade externo. Por exemplo, se o segredo for comprometido. 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.

Importante: os usuários não poderão se autenticar usando SSO com JWT até que o novo segredo seja inserido. Assegure-se de que seus usuários tenham um método de autenticação de reserva durante esse período.

Como gerar um novo segredo compartilhado:

1. Na Central de administração, clique no ícone Conta () na barra lateral e selecione Segurança > Single sign-on.
2. Em Token da web JSON, clique em Editar.

   Sua configuração de Token da web JSON é exibida.

3. Role até Segredo compartilhado no final da página de configuração e clique em Redefinir segredo.

   

   Uma mensagem de confirmação será exibida.

   

4. Para confirmar a redefinição, clique em Redefinir segredo.

   Você verá um novo Segredo compartilhado em texto sem formatação.

   

5. 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.
6. Salve suas alterações.

Alternância de métodos de autenticação

Importante: 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. Para que tenham acesso, peça a esses usuários para redefinirem sua senha na página de entrada do Zendesk.

Informações adicionais sobre o JWT

O JWT é um padrão aberto recente 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. Em seguida, ele codifica a cadeia de caracteres 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.

Observação: se você tiver feito uma atualização de uma versão anterior do SSO do Zendesk (conhecido como Autenticação remota do Zendesk) para o JWT, pode manter várias implementações de SSO ativadas ao mesmo tempo. O Zendesk reconhece se a solicitação se destina ao JWT ou a outro tipo de SSO e lida com ela de maneira apropriada. Isso significa que você pode ativar e testar o JWT antes de desativar sua implementação de SSO anterior.

Tópicos discutidos:

• Algoritmo de JWT
• Ponto de extremidade de JWT do Zendesk
• Atributos de JWT
• Parâmetro da URL de acesso remoto (return_to)
• Tratamento de erro
• Exemplos de código de implementação de JWT

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.

Observação: o Zendesk não oferece suporte aos algoritmos JWT RS256 e ES256.

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 => "[e-mail]", :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.

Tabela 1. Atributos com suporte

Atributo	Obrigatório	Descrição
iat	Sim	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	Sim	ID do token da web JSON. Uma ID exclusiva do token, usada pelo Zendesk para evitar ataques de reprodução do token.
email	Sim	E-mail do usuário que se conectará, usado para identificar exclusivamente o registro do usuário no Zendesk Support.
name	Sim	O nome desse usuário. O usuário será criado ou atualizado no Zendesk Support de acordo com isso.
external_id	Não	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)	Não	A localidade no Zendesk Support, especificada como um número.
organization	Não	O nome de uma organização à qual o usuário será adicionado. Observação: 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 organizações ao mesmo tempo, use o atributo organizations_ids. As organizações precisam ser transmitidas em uma cadeia de caracteres, separadas por vírgulas.
organization_id	Não	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. Observação: 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.
phone	Não	Um número de telefone, especificado em uma cadeia de caracteres.
tags	Não	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	Não	URL para uma foto a ser definida no perfil do usuário.
role	Não	A função do usuário. Pode ser definida como "user", "agent" ou "admin". O padrão é "user". Se a função do usuário for diferente no Zendesk Support, a função será alterada no Zendesk Support.
custom_role_id	Não	Aplicável apenas se a função do usuário for de agente.
user_fields	Não	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)

Quando o Zendesk redireciona um usuário para sua página de acesso remoto, ele também envia 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 parâmetro (nome e valor) 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:

1. 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

2. Seu sistema de autenticação recebe o parâmetro return_to (nome e valor) da 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

3. 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.

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.

Observação: se o endereço 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: dessincronização de relógio, alcance dos limites de taxa, 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:

• https://github.com/zendesk/zendesk_jwt_sso_examples

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 desta página no Github: https://github.com/zendesk/zendesk_jwt_sso_examples/tree/master/bundles.