Activar el inicio de sesión único con JWT

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 el Token Web JSON (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 rol de los administradores de Zendesk consiste en activar la opción de inicio de sesión único. En este artículo se describe cómo activar hasta dos configuraciones de inicio de sesión único con JWT que se pueden usar para autenticar a los integrantes del equipo (administradores y agentes, incluidos los agentes Light y los colaboradores), usuarios finales, o ambos.

El inicio de sesión único (SSO) depende de 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 utiliza JWT para asegurar el intercambio de datos de autenticación de los 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
• Activación del inicio de sesión único con SAML

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 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 intenta determinar si un usuario no autenticado es un usuario final o un integrante del equipo y redirige al usuario a la página de inicio de sesión remoto apropiada. 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 el equipo de TI) para asegurarse de que el tráfico dirigido a Zendesk se dirija por HTTPS y no por HTTP.

Necesitará la siguiente información para configurar un método de inicio de sesión único con JWT en Zendesk. El equipo de TI debería poder proporcionárselo.

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

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

Después de confirmar que cumple los requisitos y tiene toda la información necesaria, estará listo para activar el inicio de sesión único con JWT.

Activar el inicio de sesión único con JWT

Los administradores pueden activar el inicio de sesión único con SAML solo para los usuarios finales, solo para los integrantes del equipo (incluidos los agentes Light y colaboradores) o para ambos grupos. Se pueden crear hasta dos configuraciones del inicio de sesión único con JWT. Antes de comenzar, obtenga la información necesaria del equipo de TI de su compañía. Consulte Requisitos 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 Cuenta en la barra lateral y luego seleccione Seguridad > Inicio de sesión único.
2. Haga clic en Crear configuración de SSO y luego seleccione Token Web JSON.
3. Ingrese un Nombre de configuración único.
4. 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.

5. (Opcional) Para URL de cierre de sesión remoto, ingrese un URL de cierre de sesión a donde se debe redirigir a los usuarios después de que cierran sesión en Zendesk.

   Zendesk agrega automáticamente los parámetros email, external_id y brand_id al URL de cierre de sesión. 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/.
