Activación del inicio de sesión único con JWT (Token Web JSON)

Acceso rápido: Centro de administración > Cuenta > Seguridad > Inicio de sesión único

El inicio de sesión único es un mecanismo que permite autenticar a los usuarios en el sistema y luego informar a Zendesk que el usuario ha sido autenticado. Si se usa el inicio de sesión único con JWT, el usuario es verificado de manera automática con el proveedor de identidad en el momento de iniciar sesión. El usuario entonces puede acceder a Zendesk sin que se le solicite ingresar credenciales de inicio de sesión separadas.

El núcleo de un inicio de sesión único es un mecanismo de seguridad que permite que Zendesk confíe en las solicitudes de inicio de sesión que recibe de sus sistemas. Zendesk solo brinda acceso a los usuarios que usted ha autenticado. El SSO de Zendesk depende de una tecnología denominada Token Web JSON (JWT) que garantiza la seguridad durante el intercambio de datos de autenticación de usuarios.

Este artículo contiene las siguientes secciones:

• Cómo funciona el inicio de sesión único con JWT para Zendesk
• Requisitos para activar el inicio de sesión único con JWT
• Activar el inicio de sesión único con JWT
• Asignar inicio de sesión único con JWT a los usuarios
• Administrar a los usuarios en Zendesk después de activar el inicio de sesión único con JWT
• Generar un nuevo secreto compartido
• Cambiar de método de autenticación
• Información adicional sobre JWT

El equipo de TI de una compañía es normalmente responsable de la configuración y administración del sistema de autenticación JWT de la compañía. Su rol incluye implementar SSO para Zendesk en el sistema. Remita al equipo al siguiente tema en este artículo:

• Hoja de trabajo de implementación técnica

Artículos relacionados:

• Opciones de inicio de sesión único (SSO) en Zendesk
• Uso de SAML para el inicio de sesión único

Cómo funciona el inicio de sesión único con JWT para Zendesk

Una vez activado el inicio de sesión único, las solicitudes de inicio de sesión son dirigidas a una página de inicio de sesión externa a Zendesk Support.

Pasos del proceso de autenticación del inicio de sesión único con JWT:

1. Un usuario no autenticado va al URL de su cuenta de Zendesk Support. Ejemplo: https://susubdominio.zendesk.com/.
2. El mecanismo SSO de Zendesk reconoce que SSO está activado y que el usuario no está autenticado.
3. Zendesk redirige al usuario a la página de inicio de sesión remoto de su organización. Ejemplo: https://micompañía.com/zendesk/sso.
4. Un script en el servidor remoto autentica al usuario usando el proceso de autenticación patentado de su compañía.
5. El sistema de autenticación crea una solicitud JWT que contiene los datos de usuario pertinentes.
6. El sistema de autenticación redirige al usuario al siguiente extremo de Zendesk con la carga de JWT:

   https://susubdominio.zendesk.com/access/jwt

7. Zendesk analiza los detalles del usuario en la carga JWT y luego otorga una sesión al usuario.

Como se puede ver, este proceso depende de los redireccionamientos del navegador y el paso de mensajes firmados usando JWT. Los redireccionamientos se realizan en su totalidad en el navegador y no hay comunicación directa entre Zendesk y sus sistemas, de manera que puede guardar sus scripts de autenticación de manera segura detrás del firewall de su compañía.

Requisitos para activar el inicio de sesión único con JWT

Reúnase con el equipo responsable del sistema de autenticación JWT dentro de su compañía (por lo general un equipo dentro del departamento de TI) y solicite la siguiente información:

• El URL de inicio de sesión remoto donde se debe redirigir a los usuarios de Zendesk cuando intentan acceder a Zendesk
• (Opcional) El URL de cierre de sesión remoto donde Zendesk puede redirigir a los usuarios después de que cierran sesión en Zendesk
• (Opcional) Una lista de intervalos de IP para redirigir a los usuarios a la opción de inicio de sesión que corresponda. Los usuarios que hacen solicitudes desde los intervalos de IP especificados son redirigidos al formulario de inicio de sesión de autenticación remota con JWT. Los usuarios que hacen solicitudes desde direcciones IP fuera de los intervalos son redirigidos al formulario de inicio de sesión normal de Zendesk. Si no se especifica un intervalo, todos los usuarios son redirigidos al formulario de inicio de sesión de autenticación remota.

Confirme con el equipo que todo tráfico hacia Zendesk sea dirigido a través de HTTPS, y no de HTTP.

