Prenly Remote Authority API

O objetivo do presente documento é explicar:

1. ...como o ecossistema Prenly permite que a autenticação e a autorização do utilizador sejam tratadas por 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 em repouso 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 diz ser, antes de conceder acesso a dados protegidos. Normalmente, esta verificação é feita através do fornecimento de algumas 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 decidir a que recursos um utilizador tem acesso, ou seja, quais os dados a que o utilizador tem permissão para aceder, ou seja, o que o utilizador pode ou não fazer. No caso da Prenly, trata-se de determinar 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 lidar com a interação entre diferentes sistemas ou partes de sistemas, ditando a comunicação entre sistemas.

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

Introdução

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

No essencial, isto permite que a autoridade da aplicação Prenly autorize e/ou autentique os utilizadores à medida que 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 da Prenly mediará os pedidos de autenticação e autorização entre os utilizadores e a Prenly, não sendo permitida qualquer comunicação direta entre os utilizadores 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 consome a aplicação Prenly

Aplicações Prenly

O Prenly serve o utilizador final com aplicações utilizadas principalmente 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 responsivo 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 necessitam de algum tipo de permissão para serem consumidos. No caso das aplicações nativas, também é possível permitir que qualquer utilizador não registado consuma algumas publicações gratuitamente antes de ser necessário iniciar sessão.

Navegar na aplicação

Ao utilizar a aplicação, um utilizador 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. Mas 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 decidirá se a publicação solicitada pode ser lida por esse utilizador(autorização). Em caso afirmativo, a publicação será aberta, pronta para ser consumida. Se o utilizador não tiver acesso de leitura, será notificado na aplicação. O conteúdo protegido não será mostrado, mas o utilizador continuará a ter sessão iniciada.

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

Configurar um ambiente API

Confiar nos pedidos da Prenly

A Prenly envia uma chave secreta predefinida em todos os pedidos de autenticação e autorização. A chave é conhecida apenas pela 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 segurança adicional. Contacte-nos para obter uma lista actualizada de IPs que a Prenly utilizará nos pedidos, caso pretenda 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 RESTish

Atualmente, os pedidos Prenly são feitos com 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 detalhes, uma vez que a especificação da API tem a palavra final em quaisquer discrepâncias com esta documentação.

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

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

Todos os pontos finais estão atualmente a responder com JSON no corpo da resposta.

Familiarizar-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), indicando 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 é fornecida 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 finais da API (URLs), uma vez que a especificação gerada automaticamente contém pontos finais genéricos nomeados como referência. Com este ficheiro, pode facilmente construir um ambiente de teste com ferramentas prontas fornecidas em https://openapi.tools/ (consulte a secção "Testes").

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

Criar o ponto de extremidade de autenticação

Consulte a especificação da API em https://apidoc.prenly.com/remote-api/ para o(s) ponto(s) de extremidade de autenticação. Pode escolher o URL do ponto final exatamente como desejar; no entanto, o ponto final deve seguir a especificação da API.

Parâmetros do pedido

Os parâmetros do pedido fazem parte do corpo do pedido como JSON e são enviados por 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

Os erros conhecidos, que dependem dos parâmetros de pedido fornecidos, devem responder com um dos códigos de estado HTTP 401, 403 ou 412, conforme especificado na documentação da API. Esses erros devem incluir uma resposta JSON seguindo o modelo de dados Error, que pode ser encontrado especificado 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 forneça um valor de propriedade "message" em inglês que represente o erro de alguma forma. Se o seu software tiver algum tipo de código interno, é adequado utilizá-lo aqui, caso seja necessária uma futura resolução mútua de problemas. Não inclua dados pessoais que não sejam necessários, como 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.

Criar o ponto de extremidade de autorização

Consulte a especificação da API em https://apidoc.prenly.com/remote-api/ para obter o(s) ponto(s) final(is) de autorização. Pode escolher o URL do ponto final exatamente como desejar; no entanto, o ponto final deve seguir a especificação da API.

Parâmetros do pedido

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

Resposta em caso de sucesso

Uma extraçã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, tal como 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, no entanto, recomendamos que especifique uma propriedade "productCodes" para controlar melhor se o Prenly deve ou não conceder permissão 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 que dependem dos parâmetros de pedido fornecidos devem responder com um dos códigos de estado HTTP 403, 404 ou 412, conforme especificado na documentação da API. Esses erros devem incluir uma resposta JSON seguindo 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 seus pontos de extremidade.

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, as credenciais são enviadas para a autoridade da Prenly (encriptadas com SSL). A partir daí, a autoridade trata de como 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 extremidade remoto de acordo com a especificação.

O Prenly processará a resposta da API e tratará os pedidos de autenticação bem sucedidos e falhados, em que o utilizador verá um erro dependendo do código de estado HTTP da resposta a falhas. Para mais pormenores, 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 final da API remota de autorização para obter as informações do utilizador, que são armazenadas em cache na Prenly durante um período de tempo limitado.

A aplicação também reflectirá que alguém iniciou sessão, com nome ou e-mail, com base nos dados do utilizador que foram devolvidos nas informações do utilizador.

Se as credenciais estiverem erradas...

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

Se algo falhou...

Outros erros baseados no cliente ou no servidor, ou erros de rede, são detectados e registados por Prenly. A aplicação será servida com uma mensagem de erro adequada para apresentar ao utilizador.

Quando o utilizador continua a ler

Armazenamento em cache para pedidos repetidos

O armazenamento em cache dos dados de uma resposta de autorização bem sucedida (as informações do utilizador) elimina a necessidade de pedidos repetidos à API remota para obter 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, o Prenly accionará um novo pedido de autorização para o ponto final de autorização na API remota. Isto actualizará os dados do utilizador, tais como a disponibilidade do produto, bem como os dados armazenados em cache.

Tratamento de falhas

Se ocorrer um erro do servidor (código HTTP 5xx) quando a reautorização for acionada, 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 continuará a ler como se nada tivesse acontecido e, passados cinco minutos, será 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 conformidade, a sua implementação poderá ser utilizada no Prenly para as suas aplicações de e-paper Prenly selecionadas.

Configurar o 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 pontos de extremidade da API escolhidos

- Uma lista de produtos que devem conceder permissões de leitura e para os quais o título Prenly (apenas os produtos conhecidos pelo Prenly na lista de códigos de produto do ponto final de autorização podem conceder permissões de leitura)

- O tempo de expiração da cache pretendido

- 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 (no caso de se ter 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 (ou seja, comprar uma subscrição)

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