Puede utilizar OAuth 2 para autenticar todas las solicitudes API de su aplicación a Zendesk. OAuth brinda una manera segura para que la aplicación pueda tener acceso a los datos de Zendesk sin tener que almacenar ni usar las contraseñas de los usuarios de Zendesk, lo que es información confidencial.
Para usar la autenticación OAuth, es necesario que registre su aplicación en Zendesk. También tendrá que agregar funcionalidad a su aplicación para admitir el flujo de autorización de OAuth.
Temas que se tratan en este artículo:
Temas relacionados:
- Si desea ver un tutorial sobre cómo crear una aplicación web que implementa un flujo de autorización de OAuth, consulte Building an OAuth web app.
- Si desea implementar un flujo de autorización de OAuth en las aplicaciones de Zendesk, consulte Adding third-party OAuth to a Support app.
- Si no es necesario que los usuarios le den a su aplicación acceso a sus cuentas, de todos modos puede usar los tokens de OAuth para autenticar las solicitudes de la API. Consulte Creating and using OAuth tokens with the API.
Registrar su aplicación en Zendesk
Es necesario que registre su aplicación para generar credenciales de OAuth que su aplicación pueda usar para autenticar las llamadas API a Zendesk.
Para registrar su aplicación
- En el Centro de administración, haga clic en
Aplicaciones e integraciones en la barra lateral y luego seleccione API > API de Zendesk. - Haga clic en la pestaña Clientes OAuth en la página API de Zendesk, y luego haga clic en Agregar cliente OAuth en el lado derecho de la lista de clientes OAuth.
- Complete los siguientes campos para crear un cliente:
- Nombre de cliente: ingrese un nombre para su aplicación. Este es el nombre que verán los usuarios cuando se les solicite que otorguen acceso a la aplicación, y cuando verifiquen la lista de aplicaciones de terceros que tienen acceso a sus cuentas de Zendesk.
- Descripción: opcional. Una descripción corta de la aplicación que verán los usuarios cuando se les solicite que otorguen acceso a ella.
- Compañía: opcional. El nombre de la compañía que verán los usuarios cuando se les solicite que otorguen acceso a la aplicación. La información les permitirá saber a quién le están otorgando acceso.
- Logotipo: opcional. El logotipo que verán los usuarios cuando se les solicite que otorguen acceso a la aplicación. La imagen puede tener formato JPG, GIF o PNG. Para obtener mejores resultados, cargue una imagen cuadrada. Se le cambiará de tamaño para la página de autorización.
- Identificador único: el campo se rellena automáticamente con una versión reformateada del nombre que ingresó para su aplicación. Puede cambiarlo si desea.
- Tipo de cliente: público o confidencial. Los clientes OAuth públicos son aplicaciones que se ejecutan en entornos donde las credenciales no se pueden almacenar de manera segura, como las aplicaciones móviles y web. Estos clientes tienen que usar PKCE. Los clientes OAuth confidenciales se ejecutan en servidores seguros donde sus credenciales se pueden mantener seguras. Estos clientes pueden usar PKCE, un secreto de cliente, o ambos. Consulte Tipos de clientes OAuth.
- URL de redireccionamiento: ingrese el URL o los URL que Zendesk debe usar para enviar la decisión del usuario de otorgar acceso a su aplicación. Los URL deben ser absolutos y no relativos, https (salvo que sea localhost o 127.0.0.1), y separados por línea nuevas.
- Haga clic en Guardar.
Después de volver a cargar la página, el campo Secreto que se rellenó automáticamente aparecerá en la parte inferior. Se trata del valor "client_secret" especificado en las especificaciones de OAuth2.
- Copie el valor Secreto al portapapeles y guárdelo en un lugar seguro. Nota: Los caracteres pueden sobrepasar el ancho del cuadro de texto, de modo que asegúrese de que ha seleccionado todo antes de copiarlo.Importante: Por razones de seguridad, su secreto se mostrará completo solo una vez. Después de hacer clic en Guardar, solo tendrá acceso a los nueve primeros caracteres.
- Haga clic en Guardar.
Utilice el identificador único y el valor secreto en su aplicación como se describe en el tema siguiente.
Tipos de clientes OAuth
Los clientes OAuth de Zendesk incluyen una propiedad kind que se pasa durante la creación del cliente OAuth, y pueden tener uno de los siguientes valores:
- Público: Los clientes OAuth públicos son aplicaciones que se ejecutan en entornos donde las credenciales no se pueden almacenar de manera segura, como las aplicaciones móviles y web. Estos clientes tienen que usar PKCE.
- Confidencial: Los clientes OAuth confidenciales se ejecutan en servidores seguros donde sus credenciales se pueden mantener seguras. Estos clientes pueden usar PKCE, un secreto de cliente, o ambos.
Si desea más información, consulte Client Types.
El tipo de cliente OAuth de Zendesk se aplica solo al sistema de gestión de tickets de Zendesk Support. No se admite en Chat, Conversaciones o Sell.
Los clientes OAuth existentes de Zendesk tienen actualmente la propiedad kind establecida en unknown. Estos clientes no se verán afectados hasta que la propiedad kind se actualice a public o confidential. Los nuevos clientes OAuth creados en el Centro de administración deben establecer la propiedad kind durante la creación.
kind a public, debe implementar PKCE primero. Si no lo hace, el cliente no funcionará, ya que se requerirá PKCE inmediatamente.Los nuevos clientes OAuth creados en el Centro de administración deben establecer la propiedad kind. Si bien la propiedad kind no es obligatoria para los clientes OAuth que fueron creados con el extremo api/v2/oauth/clients endpoint, Zendesk recomienda incluirla.
Implementar un flujo de autorización de OAuth en su aplicación
Zendesk admite el flujo de concesión de código de autorización para obtener tokens de acceso. A este flujo se le conoce como flujo de concesión de código de autorización porque es necesario obtener un código de autorización antes de solicitar un token de acceso. Otros flujos de concesión son obsoletos.
El flujo no usa tokens de actualización. El token de acceso no vence.
Para implementar el flujo de concesión de código de autorización, es necesario agregar la siguiente funcionalidad a su aplicación:
- Paso 1: Enviar al usuario a la página de autorización de Zendesk
- Paso 2: Gestionar la decisión de autorización del usuario
- Paso 3: Obtener un token de acceso de Zendesk
- Paso 4: Utilizar el token de acceso en llamadas API
Si desea ver un tutorial sobre cómo crear una aplicación web que implementa un flujo de autorización de OAuth, consulte Building an OAuth web app.
El método de concesión de código de autorización admite PKCE (clave de prueba para el intercambio de código), que agrega una capa de seguridad adicional. Si desea más información, consulte Using PKCE to make Zendesk OAuth access tokens more secure en la documentación para desarrolladores.
Paso 1: Enviar al usuario a la página de autorización de Zendesk
En primer lugar, su aplicación tiene que enviar al usuario a la página de autorización de Zendesk. La página le solicita al usuario que autorice su aplicación para que pueda acceder a Zendesk en nombre del usuario. Una vez que el usuario hace una selección, Zendesk envía la selección y algunos otros fragmentos de información de nuevo a la aplicación.
Para enviar al usuario a la página de autorización de Zendesk
Agregue un vínculo o un botón a su aplicación, que envíe al usuario al siguiente URL:
https://{subdomain}.zendesk.com/oauth/authorizations/newdonde {subdomain} es su subdominio de Zendesk. Se puede usar una solicitud POST o GET. Incluya los siguientes parámetros:
-
response_type: requerido. Zendesk devuelve un código de autorización en la respuesta, de manera que especifique
code(código) como el tipo de respuesta. Ejemplo:response_type=code. - redirect_uri: requerido. El URL que Zendesk debe usar para enviar la decisión del usuario de otorgar acceso a su aplicación. El URL debe ser absoluto y no relativo. También tiene que ser seguro (https), a menos que se esté usando localhost o 127.0.0.1.
- client_id: requerido. El identificador único que obtuvo cuando registró su aplicación en Zendesk. Consulte la sección anterior.
- scope: requerido. Una lista de ámbitos (scopes) separados por espacios que controlan el acceso a los recursos de Zendesk. Se puede solicitar acceso de read, write o impersonate a todos los recursos o bien a recursos específicos. Consulte Especificar el ámbito.
-
state: una cadena arbitraria que se incluye en la respuesta de Zendesk después de que el usuario decide si va a conceder acceso o no. Se puede usar el parámetro para evitar ataques cross-site request forgery (CSRF). En un ataque CSRF, el usuario final es engañado para que haga clic en un vínculo que realiza una acción en una aplicación web donde el usuario final aún está autenticado. Para evitar este tipo de ataques, agregue algún valor al parámetro
state(estado) y valídelo cuando vuelva. - code_challenge: se requiere si se usa PKCE. Una cadena que representa un desafío de código derivado de un verificador de código. Consulte Generating the code_challenge value en la documentación para desarrolladores.
- code_challenge_method: se requiere si se usa PKCE. El método utilizado para derivar el desafío de código. Especifique "S256" como el valor.
Asegúrese de usar codificación URL para los parámetros.
Solicitud GET de muestra
https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=code&redirect_uri={your_redirect_url}&client_id={your_unique_identifier}&scope=read%20writeLa página de autorización de Zendesk se abre en el navegador del usuario final. Una vez que el usuario toma una decisión, Zendesk envía la decisión al URL de redireccionamiento especificado en la solicitud.
Especificar el ámbito
Debe especificar un ámbito para controlar el acceso de la aplicación a los recursos de Zendesk. El ámbito read brinda a una aplicación acceso a las terminales GET. Incluye el permiso para realizar transferencias locales de recursos relacionados. El ámbito write brinda a una aplicación acceso a las terminales POST, PUT y DELETE para crear, actualizar y borrar recursos.
Si desea más información sobre el ámbito, consulte OAuth Tokens for Grant Types.
El ámbito impersonate permite que un administrador de Zendesk haga solicitudes en nombre de los usuarios finales. Consulte Hacer solicitudes de API en nombre de los usuarios finales.
Por ejemplo, el siguiente parámetro proporciona a una aplicación acceso de lectura a todos los recursos:
"scope": "read"El siguiente parámetro proporciona acceso de lectura y escritura a todos los recursos:
"scope": "read write"Se puede refinar el ámbito de los siguientes recursos:
- tickets
- usuarios
- registros de auditoría (solo lectura)
- organizaciones
- centro de ayuda
- aplicaciones
- disparadores
- automatizaciones
- destinos
- webhooks
- zis
La sintaxis es como sigue:
"scope": "resource:scope"Por ejemplo, el siguiente parámetro limita una aplicación para que solo pueda leer tickets:
"scope": "tickets:read"Para darle a una aplicación acceso de lectura y escritura a un recurso, especifique ambos ámbitos:
"scope": "users:read users:write"Para darle a una aplicación acceso de escritura a un solo recurso, por ejemplo a organizaciones, y acceso de lectura a todo lo demás:
"scope": "organizations:write read"Paso 2: Gestionar la decisión de autorización del usuario
La aplicación debe gestionar la respuesta de parte de Zendesk que le informa lo que ha decidido el usuario. La información se incluye en los parámetros de URL en el URL de redireccionamiento.
Si el usuario decidió otorgar acceso a la aplicación, el URL de redireccionamiento contiene un código de autorización. Ejemplo:
{redirect_url}?code=7xqwtlf3rrdj8uyeb1yfEl código de autorización solo es válido por 120 segundos.
Si el usuario decidió no otorgar acceso a la aplicación, el URL de redireccionamiento contiene los parámetros error y error_description, que indican a la aplicación que el usuario ha negado el acceso:
{redirect_url}?error=access_denied&error_description=The+end-user+or+authorization+server+denied+the+requestUtilice estos valores para controlar el flujo de su aplicación. Si el URL contiene un parámetro code, obtenga un token de acceso de Zendesk como se describe en la siguiente sección. Este es el token que se debe incluir en las llamadas API a Zendesk.
Paso 3: Obtener un token de acceso de Zendesk
Si su aplicación recibió un código de autorización de Zendesk como respuesta a que el usuario concedió acceso, su aplicación puede cambiarla por un token de acceso. Para obtener el token de acceso, realice una solicitud POST a la siguiente terminal:
https://{subdomain}.zendesk.com/oauth/tokensIncluya los siguientes parámetros requeridos en la solicitud:
- grant_type: especifique "authorization_code" como el valor.
- code: utilice el código de autorización que recibió de Zendesk después de que el usuario concedió acceso.
- client_id: use el identificador único especificado en un cliente OAuth en la interfaz de administrador de Support (Administrador > Canales > API > Clientes OAuth). Consulte Registrar su aplicación en Zendesk.
-
client_secret: use el secreto especificado en un cliente OAuth en la interfaz de administrador de Support (Administrador > Canales > API > Clientes OAuth). Consulte Registrar su aplicación en Zendesk.
Si se utiliza la PKCE
code_challengey los parámetroscode_verifier, no se requiereclient_secret. Se puede usar esta característica para migrar del flujo de concesiones implícito, que ya no se recomienda por motivos de seguridad. Consulte Using PKCE to migrate from the implicit grant flow en la documentación para desarrolladores. - redirect_uri: el mismo URL de redireccionamiento que en el paso 1. Solo para propósitos de identificación.
- scope: consulte Especificar el ámbito.
-
code_verifier: se requiere si se usa PKCE. La cadena utilizada para generar el valor
code_challenge. Consulte Generating the code_challenge value en la documentación para desarrolladores.
La solicitud debe hacerse a través de https y las propiedades deben tener formato JSON. Si utiliza una aplicación personalizada o de terceros para hacer la solicitud de API, consulte la documentación correspondiente para averiguar el formato correcto para los valores de propiedades.
Utilizar curl
curl https://{subdomain}.zendesk.com/oauth/tokens \
-H "Content-Type: application/json" \
-d '{"grant_type": "authorization_code", "code": "{your_code}",
"client_id": "{your_client_id}", "client_secret": "{your_client_secret}",
"redirect_uri": "{your_redirect_url}", "scope": "read" }' \
-X POSTRespuesta de muestra
Status: 200 OK
{
"access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
"token_type": "bearer",
"scope":"read"
}Paso 4: Utilizar el token de acceso en llamadas API
La aplicación puede usar el token de acceso para realizar llamadas API. Incluya el token en un encabezado de autorización HTTP con la solicitud, como sigue:
Authorization: Bearer {a_valid_access_token}
Por ejemplo, una solicitud en curl para hacer una lista de los tickets sería como sigue:
curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
-H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"