A continuación, ingrese la información en Support para activar el inicio de sesión único. Consulte Activar el inicio de sesión único con JWT.

Es posible que el equipo de TI necesite más información de Zendesk para poder configurar la implementación de SAML. Remítalos a la Hoja de trabajo de implementación técnica en este artículo.

Activar el inicio de sesión único con JWT

El inicio de sesión único con JWT se puede activar solo para usuarios finales, para integrantes del equipo (agentes y administradores), o para ambos grupos. Si utiliza JWT y SAML, debe seleccionar uno como el método de autenticación principal. Cuando inicien sesión en Zendesk, los usuarios serán redirigidos a la página de inicio de sesión principal. Si desean iniciar sesión con el método secundario, pueden ir a la página de inicio de sesión secundaria. Si desea más detalles, consulte Uso de inicio de sesión único distinto con SAML y con JWT para agentes y usuarios finales.

Debe iniciar sesión en Zendesk Support como administrador para activar el inicio de sesión único con JWT.

Para activar el inicio de sesión único con JWT

1. En el Centro de administración, haga clic en el icono Cuenta () en la barra lateral y luego seleccione Seguridad > Inicio de sesión único.
2. Para el token Web JSON, haga clic en Configurar.
3. Para URL de inicio de sesión remoto, ingrese el URL donde se debe redirigir a los usuarios cuando intentan acceder al URL de su cuenta de Zendesk.

   Zendesk agrega automáticamente un parámetro brand_id al URL. Esta es la marca de Zendesk Support donde se encontraba el usuario cuando intentó iniciar sesión.

4. Para URL de cierre de sesión remoto, ingrese el URL al que Zendesk redirigirá a los usuarios después de que cierran sesión.

   Zendesk agrega automáticamente los parámetros email, external_id y brand_id al URL. Si prefiere no tener información del correo electrónico y de la ID externa en el URL, use parámetros en blanco en el URL de cierre de sesión. Ejemplo:

   https://www.xyz.com/user/signout/?email=&external_id=

   Nota: Si está usando una aplicación Ember.js, debe modificar el URL de cierre de sesión para poder usar parámetros en blanco antes del hash. Por ejemplo, https://somedomain.com/?brand_id=&return_to=&email=#/zendesk-login/.
5. (Opcional) Para Intervalos de IP, ingrese una lista de intervalos de IP si desea redirigir a los usuarios a la opción de inicio de sesión que corresponda.

   Los usuarios que hacen solicitudes desde los intervalos de IP especificados son redirigidos al formulario de inicio de sesión de autenticación con JWT. Los usuarios que hacen solicitudes desde direcciones IP fuera de los intervalos son redirigidos al formulario de inicio de sesión normal de Zendesk. No especifique un intervalo si desea que todos los usuarios sean redirigidos al formulario de inicio de sesión de autenticación con JWT.

6. Si utiliza ID externas para los usuarios, seleccione Activar en relación con ¿Permitir la actualización de id externas? para actualizarlas en Zendesk Support.
7. Proporcione el secreto compartido al equipo de TI. Lo necesitarán para su implementación de JWT.
   Importante: Guarde el secreto compartido en un lugar seguro. Si se ve comprometido, todos los datos de su cuenta de Support estarán en peligro.
8. Una vez establecida la configuración del inicio de sesión único con JWT, haga clic en Activado para asignar esta opción a los usuarios.
9. Haga clic en Guardar.

Asignar inicio de sesión único con JWT a los usuarios

Después de configurar la opción de SSO con JWT, asigne esta opción de SSO a los usuarios finales, a los integrantes del equipo o a ambos grupos.

1. Abra la configuración de seguridad para los integrantes de su equipo o usuarios finales.
   • En el Centro de administración, haga clic en el icono Cuenta () en la barra lateral y luego seleccione Seguridad > Autenticación de integrantes del equipo.
   • En el Centro de administración, haga clic en el icono Cuenta () en la barra lateral y luego seleccione Seguridad > Autenticación de usuarios finales.
2. Seleccione Token Web JSON como la opción Inicio de sesión único (SSO) en la sección Autenticación externa.
3. Si desea que todos los usuarios usen un método de inicio de sesión único solamente, quite la marca de la opción Autenticación de Zendesk.

   Las contraseñas de Zendesk se borrarán para siempre de la cuenta en 24 horas.

