API de Autoridade Remota Prenly

O objetivo do presente documento é explicar:

1. ...como o ecossistema Prenly permite gerir a autenticação e a autorização dos utilizadores utilizando uma infraestrutura técnica pertencente ao editor ou a um terceiro.

2. ...como pode ser efectuada uma implementação técnica através da criação de uma modesta API residual que siga a especificação "Prenly Remote authority API".

Contacto

Para questões ou problemas relacionados com esta API, contacte-nos por correio eletrónico para hello@prenly.com ou por telefone para +46-31-3884740.

Definições

A autenticação é o processo de verificação da identidade de alguém ou de algo, ou seja, se essa pessoa é quem afirma ser, antes de ser concedido o acesso a dados protegidos. Normalmente, isto é feito através do fornecimento de determinadas credenciais, como um nome de utilizador e uma palavra-passe. Dado que as credenciais correspondem a um registo armazenado, o utilizador é "verificado" (autenticado) aplicando o princípio de que o utilizador sabia algo que só o utilizador "real" saberia.

A autorização é o processo de determinar os recursos a que um utilizador tem acesso, ou seja, os dados a que o utilizador está autorizado a aceder e o que pode ou não fazer. Para o Prenly, isto significa determinar quais as publicações que o utilizador pode ver e abrir para ler.

Uma API(Application Program Interface)é um conjunto de rotinas, protocolos e ferramentas para gerir a interação entre diferentes sistemas ou partes de sistemas e dita a comunicação entre sistemas.

Em Prenly, uma autoridade é uma implementação técnica que determina a forma como a autenticação e a autorização são tratadas por uma aplicação Prenly no backend Prenly.

Introdução à API de autoridade remota

A API de autoridade remota da Prenly permite substituir a gestão de autorização e/ou autenticação da Prenly através da implementação de pontos finais da API que seguem uma especificação da API, permitindo a um cliente da Prenly autenticar e autorizar com base no seu sistema, requisitos e necessidades.

Basicamente, isto permite que a autoridade da aplicação Prenly autorize e/ou autentique os utilizadores quando estes interagem com a aplicação Prenly, ou seja, quando lêem publicações numa aplicação, por procuração da API da autoridade remota Prenly.

A autoridade Prenly mediará os pedidos de autenticação e autorização entre os utilizadores e Prenly, não sendo permitida a comunicação direta entre o utilizador e a implementação da API. Em vez disso, a implementação da API informa a autoridade Prenly sobre como agir em relação aos pedidos de autenticação e autorização dos utilizadores.

Implementar a sua API

Compreender como o utilizador utiliza a aplicação Prenly

Aplicações Prenly

O Prenly fornece ao utilizador final aplicações que são principalmente utilizadas para ler publicações e artigos. A aplicação pode ser uma aplicação móvel nativa na plataforma Android ou iOS ou o nosso e-reader baseado na Web. Estes dois tipos de aplicação oferecem uma experiência de utilizador semelhante.

A aplicação pode conter publicações publicadas que são públicas para todos, bem como conteúdos protegidos que requerem alguma forma de autorização para serem consumidos. No caso das aplicações nativas, também é possível permitir que todos os utilizadores não registados consumam gratuitamente determinadas publicações antes de ser necessário iniciar sessão.

Navegar na aplicação

Quando um utilizador utiliza a aplicação, pode normalmente ver a página inicial que contém componentes que apresentam publicações publicadas. As publicações públicas podem ser abertas e lidas selecionando a publicação. No entanto, quando o utilizador tenta abrir uma publicação protegida, a aplicação exige que o utilizador inicie sessão(autenticação).

Após o início de sessão, o Prenly determina se a publicação solicitada é legível para esse utilizador(autorização). Em caso afirmativo, a publicação é aberta e está pronta a ser utilizada. Se o utilizador não tiver acesso de leitura, é notificado na aplicação. O conteúdo protegido não será apresentado, mas o utilizador continuará a ter sessão iniciada.

Em alguns casos, uma aplicação exigirá que o utilizador inicie sessão para ver determinadas publicações, especialmente quando nem todas as publicações publicadas podem ser vistas por qualquer pessoa. Por exemplo, publicações disponíveis através de uma subscrição em que outras publicações publicadas que não são subscritas devem ser ocultadas.

Configuração de um ambiente API

Confiança para pedidos Prenly

A Prenly envia uma chave secreta predefinida em todos os pedidos de autenticação e autorização. A chave só é conhecida por Prenly e pelo seu sistema. Deve verificar se a chave fornecida corresponde à chave esperada para todos os pedidos de API.

Pode também abrir os seus pontos de extremidade da API apenas a determinados endereços IP para maior segurança. Contacte-nos para obter uma lista actualizada dos endereços IP que Prenly utilizará nos pedidos, se pretender esta segurança adicional.

Encriptar o tráfego

Recomendamos vivamente que não permita qualquer tráfego HTTP não encriptado para a sua API. Utilize HTTPS!

