# Trabajando con la API del servidor
Partes de este tema pueden estar traducidos automáticamente.
Las capacidades de uso de TrueConf Server se pueden ampliar mediante la API de RESTful, disponible en todas las versiones, incluyendo la gratuita.
# Principios de funcionamiento de API y OAuth 2.0
La sección API → OAuth2 está diseñada para administrar aplicaciones o servicios que trabajan con TrueConf Server API. La gestión del acceso se lleva a cabo 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 (opens new window), así como en el recuadro de abajo.
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 debe obtener una clave de acceso (access token) como resultado del proceso de autorización en TrueConf Server según el protocolo OAuth 2.0. Las aplicaciones que tienen una clave de acceso válida pueden acceder en cualquier momento a la API de TrueConf Server, cuya lista de llamadas está descrita en la documentación. A través de esta sección del panel de control, el administrador de TrueConf Server tiene control no solo sobre los accesos de las aplicaciones de terceros, sino también sobre las claves obtenidas a través de estas aplicaciones.
Ejemplos de trabajo con la API de TrueConf 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.
| Método de autorización OAuth 2.0 | Alcance de la clave de acceso | Resultado de la autorización |
|---|---|---|
| Client Credentials La aplicación recibe una clave de acceso cuyo alcance no está limitado por los datos de un usuario específico. No se requiere autorización para el usuario. Se recomienda su uso solo para aplicaciones de confianza. | No limitado. | Se emite una clave de acceso (access token) con una vida útil de 1 hora. |
| User Credentials (también conocido como Resource Owner Password Credentials Grant)
Para obtener la clave de acceso, es necesario proporcionar el nombre de usuario y la contraseña obtenidos desde la aplicación. | Limitada al alcance del usuario autorizado. | Se emite una clave de acceso válida por 1 hora, así como una clave de extensión de acceso (refresh token) válida por 7 días. |
| Authorization Code La clave de acceso (access token) se emite después de que el usuario se autorice por sí mismo en TrueConf Server. La aplicación no tiene acceso al nombre de usuario y a la contraseña. | Limitada al alcance del usuario autorizado. | Se emite una clave de acceso válida por 1 hora, así como una clave de extensión de acceso válida por 7 días. |
| Refresh Token Este método de autorización permite obtener una nueva clave de acceso (access token) basada en una clave de extensión de acceso existente (refresh token). | Limitada al alcance del usuario al que se le ha emitido la clave de extensión de acceso. | Se emite una nueva clave de acceso válida por 1 hora. No es posible renovarla utilizando este método. |
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.
# Descripción de los permisos
Las capacidades de una aplicación de terceros para trabajar con la API dependen de los permisos que se le hayan otorgado.
| Permiso | Descripción |
|---|---|
| conferences:read | Leer información sobre la conferencia |
| conferences:write | Crear, editar, eliminar conferencia |
| conferences.records:read | Leer información sobre las grabaciones de conferencias |
| conferences.participants:read | Leer la lista de participantes de la conferencia |
| conferences.participants:write | Crear, editar, eliminar participantes de la conferencia |
| conferences.invitations | Leer y editar la lista de invitados a la conferencia |
| conferences.sessions:read | Leer información sobre una sesión específica (sesión activa de videoconferencia) |
| conferences.sessions.participants:read | Leer la lista de participantes de la conferencia activa y sus roles |
| conferences.sessions.podiums.participants | Invitar a un participante de la conferencia activa al podio y eliminarlo del podio |
| groups:read | Leer información sobre el grupo de usuarios |
| groups:write | Crear, editar, eliminar grupos de usuarios. No disponible en LDAP |
| groups.users:read | Leer la lista de usuarios del grupo |
| groups.users:write | Crear, editar, eliminar usuarios del grupo. No disponible en LDAP |
| users:read | Leer información sobre los usuarios del servidor |
| users:write | Crear, editar, eliminar usuarios del servidor. No disponible en LDAP |
| users.addressbook:read | Leer contactos de las libretas de direcciones de los usuarios |
| users.addressbook:write | Crear, editar, eliminar contactos en la libreta de direcciones de los usuarios |
| users.avatar:read | Leer información sobre los avatares de los usuarios |
| users.avatar:write | Agregar y eliminar avatares de los usuarios |
| templates.conferences:read | Leer información sobre las plantillas de conferencias |
| templates.conferences:write | Crear, editar, eliminar plantillas de conferencias |
| logs.calls:read | Leer la lista de conferencias de los registros del servidor |
| logs.calls.participants:read | Leer la lista de participantes de la conferencia de los registros del servidor |
| logs.calls.invites:read | Leer la lista de usuarios invitados a la conferencia de los registros del servidor |
En la documentación para TrueConf Server API, se indica un conjunto de permisos necesarios para cada método para su correcta invocación.
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 para la creación de una nueva aplicación OAuth 2.0
Para agregar una aplicación OAuth 2.0:
Presione Create a new application.
Especifique su identificador en el campo Name. Se utiliza solo para la visualización en la lista de aplicaciones.
Para la autorización mediante el método Authorization Code, en el campo Redirect URL indique la URL a la cual será redirigida la aplicación. Para los demás métodos de autorización, puede indicar la dirección
https://localhost/.En la lista Permissions, marque los derechos necesarios para su aplicación.
Guarde los cambios con 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 revocar el acceso al servidor de esta aplicación y a todos sus nuevos usuarios. Tenga en cuenta que las claves de acceso y de renovación de acceso obtenidas usando el antiguo secreto seguirán funcionando hasta el final de su período de validez.