4. Si desactivó las contraseñas de Zendesk, seleccione la opción de menú que especifica si solo el dueño de la cuenta o los administradores (que incluye al dueño de la cuenta) pueden obtener acceso a la cuenta si un proveedor de servicios de inicio de sesión deja de funcionar.

   

   Para obtener acceso, el dueño de la cuenta o un administrador solicita que le envíen un correo electrónico con un vínculo de acceso que solo se puede usar una vez. Si hace clic en el vínculo, la persona obtiene acceso a la cuenta. La contraseña no es necesaria. Consulte Acceder a la cuenta si las contraseñas están desactivadas.

5. Haga clic en Guardar.

Administrar a los usuarios en Zendesk después de activar el inicio de sesión único con JWT

Después de activar el inicio de sesión único con JWT en Zendesk, los cambios que se realicen en los usuarios fuera de Zendesk se sincronizarán con la cuenta de Zendesk. Por ejemplo, si se agrega un usuario a su sistema interno, el usuario es agregado automáticamente a la cuenta de Zendesk. Si se borra a un usuario del sistema interno, el usuario ya no podrá iniciar sesión en Zendesk; sin embargo su cuenta seguirá existiendo en Zendesk.

De manera predeterminada, los únicos datos de usuario que se almacenan en Zendesk cuando está activado el inicio de sesión único son el nombre y la dirección de correo electrónico del usuario. Zendesk no almacena las contraseñas. Por lo tanto, se deben desactivar todas las notificaciones por correo electrónico automatizadas de Zendesk sobre las contraseñas. Consulte Desactivar las notificaciones por correo electrónico sobre contraseñas de Zendesk.

Para ofrecer una mejor experiencia a los clientes, podría ser conveniente almacenar más que el nombre y la dirección de correo electrónico del usuario en Zendesk. Consulte Obtener datos adicionales del usuario.

Generar un nuevo secreto compartido

Es posible que en algunos casos tenga que emitir un nuevo secreto compartido de JWT y dárselo a su equipo de TI o proveedor de identidad externo. Uno de esos casos es si el secreto se ve comprometido. Puede generar un nuevo secreto compartido de JWT desde el Centro de administración de Zendesk. Esta acción hará que se cree un secreto nuevo y dejará sin validez el anterior. Tendrá que informar a su equipo de TI o proveedor de identidad externo sobre su nuevo secreto compartido para que la autenticación de la cuenta de SSO de Zendesk siga funcionando.

Importante: Los usuarios no podrán autenticarse usando el inicio de sesión único con JWT hasta que el nuevo secreto esté implementado. Asegúrese de que los usuarios cuenten con un método de autenticación de respaldo durante este tiempo.

Para generar un nuevo secreto compartido:

1. En el Centro de administración, haga clic en el icono Cuenta () en la barra lateral y luego seleccione Seguridad > Inicio de sesión único.
2. Para el token web JSON, haga clic en Editar.

   Aparece la configuración del token Web JSON actual.

3. Desplácese a Secreto compartido en la parte de abajo de la página de configuración y haga clic en Restablecer secreto.

   

   Aparece un mensaje de confirmación.

   

4. Haga clic en Restablecer secreto para confirmar el restablecimiento.

   Debería ver un nuevo Secreto compartido en texto sin formato.

   

5. Haga clic en Copiar para hacer una copia del nuevo secreto compartido y proporcióneselo al equipo de TI o al proveedor de identidad externo.
6. Guarde los cambios.

Cambiar de método de autenticación

Importante: Si se utiliza un método SSO de terceros para crear y autenticar a los usuarios en Zendesk, y luego se cambia a la autenticación de Zendesk, estos usuarios no tendrán una contraseña disponible para iniciar sesión. Para obtener acceso, solicite a dichos usuarios que restablezcan sus contraseñas en la página de inicio de sesión de Zendesk.

Información adicional sobre JWT

JWT es un estándar abierto reciente que está siendo liderado por el organismo internacional de estándares IETF y patrocinado por empresas de alto nivel del sector tecnológico (por ejemplo, Microsoft, Facebook y Google).

Los componentes básicos de JWT son bien comprendidos y el resultado es una especificación bastante simple, que se encuentra aquí http://tools.ietf.org/html/draft-jones-json-web-token-10. Hay varias implementaciones de fuente abierta de la especificación JWT que abarcan la mayoría de las tecnologías modernas. Esto quiere decir que el inicio de sesión único con JWT se puede configurar sin mayores dificultades.

Una cosa que debe tener en cuenta es que la carga de JWT solo está codificada y firmada, no encriptada, de manera que no ponga información confidencial en la tabla hash. JWT funciona mediante la serialización de JSON que se transmite a una cadena. Luego, codifica dicha cadena en base 64 y, a continuación, hace un HMAC de la cadena en base 64 que depende del secreto compartido. Esto produce una firma que el lado del destinatario puede usar para validar al usuario.

