Prenly Remote Authority API

El propósito de este documento es explicar

1. ...cómo el ecosistema Prenly permite que la autenticación y autorización de usuarios sea gestionada por una infraestructura técnica propiedad del editor o de un tercero.

2. ...cómo puede realizarse una implementación técnica mediante la creación de una modesta API en reposo que siga la especificación "Prenly Remote authority API".

Contacto

Póngase en contacto con nosotros por correo electrónico en hello@prenly.com o por teléfono en el +46-31-3884740 para cualquier pregunta o problema relacionado con esta API.

Definiciones

Laautenticación es el proceso de verificar la identidad de alguien o de algo, es decir, si es quien dice ser, antes de concederle acceso a datos protegidos. Normalmente, esto se hace proporcionando unas credenciales, como un nombre de usuario y una contraseña. Dado que las credenciales coinciden con un registro almacenado, el usuario es "verificado" (autenticado) aplicando el principio de que el usuario sabía algo que sólo el usuario "real" sabría.

La autorización es el proceso de decidir a qué recursos tiene acceso un usuario, es decir, a qué datos tiene permiso para acceder, es decir, qué puede o no puede hacer el usuario. En el caso de Prenly, se trata de determinar qué publicaciones puede ver y abrir el usuario para leerlas.

Una API(Application Program Interface) es un conjunto de rutinas, protocolos y herramientas para gestionar la interacción entre diferentes sistemas o partes de sistemas, dictando la comunicación de sistema a sistema.

En Prenly, una autoridad es una implementación técnica que decide cómo se gestionan la autenticación y la autorización por parte de una aplicación Prenly dentro del backend de Prenly.

Introducción

La API de autoridad remota de Prenly introduce la capacidad de sustituir la gestión de autorización y/o autenticación de Prenly mediante la implementación de puntos finales de API que siguen una especificación de API, lo que permite a un cliente de Prenly autenticar y autorizar según su sistema, requisitos y necesidades.

En esencia, esto permite a la autoridad de la aplicación de Prenly autorizar y/o autenticar a los usuarios a medida que interactúan con la aplicación de Prenly, es decir, cuando leen publicaciones dentro de una aplicación, por medio de la API de autoridad remota de Prenly.

La autoridad de Prenly mediará en las solicitudes de autenticación y autorización entre los usuarios y Prenly cuando no se permita la comunicación directa entre los usuarios y la implementación de la API. En su lugar, la implementación de la API informa a la autoridad de Prenly sobre cómo actuar ante las solicitudes de autenticación y autorización de los usuarios.

Implementación de la API

Comprender cómo consume el usuario la aplicación de Prenly

Aplicaciones Prenly

Prenly sirve al usuario final con aplicaciones utilizadas principalmente para leer publicaciones y artículos. La aplicación puede ser una aplicación móvil nativa en la plataforma Android o iOS, o nuestro lector electrónico basado en web responsiva. Estos dos tipos de aplicaciones ofrecen una experiencia de usuario similar.

La aplicación puede contener publicaciones que son públicas para todo el mundo, así como contenidos protegidos que necesitan algún tipo de permiso para ser consumidos. En el caso de las aplicaciones nativas, también es posible permitir que cualquier usuario que no haya iniciado sesión consuma gratuitamente algunas publicaciones antes de que sea necesario iniciar sesión.

Navegar por la aplicación

Al utilizar la aplicación, un usuario puede ver normalmente la página de inicio que contiene componentes que muestran las publicaciones publicadas. Las publicaciones públicas pueden abrirse y leerse seleccionando la publicación. Pero cuando el usuario intenta abrir una publicación protegida, la aplicación le pedirá que inicie sesión(autenticación).

Tras iniciar sesión, Prenly decidirá si la publicación solicitada puede ser leída por ese usuario(autorización). En caso afirmativo, la publicación se abrirá, lista para ser consumida. Si el usuario no tiene acceso de lectura, se le notificará dentro de la aplicación. El contenido protegido no se mostrará, pero el usuario seguirá conectado.

En algunos casos, una aplicación requerirá que el usuario inicie sesión para mostrar ciertas publicaciones, especialmente cuando no todas las publicaciones publicadas pueden ser vistas por cualquiera. Por ejemplo, publicaciones accesibles a través de una suscripción en las que otras publicaciones no suscritas deberían estar ocultas.

Configurar un entorno API

Confiar en las solicitudes de Prenly

Prenly envía una clave secreta predefinida en todas las solicitudes de autenticación y autorización. La clave sólo la conocen Prenly y su sistema. Debe comprobar que la clave proporcionada coincide con la clave esperada para todas las solicitudes de API.

También puede abrir sus puntos finales de API sólo para determinadas direcciones IP para mayor seguridad. Póngase en contacto con nosotros para obtener una lista actualizada de las IP que Prenly utilizará en las solicitudes si desea esta seguridad adicional.

Cifrar el tráfico

