Activar el inicio de sesión único con JWT

Los administradores pueden activar el inicio de sesión único con JWT solo para los usuarios finales, solo para los integrantes del equipo (incluidos los agentes Light y colaboradores) o para ambos grupos. Se pueden crear varias configuraciones de 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

En el Centro de administración, haga clic en Cuenta en la barra lateral y luego seleccione Seguridad > Inicio de sesión único.
Haga clic en Crear configuración de SSO y luego seleccione Token Web JSON.
Ingrese un Nombre de configuración único.
Para URL de inicio de sesión remoto, ingrese el URL al que 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.
(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/.
(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.
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.
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.
Seleccione Mostrar el botón cuando los usuarios inician sesión para agregar un botón Continuar con SSO a la página de inicio de sesión de Zendesk.
Si lo desea, puede personalizar el rótulo del botón introduciendo un valor en el campo Nombre del botón. Los rótulos de botón personalizados son útiles si agrega varios botones de SSO a la página de inicio de sesión. Consulte Agregar botón "Continuar con SSO" a la página de inicio de sesión de Zendesk si desea más información.
Haga clic en Guardar.

De manera predeterminada, las configuraciones de inicio de sesión único empresarial están inactivas. Tendrá que asignar la configuración de SSO a los usuarios para activarlo.

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, deberá asignarla a los usuarios finales, a los integrantes del equipo o a ambos para poder activarla.

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

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.
Seleccione Autenticación externa para mostrar las opciones de autenticación.
Seleccione los nombres de las configuraciones de SSO que desea usar.
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.
Decida cómo va a permitir que inicien sesión los usuarios finales.

Dejarlos elegir permite que el usuario inicie sesión a través de cualquier método de autenticación activado. Consulte Ofrecer a los usuarios distintas opciones de inicio de sesión en Zendesk.

Redirigir a SSO permite que los usuarios se autentiquen solo a través de la configuración de SSO principal. Los usuarios no ven ninguna opción de inicio de sesión adicional, incluso si las opciones de autenticación están activadas. Cuando se selecciona Redirigir a SSO, aparece el campo SSO principal, donde podrá seleccionar la configuración de SSO principal.
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 no se sincronizarán automáticamente con la cuenta de Zendesk. Los usuarios se actualizan en Zendesk en el momento de la autenticación. Por ejemplo, si se agrega un usuario a su sistema interno, el usuario es agregado a la cuenta de Zendesk en el momento en que inicia sesión en 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.

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

Se crea un perfil de usuario de Zendesk para los nuevos usuarios que acceden a la cuenta de Zendesk a través del inicio de sesión único con SAML, JWT u OpenID Connect (OIDC). Debido a que los usuarios son autenticados a través de un IdP 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 directamente.

Los nuevos usuarios que inician sesión en Zendesk a través de SSO son verificados a través de un IdP, por lo que no recibirán notificaciones por correo electrónico para que verifiquen su cuenta. Sin embargo, se recomienda desactivar estas notificaciones por correo electrónico automatizadas para evitar que se envíen si el IdP no verifica al usuario correctamente. En el caso de SSO, la verificación del usuario siempre se tiene que hacer a través del IdP.

Para desactivar las notificaciones por correo electrónico sobre contraseñas

En el Centro de administración, haga clic en Personas en la barra lateral y luego seleccione Configuración > Usuarios finales.
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.
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

En el Centro de administración, haga clic en Cuenta en la barra lateral y luego seleccione Seguridad > Inicio de sesión único.
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.
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.
Haga clic en Restablecer secreto para confirmar el restablecimiento.
Debería ver un nuevo Secreto compartido en texto sin formato.
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.
Guarde los cambios.

Cambiar de método de autenticación

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, los usuarios tendrán que restablecer 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 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 envío del formulario
Ejemplos de generació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, cree la carga JWT y envíe una solicitud POST que contenga la carga JWT al siguiente extremo de Zendesk:

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

La carga debe tener codificación en base64 y debe ser enviada por un cliente por medio de un formulario. No se podrá enviar la carga con una solicitud AJAX, fetch o axios del lado del cliente porque la solicitud será bloqueada por la política de mismo origen del cliente. Tampoco se podrá hacer una solicitud POST desde su servidor porque no configurará correctamente las cookies que se usan para la autenticación del navegador del usuario.

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

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

No se admiten los subdominios con mapeo de host.

Atributos de JWT

Envíe atributos de JWT usando un hash (Ruby) o diccionario (Python). El JWT debe tener una codificación en base64. Ejemplo 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")

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

Atributos de usuario opcionales

Atributo	Tipo de datos	Descripción
external_id	cadena	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)	entero	La configuración regional en Zendesk Support, especificada como un número.
organization	cadena	El nombre de una organización a la cual desea agregar el usuario. 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 varios nombres de organizaciones al mismo tiempo, use el atributo organizations en lugar. Los nombres de organizaciones se deben pasar en una cadena, separados por comas.
organization_id	entero	La ID externa de la organización en la API de Zendesk. Si se proporcionan los atributos organization y organization_id, se ignora organization. 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 ID de organizaciones al mismo tiempo, use el atributo organization_ids en lugar. Las ID de organizaciones se deben pasar en una cadena, separadas por comas.
phone	cadena	Un número de teléfono, especificado como una cadena. El número de teléfono debe cumplir con el plan de numeración telefónica internacional E.164. Ejemplo: +15551234567. Los números E.164 son números internacionales que tienen un prefijo de país, normalmente un código de área y un número de abonado. Un número de teléfono E.164 válido debe incluir un código de llamada del país.
tags	matriz	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	cadena	URL de una foto para configurar en el perfil del usuario.
role	cadena	El rol del usuario. Este valor se puede establecer en usuario final, agente o administrador. El valor predeterminado es usuario final. Si el rol del usuario es diferente al de Zendesk Support, el rol se cambia en Zendesk Support.
custom_role_id	entero	Solo se aplica si el rol del usuario es agente.
user_fields	objeto	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:

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
```
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 o lo agrega al cuerpo de la solicitud. Ejemplo:
```
https://mycompany.zendesk.com/access/jwt?&return_to=https://mycompany.zendesk.com/tickets/123
```
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 envío del formulario

La carga de JWT debe enviarse mediante un formulario desde un navegador al siguiente extremo de Zendesk:

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

Zendesk proporciona una serie de ejemplos para varias pilas de tecnología en el repositorio de inicio de sesión único con JWT para Zendesk en GitHub. Es necesario enviar el formulario de carga de JWT desde un navegador para garantizar que se puedan establecer correctamente las cookies en el navegador y que la solicitud no sea bloqueada por CORS.

Consulte los siguientes ejemplos de envío de formularios:

Respuesta

La respuesta debe ser un código HTML con un estado 200 OK. El formato de la respuesta es como sigue:

<html><body>You are being <a href="">redirected</a>.</body></html>

Si href coincide con el valor de return_to, el usuario fue autenticado correctamente y se deben establecer las cookies. Si href comienza con https://SUBDOMAIN.zendesk.com/access/unauthenticated, Zendesk no pudo autenticar al usuario.

Ejemplos de generación de JWT

La codificació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 repositorio de inicio de sesión único con JWT de GitHub:

https://github.com/zendesk/zendesk_jwt_sso_examples/tree/master/jwt_generation

El código de generación de JWT es para la implementación del servidor. El JWT generado se puede volver a enviar a la página de inicio de sesión, para luego iniciar el envío del formulario desde el navegador.

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:

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

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