Funcionalidades de cliente PC

A continuación se detallan comportamientos adicionales a Timer que se relacionan únicamente con el cliente PC.

Inicio de sesión maestro

En caso de requerir el desbloqueo manual de una PC por parte de un asistente, es posible ingresar directamente a la PC para terminarla y liberar el equipo del bloqueo de la aplicación. Dicho ingreso es efectuado proporcionando una llave de ingreso maestra a la aplicación y así liberando el uso de la misma.

A continuación, se indica el comportamiento seguido para actualizar y hacer uso de la clave de ingreso maestra.

Inicialización de clave

El valor de clave maestra es proporcionado durante la inicialización del servidor Onsite, mismo que debe ser cifrado para su almacenamiento con el algoritmo AES-256, siendo la llave el secret del Access Key del usuario.

El arranque inicial del servidor debe abortarse si se presenta alguno de los siguientes casos al validar la clave maestra:

  • Si la longitud de la cadena está fuera del rango [6, 10].
  • Si la cadena contiene algún carácter no alfanumérico.
  • Si no cuenta con al menos una cadena y al menos un número.

Actualización de clave

Flujo

Onsite: PUT /master_key

Autorización: User (super, onsite)

Actualiza el valor de la clave maestra en el sistema, cifrada con el algoritmo AES-256, y siendo la llave el secret del Access Key asociado a la sucursal. El cuerpo de la petición es el siguiente:

key: alejandra

La ruta responde con el estado 204 No Content, indicando así que el cambio de clave fue exitoso. Si se desea modificar la clave dentro del horario operativo de la sucursal, se responde con el estado 403 Forbidden. Adicionalmente, se responde con el estado 400 Bad Request si se presenta alguno de los siguientes casos:

  • Si la longitud de la cadena está fuera del rango [6, 10].
  • Si la cadena contiene algún carácter no alfanumérico.
  • Si no cuenta con al menos una cadena y al menos un número.

Consulta y uso de clave

Flujo

Onsite: GET /master_key

Autorización: User (super, onsite)

Solicita al servidor Onsite la clave maestra en texto plano. La ruta responde con el estado 200 OK acompañado de la siguiente información:

key: alejandro
Onsite: GET /master_key/aes

Autorización: Timer

Solicita al servidor Onsite la clave maestra. En consecuencia, Onsite cifra la clave usando el algoritmo AES-256, y siendo la llave el secret del Access Key asociado al Timer. La ruta responde con el estado 200 OK acompañado de la siguiente información:

hashedKey: JjLLTagic1w236OCia03Mg==

El cliente debe ejecutar esta petición al inicio de la operación de la aplicación, y una respuesta exitosa debe ser un prerrequisito para el lanzamiento de ésta. En caso de solicitarse un inicio de sesión maestro en el cliente PC, se sigue uno de los siguientes casos:

  1. Si el cliente PC cuenta con comunicación hacia Onsite, se lleva a cabo la petición y el resultado es almacenado localmente.
  2. Si no es posible lograr comunicación con Onsite, el cliente PC verifica la contraseña ingresada por el asistente contra aquella almacenada desde el inicio de la aplicación.

En cualquier caso, la falta de coincidencia entre la clave almacenada y aquella introducida deniega el ingreso maestro a un cliente PC.

Obtención de tweets

El cliente PC posee la funcionalidad de mantener al tanto al usuario de los tweets publicados por la cuenta arenaplace2play. El proceso que se describe a continuación plantea la manera de obtener los tweets, guardarlos en memoria en el servidor Offsite y, posteriormente, devolverlos al cliente PC que lo solicite.

La documentación del API de Twitter puede ser consultada en Twitter Developer Documentation. Twitter provee a los desarrolladores con una consola de pruebas en API Console.

Autenticación Offsite - Twitter

Para el siguiente flujo se requiere que el servidor Offsite cuente con las llaves consumer key y secret, los cuales son configurados al momento de la instalación y por motivos de seguridad no son incluidos en el presente documento. Una descripción más detallada del flujo se proporciona en Application-only authentication.

