Una conexión permite guardar de manera segura las credenciales de API que se van a utilizar con un servicio o sistema, como Slack o Shopify. Una conexión se puede usar para autenticar las llamadas de API de REST en el paso Hacer llamada de API del generador de bots o para acciones de asistencia automática. Para crear conexiones, es necesario ser un administrador.
Acerca de las conexiones
Las conexiones admiten uno de los siguientes métodos de autenticación de la API:
- Clave API
- Autenticación básica
- Token de portador
- OAuth 2.0
El método de autenticación determina el tipo de credenciales que almacena la conexión. Por ejemplo, una conexión de autenticación básica almacena un nombre de usuario y una contraseña. Después de que se crea una conexión, no se puede cambiar su tipo de autenticación.
Distintas API admiten distintos métodos de autenticación. Para determinar el método de autenticación apropiado para una llamada de API, consulte la documentación de la API correspondiente.
Encabezados de HTTP para tipos de autenticación
| Tipo de autentificación | Encabezado de HTTP |
|---|---|
| Clave API | Se establece cuando se crea la conexión. Consulte Encabezados de HTTP para las claves API. |
| Autenticación básica |
Authorization: Basic
|
| Token de portador |
Authorization: Bearer
|
| OAuth 2.0 |
El token de acceso se envía al servicio en Authorization:
Bearer
|
Si desea más información sobre cómo usar una conexión en un bot, consulte Utilización del paso Hacer llamada de API en el generador de bots. Si desea más información acerca del uso de una conexión en una acción, consulte Crear y administrar acciones de asistencia automática.
Crear un cliente OAuth
Una conexión OAuth almacena un token de acceso de OAuth 2.0 para un servicio o sistema, como Slack, Shopify o Zendesk.
Antes de crear una conexión con el tipo de autenticación OAuth 2.0, debe configurar un cliente OAuth. Para configurar el cliente OAuth, necesita tener la ID del cliente, el secreto del cliente, el URL de autorización, el URL de token y ámbitos de la interfaz de configuración de OAuth o el portal de administrador del sistema externo. Estas credenciales se generan al registrar su aplicación cliente (como Zendesk) con el sistema externo. Los pasos concretos varían según el servicio externo. Si se lo exigen, configure el URL de devolución de llamada del cliente como "https://zis.zendesk.com/api/services/zis/connections/oauth/callback".
- Código de autenticación
- Credenciales del cliente
Se admite el tipo de concesión de token de actualización para los clientes OAuth 2.0 creados usando un tipo de concesión de código de autorización. Si la respuesta del token de acceso del sistema incluye los valores no vacíos expires_in y refresh_token, el token de acceso se actualiza automáticamente con el token de actualización.
Las conexiones OAuth 2.0 creadas con un cliente que usa el tipo de concesión de credenciales de cliente puede incluir un valor de vencimiento del token. En estos casos, cuando se vence el token, se obtiene un token de acceso nuevo usando el mismo cliente OAuth.
Para crear un cliente OAuth
- En el Centro de administración, haga clic en
Aplicaciones e integraciones en la barra lateral y luego seleccione Conexiones > Conexiones. - Ingrese un nombre para el cliente. Después de crear el cliente, no se puede cambiar este nombre.
- Ingrese la ID del cliente. Esto es un identificador único asignado a su cliente OAuth, similar a un nombre de usuario para su cliente.
- Ingrese el secreto del cliente. Esto actúa como una contraseña para su aplicación cliente e inspira confianza entre Zendesk y el sistema externo.
- (Tipo de concesión de código de autorización solamente) Ingrese el URL de autorización. Este es el URL de servidor que se utiliza para recibir un código de autorización.
- Ingrese el URL de token. Este es el URL que se utiliza para recibir un token de acceso.
- Ingrese una lista de ámbitos predeterminados separados por medio de espacios. Los ámbitos son los permisos que representan el acceso que tiene una aplicación cliente en nombre del usuario.
- Haga clic en Guardar para crear el cliente.
Crear una conexión
Se puede crear una conexión en el Centro de administración desde la página Conexiones.
Para crear una conexión
- En el Centro de administración, haga clic en Aplicaciones e integraciones en la barra lateral y luego seleccione Conexiones > Clientes OAuth.
- Haga clic en Crear conexión.
- Seleccione un tipo de autenticación.
- Ingrese un nombre para la conexión. Después de crear la conexión, no se puede cambiar este nombre.
- Haga una de las siguientes cosas:
- (Clave de API, Autenticación básica, Token de portador) Configure las credenciales de autenticación de la conexión. La conexión utiliza estos detalles para autenticar las llamadas de API de REST al servicio o sistema.
- (OAuth 2.0) Seleccione el cliente para usar y, opcionalmente, ingrese una lista de ámbitos separados por espacios. Si no ingresa ningún ámbito, se utilizan los predeterminados especificados en el cliente OAuth.
- Ingrese un dominio permitido para la conexión. Después de crear la conexión, no se puede cambiar el dominio permitido. Si desea más información, consulte Dominio permitido.
- Haga clic en Guardar para crear la conexión.
Después de creada la conexión, puede ver los detalles en la página Conexiones en el Centro de administración. Consulte Administración de conexiones.
Dominio permitido
Cada conexión requiere un nombre de host de URL como dominio permitido. Zendesk solo pasa las credenciales de la conexión en las llamadas de API a este nombre de host. Cualquier intento por usar la conexión con otros nombres de host producirá un error. Esto ayuda a evitar una filtración accidental de las credenciales de la conexión. Después de que se crea una conexión, no se puede cambiar su dominio permitido.
Por ejemplo, solo se puede usar una conexión con un dominio permitido de "api.example.com" para hacer llamadas de API al nombre de host “https://api.example.com”.
Requisitos para el dominio permitido
El dominio permitido de una conexión no puede exceder 128 caracteres. Un subdominio o dominio en el valor no puede exceder 63 caracteres. El valor debe contener un nombre de dominio válido.
Una conexión siempre usa un esquema https. No se admite ningún otro esquema, como ftps.
Comodines para el dominio permitido
El dominio permitido de una conexión admite un subdominio de comodín (*) opcional. Esto permite usar la conexión con el dominio ápex y cualquier subdominio. Por ejemplo, se puede usar una conexión con un dominio permitido de *.example.com para autenticar las llamadas de API a "example.com" o cualquier subdominio de "example.com".
Para usar un subdominio de comodín, los dos primeros caracteres del dominio permitido deben ser *.. No se puede usar un comodín en otras partes del nombre de host. Por ejemplo, no se puede usar un comodín dentro de un nombre de host, como exam*.com, o bien my-*.example.com.
No se puede usar un comodín con solo un sufijo de dominio público, como *.com, *.com.au, o bien *.myshopify.com. Si desea ver una lista de sufijos públicos, consulte la lista de sufijos públicos que se encuentra en publicsuffix.org.
Encabezados de HTTP para las claves API
Cuando se crea una conexión de clave API, se debe especificar un nombre de encabezado de HTTP. Cuando se usa la conexión para hacer una llamada de API, Zendesk pasa la clave de API como el valor para este encabezado.
Muchas API usan un encabezado personalizado para aceptar las claves API. Para obtener el nombre del encabezado apropiado para una llamada de API, consulte la documentación de la API correspondiente.
Requisitos para el nombre del encabezado
El nombre del encabezado de una conexión de clave API no puede exceder 128 caracteres. El nombre del encabezado solo puede contener letras, guiones normales (-) y guiones bajos (_).
acceptaccept-charsetaccept-encodingaccept-languagecache-controlconnectioncontent-md5cookiedateexpectfromhostif-matchif-modified-sinceif-none-matchif-rangeif-unmodified-sincemax-forwardspragmaproxy-authenticateproxy-authorizationrangeserverreferertetrailertransfer-encodingupgradeuser-agentviawarningwww-authenticate- Los nombres de encabezados que comienzan por:
x-amz-
x-amzn-x-forwarded-x-zis-