6. (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.

7. 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.
8. 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.
9. 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.
10. Haga clic en Save.

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

Después de crear la configuración del inicio de sesión único (SSO) con JWT, se debe asignar a los usuarios finales, a los integrantes del equipo, o ambos, para activarla.

Para asignar una configuración de SSO a los integrantes del equipo y los usuarios finales

1. Abra la configuración de seguridad para integrantes del equipo o usuarios finales.
   • En el Centro de administración, haga clic en Cuenta en la barra lateral y luego seleccione Seguridad > Autenticación de integrantes del equipo.
   • En el Centro de administración, haga clic en Cuenta en la barra lateral y luego seleccione Seguridad > Autenticación de usuarios finales.
2. Si está asignando una configuración de SSO a los integrantes del equipo, seleccione Autenticación externa para mostrar las opciones de autenticación.

   Estas opciones ya se muestran para los usuarios finales.

3. Haga clic en la opción Inicio de sesión único (SSO) en la sección Autenticación externa y luego seleccione los nombres de las configuraciones de SSO que desea utilizar.

   Si los usuarios finales seleccionan la opción SSO, automáticamente se anula la selección de la opción Autenticación de Zendesk si está activada. Para los integrantes del equipo, es posible que el inicio de sesión único no funcione en todos los casos, por lo que la autenticación de Zendesk permanece activa de manera predeterminada. Por ejemplo, se necesita una contraseña de Zendesk para acceder a su cuenta de Support desde muchas de las integraciones de Zendesk, o para usar la API de Zendesk o el framework de aplicaciones. Para desactivar la autenticación de Zendesk, consulte Para permitir que solo los integrantes del equipo utilicen la autenticación de SSO.

4. Haga clic en Guardar.

Para permitir que solo los integrantes del equipo utilicen la autenticación de SSO

1. En el Centro de administración, haga clic en Cuenta en la barra lateral y luego seleccione Seguridad > Autenticación de integrantes del equipo.
2. Deseleccione la opción Autenticación de Zendesk y haga clic en Guardar.

   

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

3. En el Centro de administración, haga clic en Cuenta en la barra lateral y luego seleccione Seguridad > Avanzada.
4. Haga clic en la pestaña Autenticación y luego seleccione una opción de Bypass de SSO.

   Puede elegir si desea que se otorgue acceso a la cuenta solo al Dueño de la cuenta o a todos los Administradores (incluido el dueño de la cuenta) en caso de que el proveedor de inicio de sesión externo deje 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 Save.

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, puede almacenar el nombre, la dirección de correo electrónico del usuario en Zendesk y otros datos. Para ello, puede usar los atributos adicionales de JWT.

Desactivar las notificaciones por correo electrónico sobre contraseñas de Zendesk

Cuando se agrega un usuario a una cuenta de Zendesk, es posible que se le envíe una notificación automática por correo electrónico para que verifique su dirección de correo electrónico y cree un nombre de usuario y una contraseña.

Se crea un perfil de usuario de Zendesk para los nuevos usuarios que accedan a la cuenta de Zendesk a través de SAML o JWT. Debido a que se han autenticado con una contraseña que no es de Zendesk, el perfil se crea sin una contraseña porque no es necesario que inicien sesión en Zendesk. No obstante, de manera predeterminada, todos los nuevos usuarios reciben una notificación por correo electrónico que les notifica que deben verificar su dirección de correo electrónico y crear un nombre de usuario y una contraseña.

Para evitar que esto suceda, asegúrese de quitar la marca de las siguientes opciones.

1. En el Centro de administración, haga clic en Personas en la barra lateral y luego seleccione Configuración > Usuarios finales.
2. En la sección Mensajes de correo electrónico de la cuenta, quite la marca de Enviar también un correo de bienvenida cuando un agente o administrador cree un nuevo usuario.
3. En Permitir que los usuarios cambien su contraseña, quite la marca de la opción.

Generar un nuevo secreto compartido

Es posible que en algunos casos (como cuando el secreto se ha visto comprometido) tenga que emitir un nuevo secreto compartido de JWT y dárselo a su equipo de TI o proveedor de identidad externo. 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 Cuenta en la barra lateral y luego seleccione Seguridad > Inicio de sesión único.
2. Pase el mouse por encima de la configuración de JWT para la cual desea crear un secreto compartido, haga clic en el icono del menú de opciones () y seleccione Editar.
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

Es importante observar que, 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. Solicite a dichos usuarios que restablezcan sus contraseñas en la página de inicio de sesión de Zendesk para que puedan obtener acceso.

Información adicional sobre JWT

JWT es un estándar abierto 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. Se codifica la cadena en Base64 y, a continuación, JWT hace un HMAC de la cadena en Base64 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.

Atributos obligatorios

Atributo	Descripción
iat	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	ID del Token Web JSON. Una ID única para el token, que Zendesk utiliza para evitar ataques de reproducción de token.
email	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	El nombre de este usuario. El usuario en Zendesk Support se creará y actualizará conforme a esto.

Atributos de usuario opcionales

Atributo	Descripción
external_id	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)	La configuración regional en Zendesk Support, especificada como un número.
organization	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	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	Un número de teléfono, especificado como una cadena.
tags	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	URL de una foto para configurar en el perfil del usuario.
role	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	Solo se aplica si el rol del usuario es agente.
user_fields	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

El paso del parámetro return_to es opcional, pero se recomienda para propiciar una experiencia óptima al usuario. Cuando Zendesk redirige al usuario a la página de inicio de sesión remoto, puede pasar 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 nombre y valor del parámetro 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 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 un URL relativo para el centro de ayuda.

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 y tokens no válidos.

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