Descripción general

_images/offsite_twitter_auth_overview.svg
  1. El servidor Offsite codifica su llave y su secreto en una única en base 64 para posteriormente solicitar al API Twitter un cambio de estas credenciales por un bearer token.
  2. El API Twitter responde con un bearer token, mismo que Offsite usará en peticiones subsecuentes al API REST para autenticarse.

Flujo

_images/offsite_twitter_auth_sequence.svg

Las llaves consumer key y password son codificadas para obtener un bearer token de la siguiente manera

  1. Codificar las llaves en formato URL. Este paso no es requerido debido al formato actual de las llaves, pero debe ser tomado en cuenta en caso de que Twitter actualice el formato de las mismas.
  2. Concatenar el consumer key codificado, un caracter de dos puntos (:), y el secret codificado.
  3. Codificar usando base 64 la cadena del paso anterior.

Posteriormente, debe invocarse la ruta

Twitter API: POST /oauth2/token

Mediante la cual se obtiene un bearer token asociado a la pareja (consumer key, password).

La petición debe llevar como body la cadena grant_type=client_credentials y como encabezados los siguientes valores

Encabezado Valor
Authorization Basic <cadena codificada en base 64>
Content-Type application/x-www-form-urlencoded;charset=UTF-8

Si la operación fue exitosa, el API responde con el estado 200 OK acompañado del token solicitado en el siguiente formato

{
  "token_type": "bearer",
  "access_token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/AAAAAAAAAAAAAAAAAAAA=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}

Consulta de tweets desde Offsite

Para el siguiente flujo se requiere que el servidor Offsite cuente con un bearer token como se describe en la sección anterior; esto con el fin de autenticar sus peticiones. Una biblioteca para node.js con funciones de cliente hacie el API de Twitter puede consultarse aquí.

Descripción general

_images/offsite_tweet_fetch_overview.svg
  1. El servidor Offsite solicita los n últimos tweets generados por la cuenta arenaplace2play.
  2. El API de Twitter devuelve los tweets solicitados y son almacenados localmente por Offsite.

Flujo

Se hace uso de la ruta https://api.twitter.com/1.1/statuses/user_timeline.json para obtener los tweets del usuario que se indique como screen_name. Un ejemplo de la petición haciendo uso de la biblioteca twitter de node.js como sigue

var params = {screen_name: 'arenaplace2play'};
client.get('statuses/user_timeline', params, function(error, tweets, response) {
  if (!error) {
    console.log(tweets);

    // Write tweets to file
  }
});

Las peticiones a la ruta statuses/user_timeline deben efectuarse con los siguientes parámetros

Parámetro Valor Función
screen_name arenaplace2play El nombre del usuario para el cual devolver resultados
trim_user true Para devolver una versión reducida de datos del usuario
count 30 Solicita los 30 últimos tweets
since_id Ver nota Para devolver resultados a partir de un índice

Nota

Con el objetivo de solicitar únicamente los tweets con los que no cuenta el servidor Offsite y no redundar información, se hace uso del campo since_id. El valor de dicho campo debe corresponder con el identificador del último tweet con el que se cuente en el sistema. El campo since_id es excluyente, esto es, el tweet a partir del cual se solicita nueva información no es incluido en la respuesta. Como excepción, el tweet referenciado en since_id es incluido si el número de tweets solicitados en el campo count excede el disponible. En caso de tratarse de la primera petición para obtener tweets, el campo since_id es omitido.

La respuesta de Twitter al solicitar el histórico de tweets sigue el siguiente formato

[{
  "created_at": "Mon Jan 23 01:13:25 +0000 2017",
  "id": 823337809763299300,
  "id_str": "823337809763299328",
  "text": "“Does anyone claim to have a particularly fine Jenkins install that I can steal? Something they’re...” https://t.co/9VxglBOJAB",
  "truncated": false,
  "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": [{
          "url": "https://t.co/9VxglBOJAB",
          "expanded_url": "https://tmblr.co/ZLYJno2HWjQuu",
          "display_url": "tmblr.co/ZLYJno2HWjQuu",
          "indices": [
              103,
              126
          ]
      }]
  },
  "source": "<a href="
  http: //www.tumblr.com/" rel="nofollow">Tumblr</a>",
      "in_reply_to_status_id": null,
  "in_reply_to_status_id_str": null,
  "in_reply_to_user_id": null,
  "in_reply_to_user_id_str": null,
  "in_reply_to_screen_name": null,
  "user": {
      "id": 37792401,
      "id_str": "37792401"
  },
  "geo": null,
  "coordinates": null,
  "place": null,
  "contributors": null,
  "is_quote_status": false,
  "retweet_count": 0,
  "favorite_count": 0,
  "favorited": false,
  "retweeted": false,
  "possibly_sensitive": false,
  "lang": "en"
}]