Le recomendamos encarecidamente que no permita el tráfico HTTP no cifrado a su API. Utilice HTTPS.

Permita un comportamiento RESTish

Actualmente, las solicitudes Prenly se realizan con HTTP POST, pero la API no debería limitarse a utilizar ningún método HTTP para futuras ampliaciones de los puntos finales. Por favor, consulte la especificación actual de la API para más detalles, ya que la especificación de la API tiene la última palabra en cualquier discrepancia con esta documentación.

En las respuestas de la API, los códigos de estado HTTP se utilizan para informar a Prenly sobre el resultado. Usted debe ser capaz de responder con diferentes códigos de estado HTTP, tanto para solicitudes exitosas como para errores de datos, errores de tiempo de ejecución y errores inesperados del servidor.

Los parámetros de petición se pasan actualmente como JSON en el cuerpo de la petición.

Todos los endpoints responden actualmente con JSON en el cuerpo de la respuesta.

Familiarícese con OpenAPI 3.0

La especificación de la API se documenta en un archivo yaml conforme al estándar OpenAPI 3.0 (anteriormente Swagger), en el que se indican los aspectos técnicos y los requisitos de la API y de cada punto final, incluidos todos los objetos de datos de solicitud y respuesta.

La documentación autogenerada se proporciona en https://apidoc.prenly.com/remote-api/ y el archivo de especificaciones está disponible en https://apidoc.prenly.com/remote-api/spec/v1.3-specification.yaml.

No dudes en hacer una copia del archivo de especificaciones y modificarlo para adaptarlo a tus puntos finales de la API (URL), ya que la especificación autogenerada contiene puntos finales genéricos con nombre como referencia. Con este archivo, puede crear fácilmente un entorno de pruebas con las herramientas preparadas que se proporcionan en https://openapi.tools/ (consulte la sección "Pruebas").

Más información sobre OpenAPI, incluida la especificación, en https://www.openapis.org/.

Crear el punto final de autenticación

Consulta la especificación de la API en https://apidoc.prenly.com/remote-api/ para conocer los puntos finales de autenticación. Puedes elegir la URL del endpoint exactamente como desees; sin embargo, el endpoint debe seguir la especificación de la API.

Parámetros de solicitud

Los parámetros de solicitud forman parte del cuerpo de la solicitud como JSON y son enviados por Prenly para cada solicitud.

Respuesta en caso de éxito

Un inicio de sesión correcto debe responder con el código de estado HTTP 200 y una respuesta JSON con el identificador único del usuario que se autenticó.

Respuesta en caso de error

Los errores conocidos que dependen de los parámetros de la solicitud deben responder con uno de los códigos de estado HTTP 401, 403 o 412 especificados en la documentación de la API. Estos errores deben incluir una respuesta JSON siguiendo el modelo de datos Error que puede encontrar especificado en la parte inferior de https://apidoc.prenly.com/remote-api/.

Puede elegir entre proporcionar un Erroro un objeto JSON vacío. Actualmente, sólo se requiere la propiedad "message" si se proporciona un Error. Sin embargo, se recomienda proporcionar también una propiedad "code".

Le recomendamos encarecidamente que proporcione un valor de propiedad "message" en inglés que represente el error de alguna manera. Si su software dispone de algún tipo de códigos internos, es conveniente utilizarlos aquí por si en el futuro fuera necesaria la resolución mutua de problemas. No incluya datos personales que no sean necesarios, como nombres personales. Los identificadores únicos son suficientes para solucionar problemas.

Esta información nunca se muestra al usuario final, pero puede registrarse en Prenly para simplificar la resolución de problemas.

Construir el punto final de autorización

Consulte la especificación de la API en https://apidoc.prenly.com/remote-api/ para conocer los puntos finales de autorización. Puede elegir la URL del endpoint exactamente como desee; sin embargo, el endpoint debe seguir la especificación de la API.

Parámetros de solicitud

Los parámetros de solicitud forman parte del cuerpo de la solicitud como JSON y son enviados por Prenly para cada solicitud.

Respuesta satisfactoria

Una obtención correcta de la información del usuario debe responder con un código de estado HTTP 200 y una respuesta JSON según el modelo de datos UserSummary descrito en la especificación.

Los campos de este objeto de datos se explican en la parte inferior de https://apidoc.prenly.com/remote-api/.

Para qué se utilizan las propiedades

La única propiedad que actualmente no se puede dejar en blanco es "uid". Las demás propiedades pueden omitirse, sin embargo, recomendamos que especifique una propiedad "productCodes" para controlar mejor si Prenly debe o no conceder permiso de lectura a las publicaciones. Actualmente, Prenly tratará una propiedad "productCodes" omitida como una lista vacía.

Respuesta en caso de error

Los errores conocidos que dependen de los parámetros de solicitud dados, deben responder con uno de los códigos de estado HTTP 403, 404 o 412 como se especifica en la documentación de la API. Estos errores deben incluir una respuesta JSON que siga el modelo de datos Error descrito anteriormente.

