Uso de la API del servidor
Trabajo con el API del servidor
Partes de este tema pueden estar traducidos automáticamente.
Puede ampliar las funcionalidades de TrueConf Server utilizando la API RESTful, disponible en todas las versiones, incluida la gratuita.
Principios de funcionamiento de API y OAuth 2.0
La sección API → OAuth2 está destinada a la gestión de aplicaciones o servicios que operan con TrueConf Server API. El control de acceso se realiza de acuerdo con el protocolo de autorización OAuth 2.0, sobre el cual puede leer más en la documentación oficial del RFC 6749, así como en el recuadro a continuación.
La idea principal del protocolo OAuth 2.0 consiste en otorgar derechos de acceso al API a aplicaciones individuales (client en la terminología de OAuth) con un rango limitado de visibilidad y derechos. Este enfoque permite deshabilitar el acceso a un recurso del servidor a una aplicación específica o a su usuario en cualquier momento. El protocolo también permite autorizar de forma segura aplicaciones de terceros y realizar acciones en el servidor a través del API en nombre del usuario. En este caso, el usuario no debe proporcionar su nombre de usuario o contraseña a la aplicación de terceros (método Authorization Code).
Cada aplicación de terceros está obligada a obtener un token de acceso como resultado del proceso de autorización en TrueConf Server a través del protocolo OAuth 2.0. Las aplicaciones que tienen un token de acceso válido pueden acceder a la API de TrueConf Server en cualquier momento, cuya lista de llamadas está descrita en la documentación. A través de esta sección del panel de control, el administrador TrueConf Server tiene control no solo sobre los accesos de aplicaciones de terceros, sino también sobre los tokens obtenidos a través de estas aplicaciones.
Ejemplos de cómo trabajar con TrueConf la API se muestran en nuestro blog.
Después de la autorización, la aplicación recibe una clave de acceso (access token) con una vida útil limitada y con un alcance del servidor o del usuario. Por ejemplo, el alcance del servidor permite obtener datos de cualquier reunión, mientras que el del usuario solo permite obtener información de las reuniones en las que el usuario es participante o propietario. El alcance se determina por el tipo de autorización seleccionado por el desarrollador de la aplicación de terceros, y el conjunto de permisos para acceder a los recursos del servidor es determinado por el administrador del servidor.
Cada solicitud para crear una clave de acceso requiere la especificación de un ID de aplicación (Application ID) y un secreto de aplicación (Secret), los cuales se pueden obtener y actualizar creando o, respectivamente, editando la aplicación en esta sección. El ID de la aplicación se crea automáticamente y no se puede cambiar en el futuro, a diferencia del secreto de la aplicación, que se puede generar nuevamente.
| Método de autorización OAuth 2.0 | Alcance de la clave de acceso | Resultado de la autorización |
|---|---|---|
| Client Credentials La aplicación obtiene una clave de acceso cuyo ámbito no está limitado a los datos de un usuario específico. No se requiere autorización para el usuario. Se recomienda utilizar solo para aplicaciones de confianza. | No está limitado. | Se emite una clave de acceso (access token) con una duración de 1 hora. |
| Credenciales del Usuario (también conocido como Concesión de Credenciales de Contraseña de Recurso Propietario) Para obtener la clave de acceso, es necesario proporcionar el inicio de sesión y la contraseña del usuario, obtenidos en el lado de la aplicación. | Limitado al ámbito del usuario autorizado. | Se emite una clave de acceso por 1 hora, además de una clave de renovación de acceso (refresh token) por 7 días. |
| Código de Autorización El token de acceso (access token) se emite después de que el usuario se autentica de forma independiente en el lado del servicio. La aplicación no tiene acceso al nombre de usuario ni a la contraseña del usuario. | Limitado al ámbito del usuario autorizado. | Se emite una clave de acceso válida por 1 hora, así como una clave de renovación de acceso válida por 7 días. |
| Refresh Token Este método de autorización permite obtener un nuevo token de acceso (access token) basado en un token de actualización existente (refresh token). | Limitado al ámbito de visibilidad del usuario al que se le otorgó la clave de extensión de acceso. | Se emite una nueva clave de acceso por 1 hora. No es posible actualizarla utilizando este método. |
Descripción de permisos
Las capacidades de una aplicación de terceros para trabajar con la API dependen de los permisos que se le hayan otorgado.
La lista de permisos se amplía con cada versión del API junto con el aumento de las capacidades del servidor de videoconferencias. Para ver la lista de correspondencia entre el API y la versión del servidor, consulte la documentación del API.
En la documentación del API de TrueConf Server, se especifica un conjunto de permisos necesarios para la ejecución exitosa de cada método.
Si una aplicación OAuth necesita tanto acceso de lectura como de escritura a ciertos parámetros, en lugar de especificar los permisos <permission>:read y <permission>:write, puede establecerse el permiso general <permission> si está disponible. Por ejemplo, si una aplicación necesita leer y editar las cuentas de usuario del servidor, en lugar de seleccionar ambas casillas users:read y users:write, solo se puede especificar una: users.
Formulario de creación de una nueva aplicación OAuth 2.0
Para agregar una aplicación OAuth 2.0:
Presione Create a new application.
Introduzca su identificador en el campo Name. Este se utiliza solo para mostrar en la lista de aplicaciones.
Para la autorización mediante el método Authorization Code, ingrese la URL en el campo Redirect URL a la que se redirigirá la aplicación. Para los demás métodos de autorización, puede especificar la dirección
https://localhost/.En la lista Permissions, marque los permisos necesarios para su aplicación.
Guarde los cambios utilizando el botón Create.
Página de edición de la aplicación
En la página de la aplicación, además de poder editar sus propiedades, también es posible ver la lista de claves de acceso que los usuarios de esta aplicación han obtenido. Puedes eliminar en cualquier momento las claves de acceso para usuarios específicos, lo que les impedirá acceder a los recursos del servidor a través de la API.
También puede Regenerate el secreto de la aplicación, lo que puede ser útil por razones de seguridad para terminar el acceso al servidor por esta aplicación y todos sus nuevos usuarios. Tenga en cuenta que las claves de acceso y renovación obtenidas con el secreto anterior seguirán funcionando hasta que expire su tiempo de vida.
Documentación API integrada
La documentación integrada de la API v4 está disponible a partir de la versión 5.5.3 del servidor.
En la instalación de su servidor, ya se incluye documentación integrada para facilitar el trabajo con la API (al igual que con esta documentación del administrador). Sus desarrolladores no necesitarán buscar instrucciones en internet y podrán crear scripts y aplicaciones utilizando la API TrueConf Server, incluso trabajando en una red cerrada (CSPD).
La documentación API integrada está disponible en el siguiente enlace:
https://[server-address]/api/v4/docs/
donde [server-address] es la dirección IP o FQDN de su servidor.
La documentación integrada admite el modo de prueba de cualquier solicitud. Para hacerlo:
Genere un token para la aplicación OAuth 2.0 con los permisos necesarios (o utilice un token de la sección Web → Security para fines de prueba).
Especifique el token en la sección Introduction dentro del bloque Bearer Token:
Ahora, este token se recordará durante la sesión de esta página en el navegador y podrá realizar cualquier solicitud utilizando el botón Test Request:
Además, el token del punto 1 se recordará para todas las solicitudes si se especifica en cualquier solicitud antes de enviarla:
Al cambiar el idioma de la página o al actualizarla, el token API especificado para las pruebas se olvidará y deberá ingresarse nuevamente. Esto se hace por seguridad, ya que el token no se guarda en las cookies.