Permisos

Información general

Como administrador de sistema de Workplace, puedes controlar las funcionalidades disponibles en cada integración creando apps y otorgándoles permisos específicos. Cada app puede recibir un nombre para identificar el servicio que ofrece. Las apps incluyen tokens de acceso a la app y permisos que controlan la información que puede ser leída y escrita por dicha app.

En esta guía se describe con un mayor nivel de detalle el modelo de apps y permisos.

Los permisos de control al editar una app de integración personalizada

Permisos disponibles

Cada app de Workplace puede recibir su propio conjunto de permisos para controlar el nivel de funcionalidad disponible en la API Graph y la API de administración de cuenta.

Cuando creas una app y otorgas permisos, estos se aplican a todas las cuentas de tu comunidad. Los titulares de las cuentas no necesitan otorgar permisos adicionales a la app para beneficiarse de su funcionalidad. Esta modalidad se diferencia del modelo de permisos de Facebook, donde cada usuario otorga permisos individualmente a la app al iniciar sesión.

A continuación se incluye el listado completo de permisos de app disponibles para las integraciones, junto con una descripción general de cómo pueden utilizarse.

Permisos de nivel de grupo

En algunos permisos, existe la posibilidad de limitar una integración para que se encuentre habilitada en determinados grupos. Esto te permite especificar el acceso de una integración al contenido puntual que quieras mostrar.

Por ejemplo, puedes permitir que una integración de publicación de alertas publique únicamente en el grupo exclusivo de un equipo, o bien habilitar que una integración de app para empleados consulte contenido únicamente en determinados grupos abiertos.

Para especificar los permisos de nivel de grupo en una integración personalizada, usa el panel "Acceso al grupo" en el diálogo "Editar integración".

Habilitación del permiso de nivel grupal en esta integración.

Los permisos de nivel de grupo se aplican a los siguientes permisos:

• Leer el contenido del grupo: consulta las publicaciones, los comentarios y los perfiles de miembro en los grupos seleccionados.
• Administrar el contenido del grupo : administra las publicaciones y los comentarios en los grupos seleccionados.
• Administrar grupos: edita o elimina los grupos seleccionados y los miembros.

Puedes configurar una integración para que los permisos de nivel de grupo puedan aplicarse a todos los grupos, grupos específicos seleccionados por el administrador del sistema, o bien permitir que los administradores de grupo habiliten los permisos para sus grupos.

Flujo de instalación para administradores

Cuando la opción Permitir que los administradores de grupo habiliten los permisos para sus grupos está activada, el administrador de un grupo verá una nueva pestaña Integraciones en la pantalla Administrar grupo, la cual le permitirá habilitar la integración en su grupo.

Una app de muestra que ahora puede habilitar el administrador del grupo.

Uso y tokens de app

Cuando crees una nueva app para Workplace, se generará un token de acceso para usarlo con la API Graph, la API de administración de cuentas, o los Webhooks.

Este token de acceso solo se mostrará una vez, así que es importante que lo almacenes en un lugar seguro para usarlo más tarde en el código.

El flujo de restablecimiento de token en una app de integración personalizada

Los tokens de app de Workplace nunca caducan y no necesitan ser actualizados, salvo que hayan sido restablecidos manualmente. Si editas los permisos disponibles para una app determinada, el token ya existente seguirá funcionando; no necesitarás generar uno nuevo.

Si en algún momento necesitas invalidar un token, puedes restablecerlo mediante el botón Restablecer token de acceso en el diálogo Editar app. Se generará un nuevo token, el cual aparecerá visible e invalidará inmediatamente el token anterior.

Seguridad del token

Los tokens de acceso son importantes. Otorgan acceso a los datos de tu empresa en Workplace. Al crear una app, evalúa el conjunto mínimo de permisos necesarios para completar las funciones de integración; no otorgues permisos innecesarios.

Cuando almacenes tokens o los agregues a los repositorios de código, ten mucho cuidado de asegurarte de no compartirlos con las personas equivocadas.

Si quieres agregar una capa de seguridad adicional para las integraciones, puedes agregar una lista de IP permitidas, la cual restringirá el uso del token únicamente a aquellos servidores que aparecen entre las direcciones IP autorizadas.

Incorporación de una lista de IP permitidas para restringir el uso del token a determinados servidores, y requisito de la prueba de clave secreta de la app.

Eliminación automática de permisos sin utilizar

Si una integración personalizada no realiza llamadas con un permiso determinado durante 30 días, dicho permiso será eliminado. Luego de que esta situación ocurra una vez en una integración personalizada, habrá una opción disponible para detener dicho proceso de eliminación.

Si se configuró una suscripción válida a webhooks, los webhooks enviados contarán como una instancia de uso del permiso vinculado.

Controles para la eliminación automática de permisos

Prueba de clave secreta de la app

Los tokens de acceso a Workplace no caducan. Las integraciones personalizadas pueden requerir una prueba de clave secreta de la app para agregar una capa de seguridad adicional. Habilitar la opción "Requerir prueba de clave secreta de la app" garantiza que las llamadas a la API se realizarán únicamente desde el código del servidor. Al realizar llamadas a la API, se requerirá una prueba de clave secreta de la app, junto con el token de acceso.

Para generar una prueba de clave secreta de la app caducable, deberás concatenar el token con una marca de tiempo UNIX separada por una barra vertical | y luego crear un hash SHA-256 de la cadena concatenada usando la clave secreta de la app. A continuación, puedes ver un ejemplo en PHP:

$appsecret_proof = hash_hmac('sha256', $access_token.'|'.time(), $app_secret); 

Para realizar llamadas a la API con la prueba de clave secreta de la app, envía el hash generado a través del parámetro appsecret_proof, junto con el appsecret_time configurado con la marca de tiempo que usaste al cifrar la clave secreta de la app, acompañada del token de acceso.

GET https://graph.facebook.com/v2.9/community/groups?
&access_token={access-token}
&appsecret_proof={appsecret_proof}
&appsecret_time={appsecret_time}

Explorar la funcionalidad de la API con Postman

Postman es una herramienta muy utilizada para trabajar con API de sitios web. Quizás te resulte conveniente explorar la API de Workplace mediante Postman, pero el parámetro $appsecret_proof presenta una complicación: dado que este valor debe ser calculado y expira luego de cinco minutos, la operación puede simplificarse si Postman genera el valor en el momento de la solicitud. Postman puede lograr tal operación mediante sus funciones de scripts previos a la solicitud y de parámetros. Puedes usar el siguiente script como punto de partida:

// Add to Postman's Pre-request Script Tab
var access_token = "replace-me";
var app_secret = "replace-me";
var time = (new Date().getTime()/1000|0);
postman.setEnvironmentVariable("access_token", access_token)
postman.setEnvironmentVariable("appsecret_time", time);
postman.setEnvironmentVariable("appsecret_proof", CryptoJS.HmacSHA256(access_token + '|' + time, app_secret));

1) Crear un entorno activo (no existe uno de forma predeterminada); y luego 2) agregar estos tres parámetros, calculados por tu script previo a la solicitud.