Pruebas de

Es importante probar la implementación de los puntos finales de autenticación y autorización. Consulte https://docs.google.com/document/d/1UxmvDs7_Z0GwGbwCHXr4Ojpb9HaZif1nJ8YRMmztzeo/ para obtener más información sobre cómo probar sus puntos finales.

¿Qué ocurre en Prenly?

Cuando el usuario inicia sesión (autenticación + autorización)

Cuando el usuario solicita iniciar sesión y envía el formulario de inicio de sesión, las credenciales se envían a la autoridad de Prenly (cifradas con SSL). A partir de ahí, la autoridad gestiona cómo utilizar estas credenciales para autenticar al usuario. Para la API de autoridad remota, esto significa que las credenciales se envían al punto final remoto de acuerdo con la especificación.

Prenly procesará la respuesta de la API y gestionará tanto las solicitudes de autenticación correctas como las erróneas, en las que el usuario verá un error en función del código de estado HTTP de la respuesta de error. Véase más abajo para más detalles.

Si la autenticación ha tenido éxito...

Un inicio de sesión exitoso activará una solicitud de autorización separada al punto final de la API remota de autorización para obtener la información del usuario, que se almacena en caché en Prenly durante un tiempo limitado.

La aplicación también reflejará que alguien ha iniciado sesión, con nombre o correo electrónico en función de los datos de usuario que se hayan devuelto dentro de la información de usuario.

Si las credenciales eran incorrectas...

Si la solicitud fue técnicamente exitosa, pero las credenciales eran incorrectas, la autoridad Prenly notificará a la aplicación y un mensaje acerca de las credenciales incorrectas será presentado al usuario.

Si algo falló...

Otros errores basados en el cliente o el servidor, o errores de red, son detectados y registrados por Prenly. La aplicación será servida con un mensaje de error adecuado para presentar al usuario.

Cuando el usuario sigue leyendo

Almacenamiento en caché de solicitudes repetidas

El almacenamiento en caché de los datos de una respuesta de autorización correcta (la información del usuario) elimina la necesidad de realizar solicitudes repetidas a la API remota para obtener datos del usuario que rara vez se modifican. Cada cliente de Prenly puede elegir el tiempo de expiración de la caché, recomendamos establecer 30 minutos, donde el tiempo mínimo permitido de expiración de la caché es de 20 minutos.

Reautorización

Prenly utilizará el resultado almacenado en caché para cada solicitud de autorización siempre que la caché no haya caducado. Si la caché ha caducado, Prenly lanzará una nueva solicitud de autorización al punto final de autorización en la API remota. Esto actualizará los datos del usuario, como la disponibilidad del producto, así como los datos almacenados en caché.

Gestión de errores

Si se produce un error del servidor (código HTTP 5xx) cuando se activa la reautorización, el tiempo de caducidad de la caché se prolonga cinco minutos. Prenly hace esto para evitar que los usuarios se desconecten por errores temporales de la red o del servidor; el usuario seguirá leyendo como si no pasara nada y, pasados cinco minutos, se realiza un nuevo intento de reautorización. Este comportamiento dura mientras persista el problema del servidor. Prenly registrará estos problemas técnicos e intentará ponerse en contacto con el cliente si esto ocurre.

Puesta en marcha

Cuando considere que la API está lista para entrar en funcionamiento (ha terminado de desarrollar y probar su implementación), póngase en contacto con nosotros para dar los últimos pasos.

Prenly le pedirá información para configurar su implementación en Prenly. La información será evaluada y, si todo es correcto, su implementación podrá ser utilizada en Prenly para las aplicaciones de e-paper Prenly que usted elija.

Configuración de Prenly

Antes de que su implementación de la API remota pueda utilizarse en Prenly, debe proporcionar:

- La clave secreta que haya elegido para los puntos finales de autenticación y autorización.

- Los puntos finales de API elegidos

- Una lista de productos que deben conceder permisos de lectura y para los que Prenly es titular (sólo los productos conocidos por Prenly incluidos en la lista de códigos de producto del punto final de autorización pueden conceder permisos de lectura).

- El tiempo de caducidad de la caché que desee

- Una URL donde un nuevo usuario pueda crear una cuenta

- Una URL donde un usuario pueda eliminar su cuenta

- Una URL donde un usuario pueda restablecer su contraseña (en caso de que la haya olvidado)

- Le recomendamos que también proporcione una URL en la que un usuario autorizado sin códigos de producto Prenly-known pueda activar un producto (es decir, comprar una suscripción)

- Credenciales de usuario (nombre de usuario y contraseña) para el usuario de prueba, donde el usuario es compartido por Textalk, Apple y Google (si tiene aplicaciones nativas) donde al menos un código de producto debe permanecer activo mientras la API remota sea utilizada por la autoridad Prenly de su e-paper