Hoja de trabajo de implementación técnica

Esta sección es para el equipo dentro de la compañía que es responsable del sistema de autenticación JWT de la compañía. Proporciona detalles sobre la implementación del inicio de sesión único con JWT de Zendesk.

Nota: Si está actualizando de una versión anterior del SSO de Zendesk (conocido como Autenticación remota de Zendesk) a JWT, puede tener varias implementaciones de SSO activas al mismo tiempo. Zendesk reconoce si una solicitud está destinada a JWT o a otro tipo de SSO y procesará la solicitud como corresponde. Esto quiere decir que puede activar y probar JWT antes de desactivar la implementación de SSO anterior.

Temas que se tratan:

• Algoritmo de JWT
• Extremo de JWT de Zendesk
• Atributos de JWT
• Parámetro (return_to) del URL de inicio de sesión remoto
• Manejo de errores
• Ejemplos de código de implementación de JWT

Algoritmo de JWT

Especifique HS256 como el algoritmo JWT en el encabezado de la carga JWT:

{
  "typ":"JWT",
  "alg":"HS256"
}

HS256 significa HMAC SHA 256, un algoritmo de encriptación de 256 bits creado por la Agencia de Seguridad Nacional de Estados Unidos. .

Nota: Zendesk no admite los algoritmos JWT RS256 y ES256.

Extremo de JWT de Zendesk

Después de autenticar correctamente al usuario, rediríjalo junto con la carga de JWT al siguiente extremo de Zendesk:

https://susubdominio.zendesk.com/access/jwt

La carga debe tener una codificación en base64 y debe agregarse al URL como una cadena de consulta.

La carga JWT debe enviarse al subdominio de su cuenta de Zendesk Support usando el protocolo https. Ejemplo:

https://yoursubdmain.zendesk.com/access/jwt?jwt={payload} 

No se admiten los subdominios con mapeo de host.

Atributos de JWT

Envíe los atributos a Zendesk como un hash codificado en base64 (Ruby) o diccionario (Python). Ejemplo usando Ruby:

payload = JWT.encode({
   :email => "[e-mail]", :name => "Bob", :iat => Time.now.to_i, :jti => rand(2<<64).to_s
}, "Our shared secret")

Zendesk necesita una dirección de correo electrónico para poder identificar de manera inequívoca al usuario. Además de los atributos necesarios que se indican en la tabla a continuación, puede, si lo desea, enviar datos adicionales del perfil del usuario. Estos datos se sincronizan en el sistema de administración de usuarios y en Zendesk Support.

Tabla 1. Atributos admitidos

Atributo	Requerido	Descripción
iat	Sí	Emitido. Hora a la que fue emitido el token, se usa para ayudar a garantizar que un token en particular se use poco después de ser generado. El valor debe ser el número de segundos desde la época UNIX. Zendesk permite un sesgo del reloj de hasta tres minutos, de modo que asegúrese de configurar NTP o similar en sus servidores.
jti	Sí	ID del Token Web JSON. Una ID única para el token, que Zendesk utiliza para evitar ataques de reproducción de token.
email	Sí	El correo electrónico del usuario que inicia sesión, que se usa para identificar de forma exclusiva el registro del usuario en Zendesk Support.
name	Sí	El nombre de este usuario. El usuario en Zendesk Support se creará y actualizará conforme a esto.
external_id	No	Si a los usuarios se les identifica de forma exclusiva por alguna otra cosa que no sea su dirección de correo electrónico, y sus direcciones de correo electrónico pueden cambiar, envíe la ID única desde su sistema. Especifique la ID como una cadena.
locale (para usuarios finales) locale_id (para agentes)	No	La configuración regional en Zendesk Support, especificada como un número.
organization	No	El nombre de una organización a la cual desea agregar el usuario. Nota: Si la opción Permitir que los usuarios pertenezcan a varias organizaciones está activada, las organizaciones adicionales anexan la organización original, y son consideradas organizaciones secundarias. Esto no borra las afiliaciones existentes. Si desea pasar varias organizaciones al mismo tiempo, mejor use el atributo organization_ids. Las organizaciones se deben pasar en una cadena, separadas por comas.
organization_id	No	La ID externa de la organización en la API de Zendesk. Si se proporcionan los atributos organization y organization_id, se ignora organization. Nota: Si la opción Permitir que los usuarios pertenezcan a varias organizaciones está activada, las organizaciones adicionales anexan la organización original, y son consideradas organizaciones secundarias. Esto no borra las afiliaciones existentes.
phone	No	Un número de teléfono, especificado como una cadena.
tags	No	Una matriz JSON de etiquetas para configurar en el usuario. Estas etiquetas reemplazarán todas las otras etiquetas que existan en el perfil del usuario.
remote_photo_url	No	URL de una foto para configurar en el perfil del usuario.
role	No	El rol del usuario. Puede configurarse en "usuario", "agente" o "administrador". El valor predeterminado es "usuario". Si el rol del usuario es diferente al de Zendesk Support, el rol se cambia en Zendesk Support.
custom_role_id	No	Solo se aplica si el rol del usuario es agente.
user_fields	No	Un hash JSON de clave del campo de usuario personalizado y valores para configurar el usuario. El campo de usuario personalizado debe existir para poder establecer el valor del campo. Cada campo de usuario personalizado se identifica por su clave de campo que se encuentra en la configuración de administración de los campos de usuario. El formato de los valores de fecha es aaaa-mm-dd. Si una clave de campo de usuario personalizado o de valor no es válida, la actualización del campo fallará de manera silenciosa y el usuario iniciará sesión sin problemas. Si desea más información acerca de los campos de usuario personalizados, consulte Adición de campos personalizados a usuarios. Nota: Si se envían valores null en el atributo user_fields se eliminarán los valores existentes en los campos correspondientes.

