API de autoridad remota previa

El objetivo de este documento es explicar:

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

2. ...cómo se puede realizar una implementación técnica construyendo una modesta API residual 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 algo, es decir, si es quien dice ser, antes de concederle acceso a datos protegidos. Normalmente, esto se hace proporcionando ciertas 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 determinar a qué recursos tiene acceso un usuario, es decir, a qué datos está autorizado a acceder y qué puede o no puede hacer. En el caso de Prenly, esto significa 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, y dicta la comunicación entre sistemas.

En Prenly, una autoridad es una implementación técnica que determina cómo una aplicación Prenly gestiona la autenticación y la autorización en el backend de Prenly.

Introducción

La API de autoridad remota de Prenly ofrece la posibilidad 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 en función de su sistema, requisitos y necesidades.

Básicamente, esto permite a la autoridad de la aplicación de Prenly autorizar y/o autenticar a los usuarios cuando interactúan con la aplicación de Prenly, es decir, cuando leen publicaciones en una aplicación, mediante un proxy 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 el usuario 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 utiliza el usuario la aplicación de Prenly

Aplicaciones de Prenly

Prenly proporciona al usuario final aplicaciones que se utilizan 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 todos, así como contenido protegido que requiere algún tipo de autorización para ser consumido. En el caso de las aplicaciones nativas, también es posible permitir que todos los usuarios que no hayan iniciado sesión consuman determinadas publicaciones de forma gratuita antes de que sea necesario iniciar sesión.

Navegar por la aplicación

Cuando un usuario utiliza la aplicación, normalmente puede ver 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. Sin embargo, 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 determina si la publicación solicitada puede ser leída por ese usuario(autorización). En caso afirmativo, la publicación se abre y queda lista para su uso. Si el usuario no tiene acceso de lectura, se le notifica en 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 ver ciertas publicaciones, especialmente cuando no todas las publicaciones publicadas pueden ser vistas por cualquiera. Por ejemplo, las publicaciones disponibles a través de una suscripción donde otras publicaciones publicadas que no están suscritas deben estar ocultas.

Configuración de un entorno API

Confianza para 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 a determinadas direcciones IP para mayor seguridad. Póngase en contacto con nosotros para obtener una lista actualizada de las direcciones IP que Prenly utilizará en las solicitudes si desea esta seguridad adicional.

Cifrar el tráfico

Le recomendamos encarecidamente que no permita ningún tráfico HTTP sin cifrar a su API. Utilice HTTPS.

Permitir un comportamiento tipo REST

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

En las respuestas de la API, los códigos de estado HTTP se utilizan para informar a Prenly del 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 solicitud se envían actualmente como JSON en el cuerpo de la solicitud.

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 de acuerdo con el estándar OpenAPI 3.0 (anteriormente Swagger) y especifica 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 está disponible en https://apidoc.prenly.com/remote-api/ y el archivo de especificaciones 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 con nombres genéricos como referencia. Con este archivo, puede crear fácilmente un entorno de pruebas con las herramientas disponibles en https://openapi.tools/ (consulte la sección "Pruebas").

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

Creación del 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 a tu gusto, pero el endpoint debe seguir la especificación de la API.

Parámetros de solicitud

Los parámetros de solicitud forman parte 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 fallo

Los fallos conocidos debidos a los parámetros de solicitud especificados deben responderse con uno de los códigos de estado HTTP 401, 403 o 412 especificados en la documentación de la API. Estos errores deben contener una respuesta JSON que siga el modelo de datos Error que se encuentra en la parte inferior de https://apidoc.prenly.com/remote-api/.

Puede elegir entre proporcionar un objeto 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 establezca un valor para la propiedad "message" en inglés que represente el error de alguna manera. Si su software tiene algún tipo de códigos internos, es aconsejable utilizarlos aquí por si en el futuro fuera necesaria una depuración mutua. No incluya datos personales que no sean necesarios, por ejemplo, nombres personales. Los identificadores únicos son suficientes para la resolución de problemas.

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

Creación del 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 punto final como desee, pero el punto final debe seguir la especificación de la API.

Parámetros de solicitud

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

Respuesta satisfactoria

Una recuperación con éxito de la información del usuario debe responder con el código de estado HTTP 200 y una respuesta JSON de acuerdo con 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 puede dejarse en blanco es "uid". Las demás propiedades pueden omitirse, pero recomendamos establecer una propiedad "productCodes" para controlar mejor si Prenly debe conceder o no acceso 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 resultantes de los parámetros de solicitud especificados deben responderse con uno de los códigos de estado HTTP 403, 404 o 412 especificados en la documentación de la API. Estos errores deben contener 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, los datos de inicio de sesión se envían a la autoridad de Prenly (cifrados 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 de conexión remoto especificado.

Prenly procesará la respuesta de la API y gestionará tanto las solicitudes de autenticación correctas como las incorrectas, 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 información.

Si la autenticación fue exitosa...

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

La aplicación también mostrará que alguien ha iniciado sesión, por nombre o correo electrónico, en función de los datos de usuario que se hayan devuelto en las credenciales de usuario.

Si los datos de acceso eran incorrectos...

Si la solicitud fue técnicamente exitosa, pero las credenciales eran incorrectas, la autoridad de 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, serán detectados y registrados por Prenly. La aplicación recibirá un mensaje de error apropiado que se presentará al usuario.

Mientras el usuario sigue leyendo

Almacenamiento en caché de solicitudes repetidas

El almacenamiento en caché de los datos de respuesta de una autorización correcta (la información del usuario) elimina la necesidad de realizar solicitudes repetidas a la API remota para recuperar datos del usuario que raramente cambian. Cada cliente de Prenly puede elegir el tiempo de caducidad de la caché, recomendamos establecer 30 minutos, siendo el tiempo mínimo de caducidad de la caché permitido 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 de 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 debido a errores temporales de la red o del servidor; el usuario sigue leyendo como si nada hubiera pasado, y pasados cinco minutos se realiza un nuevo intento de reautorización. Este comportamiento dura mientras persista el problema en el 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 pasos finales.

Prenly le pedirá información para configurar su implementación en Prenly. La información será evaluada y si todo está en orden, su implementación podrá ser utilizada en Prenly para sus aplicaciones de papel electrónico Prenly seleccionadas.

Configuración de Prenly

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

- Su clave secreta elegida para los puntos finales de autenticación y autorización

- Los puntos finales de API elegidos

- Una lista de productos a los que conceder acceso de lectura y para los que el título de Prenly (sólo los productos conocidos por Prenly de la lista de códigos de producto del punto final de autorización pueden conceder acceso de lectura)

- La hora de caducidad que prefiera para la caché

- 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 (si la ha olvidado)

- Le recomendamos que también proporcione una URL en la que un usuario autorizado sin códigos de producto previamente conocidos pueda activar un producto (por ejemplo, comprar una suscripción)

- credenciales de usuario (nombre de usuario y contraseña) para el usuario de prueba, cuando 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 para su e-paper