Permitir um comportamento do tipo REST

Atualmente, os pedidos Prenly são feitos utilizando HTTP POST, mas a API não deve limitar-se a utilizar quaisquer métodos HTTP para futura expansão do ponto final. Consulte a especificação atual da API para obter mais informações, uma vez que a especificação da API tem a palavra final sobre quaisquer desvios a esta documentação.

Nas respostas da API, os códigos de estado HTTP são utilizados para informar a Prenly do resultado. O utilizador deve ser capaz de responder com diferentes códigos de estado HTTP, tanto para pedidos bem sucedidos como para erros de dados, erros de tempo de execução e erros inesperados do servidor.

Os parâmetros do pedido são atualmente enviados como JSON no corpo do pedido.

Todos os pontos de extremidade respondem atualmente com JSON no corpo da resposta.

Familiarize-se com a OpenAPI 3.0

A especificação da API está documentada num ficheiro yaml de acordo com a norma OpenAPI 3.0 (anteriormente Swagger) e especifica os aspectos técnicos e os requisitos da API e de cada ponto final, incluindo todos os objectos de dados de pedido e resposta.

A documentação gerada automaticamente está disponível em https://apidoc.prenly.com/remote-api/ e o ficheiro de especificação está disponível em https://apidoc.prenly.com/remote-api/spec/v1.3-specification.yaml.

Pode fazer uma cópia do ficheiro de especificação e modificá-lo para os seus pontos de extremidade da API (URLs), uma vez que a especificação gerada automaticamente contém pontos de extremidade genéricos nomeados para referência. Com este ficheiro, pode facilmente construir um ambiente de teste com ferramentas prontas disponíveis em https://openapi.tools/ (consulte a secção "Testes").

Leia mais sobre a OpenAPI, incluindo a especificação, em https://www.openapis.org/.

Criando o ponto de extremidade de autenticação

Consulte a especificação da API em https://apidoc.prenly.com/remote-api/ para obter os pontos finais de autenticação. Pode escolher o URL do ponto final como quiser, mas o ponto final deve seguir a especificação da API.

Parâmetros do pedido

Os parâmetros do pedido fazem parte do pedido como JSON e são enviados pela Prenly para cada pedido.

Resposta em caso de sucesso

Um início de sessão bem sucedido deve responder com o código de estado HTTP 200 e uma resposta JSON com o identificador único do utilizador que foi autenticado.

Resposta em caso de falha

As falhas conhecidas devido aos parâmetros de pedido especificados devem ser respondidas com um dos códigos de estado HTTP 401, 403 ou 412, conforme especificado na documentação da API. Esses erros devem conter uma resposta JSON que segue o modelo de dados Error encontrado na parte inferior de https://apidoc.prenly.com/remote-api/.

Pode optar por fornecer um Erroou um objeto JSON vazio. Atualmente, apenas a propriedade "message" é necessária se fornecer um erro. No entanto, recomenda-se que forneça também uma propriedade "code".

Recomendamos vivamente que defina um valor para a propriedade "message" em inglês que represente o erro de alguma forma. Se o seu software tiver algum tipo de código interno, é aconselhável utilizá-lo aqui, caso seja necessário efetuar uma futura depuração mútua. Não inclua dados pessoais que não sejam necessários, por exemplo, nomes pessoais! As identificações únicas são suficientes para a resolução de problemas.

Esta informação nunca é mostrada ao utilizador final, mas pode ser registada no Prenly para simplificar a resolução de problemas.

Construir o ponto de extremidade para autorização

Consulte a especificação da API em https://apidoc.prenly.com/remote-api/ para obter os pontos finais de autorização. Pode escolher o URL do ponto final como quiser, mas o ponto final deve seguir a especificação da API.

Parâmetros do pedido

Os parâmetros do pedido fazem parte do pedido como JSON e são enviados por Prenly para cada pedido.

Resposta em caso de êxito

Uma recuperação bem sucedida das informações do utilizador deve responder com o código de estado HTTP 200 e uma resposta JSON de acordo com o modelo de dados UserSummary descrito na especificação.

Os campos deste objeto de dados são explicados na parte inferior de https://apidoc.prenly.com/remote-api/.

Para que são utilizadas as propriedades

A única propriedade que atualmente não pode ser deixada em branco é "uid". As outras propriedades podem ser omitidas, mas recomendamos a definição de uma propriedade "productCodes" para controlar melhor se o Prenly deve ou não conceder acesso de leitura às publicações. Atualmente, o Prenly tratará uma propriedade "productCodes" em falta como uma lista vazia.

Resposta em caso de falha

Os erros conhecidos resultantes dos parâmetros de pedido especificados devem ser respondidos com um dos códigos de estado HTTP 403, 404 ou 412, conforme especificado na documentação da API. Esses erros devem conter uma resposta JSON que siga o modelo de dados Error, conforme descrito acima.

Testes