Parámetro (return_to) del URL de inicio de sesión remoto

Cuando Zendesk redirige al usuario a la página de inicio de sesión remoto, también pasa un parámetro return_to de URL. El parámetro contiene la página a la cual Zendesk redirigirá al usuario después de que el sistema lo haya autenticado. Anexe el parámetro (nombre y valor) al extremo de JWT de Zendesk.

Por ejemplo, si un agente que ha cerrado sesión hace clic en el siguiente vínculo para abrir un ticket en Support: https://mycompany.zendesk.com/tickets/1232. El flujo es como sigue:

1. Cuando se hace clic, Zendesk redirige al usuario al URL de inicio de sesión remoto y anexa el siguiente parámetro return_to al URL: 

   https://mycompany.com/zendesk/sso?return_to=https://mycompany.zendesk.com/tickets/123

2. El sistema de autenticación toma el parámetro return_to (nombre y valor) del URL y, después de hacer una autenticación correcta del usuario, lo anexa al extremo de JWT de Zendesk. Ejemplo:

   https://mycompany.zendesk.com/access/jwt?jwt=payload&return_to=https://mycompany.zendesk.com/tickets/123

3. Zendesk utiliza el parámetro para abrir la página del ticket para el agente.

El parámetro return_to es un URL absoluto para la interfaz de agente, y uno relativo para el centro de ayuda.

El paso del parámetro return_to es opcional, pero se recomienda para propiciar una experiencia óptima al usuario.

Nota: Si la dirección return_to contiene sus propios parámetros de URL, asegúrese de que su script codifique con URI todo el valor return_to al enviar el token JWT.

Manejo de errores

Si Zendesk encuentra un error durante el procesamiento de una solicitud de inicio de sesión con JWT, envía un mensaje que explica el problema. Si se especificó un URL de cierre de sesión remoto al configurar la integración con JWT, redirige a ese URL y pasa un mensaje y un parámetro kind. En caso de error, el parámetro kind siempre tiene el valor "error". Zendesk recomienda especificar un URL de cierre de sesión remoto además de registrar los mensajes de Zendesk junto al tipo. La mayoría de los errores que pueden ocurrir son errores que es preferible corregir. Ejemplos: derivas de reloj, límites de frecuencia alcanzados, tokens no válidos, etc.

Ejemplos de código de implementación de JWT

La implementación de JWT en sí es sencilla y la mayoría de los lenguajes modernos tienen bibliotecas compatibles. Zendesk proporciona una serie de ejemplos para varias pilas en el siguiente repositorio JWT SSO GitHub:

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

Si implementa JWT en cualquier otra pila, nos encantaría incluir un ejemplo ahí también. Agregue un comentario a este artículo para compartir lo que ha implementado.

Si ejecuta IIS/AD y no desea crear su propia solución .NET, proporcionamos una implementación completa en ASP clásico, que requiere el ajuste de solo un par de variables. Descargue el script de autenticación ASP desde esta página en Github: https://github.com/zendesk/zendesk_jwt_sso_examples/tree/master/bundles.