Los tweets recibidos en el formato anterior deben ser recortados para almacenar únicamente la información requerida por el cliente. Un objeto tweet recortado será almacenado en la base de datos tomando en cuenta únicamente los siguientes campos

{
  "created_at": "Mon Jan 23 01:13:25 +0000 2017",
  "id": 823337809763299300,
  "id_str": "823337809763299328",
  "text": "“Does anyone claim to have a particularly fine Jenkins install that I can steal? Something they’re...” https://t.co/9VxglBOJAB",
  "truncated": false
}

El servidor Offsite contará en todo momento con 30 tweets disponibles al cliente PC. Si la cantidad de tweets en el archivo es mayor a 30, se eliminan los tweets más antiguos para mantener el número.

El servidor Offsite realizará una consulta al API de Twitter no más de una vez cada 5 minutos. De haber transcurrido menos de 5 minutos de una petición de tweets por parte de un cliente PC, Offsite devolverá el caché sin consultar Twitter.

Consulta de tweets desde PC

Un cliente PC solicita periódicamente al servidor Offsite los tweets almacenados en el servidor. A continuación se describe el proceso de consulta de tweets.

Descripción general

_images/pc_tweet_fetch_overview.svg
  1. El cliente de PC realiza una consulta al servidor Offsite para obtener los últimos tweets para mostrar al usuario.
  2. Offsite consulta con el API de Twitter si existen nuevos tweets generados por la cuenta predefinida. En caso de ser así, el servidor actualiza su archivo de tweets.
  3. Offsite devuelve el caché de tweets al cliente PC.

Flujo

_images/pc_tweet_fetch_overview.svg
Offsite: GET /tweet_timeline

Autorización: Timer

Mediante este ruta, se consultan los 30 últimos tweets generados por la cuenta arenaplacetoplay. Esta ruta responde con el estado 200 OK acompañado de los tweets ordenados de manera decreciente por fecha siguiendo el siguiente formato

[{
  "id": 8,
  "createdAt": "Mon Jan 23 01:13:25 +0000 2017",
  "tid": 823337809763299300,
  "tidStr": "823337809763299328",
  "text": "“Does anyone claim to have a particularly fine Jenkins install that I can steal? Something they’re...” https://t.co/9VxglBOJAB",
  "truncated": false
}]

De ocurrir un error de comunicación con el servidor de Twitter, la ruta responde con los últimos tweets en la memoria de Offsite.

Restricciones sobre la consulta de tweets

Twitter impone una restricción de un máximo de 1500 consultas por ventana de tiempo de 15 minutos, por lo que una cantidad de consultas mayor a esta cantidad devolverá un error. Como consecuencia, se devolverá al cliente de PC el contenido del caché de tweets.

Los errores sobre operaciones no permitidas son devueltos por Twitter con el estado 403 Forbidden y un objeto de error en el cuerpo como el siguiente

{
  "errors": [{
      "code": 99,
      "label": "authenticity_token_error",
      "message": "Unable to verify your credentials"
  }]
}