É importante testar a sua implementação para os pontos finais de autenticação e autorização. Consulte https://docs.google .com/document/d/1UxmvDs7_Z0GwGbwCHXr4Ojpb9HaZif1nJ8YRMmztzeo/ para obter mais informações sobre como testar os seus pontos finais.

O que acontece no Prenly?

Quando o utilizador inicia sessão (autenticação + autorização)

Quando o utilizador pede para iniciar sessão e submete o formulário de início de sessão, os dados de início de sessão são enviados para a autoridade Prenly (encriptados com SSL). A partir daí, a autoridade gere a forma de utilizar estas credenciais para autenticar o utilizador. Para a API de autoridade remota, isto significa que as credenciais são enviadas para o ponto de ligação remoto, conforme especificado.

A Prenly processará a resposta da API e tratará os pedidos de autenticação bem e mal sucedidos, em que o utilizador verá um erro dependendo do código de estado HTTP da resposta de erro. Para mais informações, ver abaixo.

Se a autenticação for bem sucedida...

Um início de sessão bem sucedido desencadeia um pedido de autorização separado para o ponto de extremidade da API de autorização para recuperar as informações do utilizador, que são armazenadas em cache no Prenly durante um período de tempo limitado.

A aplicação também mostrará que alguém iniciou sessão, através do nome ou do e-mail, com base nos dados do utilizador que foram devolvidos nas credenciais do utilizador.

Se os dados de início de sessão estiverem incorrectos...

Se o pedido foi tecnicamente bem sucedido, mas as credenciais estavam incorrectas, a autoridade Prenly notificará a aplicação e será apresentada ao utilizador uma mensagem sobre as credenciais incorrectas.

Se algo falhou...

Outros erros baseados no cliente ou no servidor, ou erros de rede, serão detectados e registados por Prenly. A aplicação recebe uma mensagem de erro adequada que é apresentada ao utilizador.

Enquanto o utilizador continua a ler

Armazenamento em cache para pedidos repetidos

O armazenamento em cache dos dados de resposta de uma autorização bem sucedida (as informações do utilizador) elimina a necessidade de pedidos repetidos à API remota para recuperar dados do utilizador que raramente são alterados. Cada cliente Prenly pode escolher o tempo de expiração da cache. Recomendamos que defina 30 minutos, sendo que o tempo mínimo de expiração da cache permitido é de 20 minutos.

Reautorização

A Prenly utilizará o resultado armazenado em cache para cada pedido de autorização, desde que a cache não tenha expirado. Se a cache tiver expirado, Prenly accionará um novo pedido de autorização para o ponto final de autorização na API remota. Este pedido actualizará os dados do utilizador, como a disponibilidade do produto, bem como os dados armazenados em cache.

Tratamento de erros

Se ocorrer um erro do servidor (código HTTP 5xx) quando for acionada uma nova autorização, o tempo de expiração da cache é prolongado por cinco minutos. O Prenly faz isto para evitar que os utilizadores sejam desconectados devido a erros temporários da rede ou do servidor; o utilizador continua a ler como se nada tivesse acontecido e, passados cinco minutos, é feita uma nova tentativa de reautorização. Este comportamento mantém-se enquanto o problema do servidor persistir. A Prenly registará estes problemas técnicos e tentará contactar o cliente se tal acontecer.

Entrada em funcionamento

Quando considerar que a API está pronta para entrar em funcionamento (terminou de desenvolver e testar a sua implementação), contacte-nos para dar os últimos passos.

A Prenly irá solicitar-lhe informações para configurar a sua implementação na Prenly. As informações serão avaliadas e, se tudo estiver em ordem, a sua implementação pode ser utilizada em Prenly para as suas aplicações de papel eletrónico Prenly selecionadas.

Configuração do Prenly

Antes de a sua implementação da API remota poder ser utilizada no Prenly, tem de fornecer

- A chave secreta escolhida para os pontos finais de autenticação e autorização

- Os seus pontos finais de API escolhidos

- Uma lista de produtos a que deve conceder acesso de leitura e para os quais o título Prenly (apenas os produtos conhecidos por Prenly na lista de códigos de produtos do ponto final de autorização podem conceder acesso de leitura)

- O tempo de expiração preferido para a cache

- Um URL onde um novo utilizador pode criar uma conta

- Um URL onde um utilizador pode eliminar a sua conta

- Um URL onde um utilizador pode redefinir a sua palavra-passe (caso se tenha esquecido da palavra-passe)

- Recomendamos que também forneça um URL onde um utilizador autorizado sem códigos de produto previamente conhecidos possa ativar um produto (por exemplo, comprar uma subscrição)

- Credenciais de utilizador (nome de utilizador e palavra-passe) para o utilizador de teste, quando o utilizador é partilhado por Textalk, Apple e Google (se tiver aplicações nativas) quando pelo menos um código de produto tem de permanecer ativo enquanto a API remota for utilizada pela autoridade Prenly para o seu e-paper