OAuth2

Prenly suporta OAuth2 com ou sem extensão OpenID Connect (OIDC), desde que o servidor de autorização siga a especificação OAuth2 RFC 6749. É provável que necessite de um servidor de autorização que suporte OIDC.

O Prenly apenas suporta a concessão de autorização Código de autorização.

O cliente que o Prenly utilizará no fluxo OAuth2 é a autoridade da aplicação do papel eletrónico (uma implementação técnica que decide como a autenticação e a autorização são tratadas pela aplicação do papel eletrónico no backend do Prenly).

A Prenly precisa de saber algumas coisas para poder atuar como cliente do fluxo de autorização:

- Opcional*. O emissor selecionado.
Isto só é obrigatório se pretender utilizar a reivindicação de token de ID de extensão OpenID Connect.

- Obrigatório. O ID de cliente que pretende que a autoridade Prenly utilize.

- Obrigatório. O segredo do cliente que pretende que a autoridade de pré-aprovação utilize ao trocar a concessão de autorização fornecida por um token de acesso ao autenticar a autoridade de pré-aprovação (o cliente).

- Opcional. Âmbito. Pode optar por fazer com que o Prenly utilize uma lista de âmbitos, separada por espaços, que define a permissão do token emitido. O(s) âmbito(s) será(ão) utilizado(s) com o ponto final de autorização.

- Opcional. Estado. O Prenly suporta a geração de estado no pedido de autorização. Pode optar por deixar o Prenly gerar um estado ou fazer com que a autoridade o ignore.

- Obrigatório. Ponto de extremidade de autorização. A autoridade Prenly navegará o agente do utilizador até este ponto final para iniciar o fluxo de autorização com o servidor de autorização, iniciando a sessão do utilizador para obter a concessão do código de autorização.

- Obrigatório. Ponto de extremidade do token. A autoridade de gestão prévia tentará trocar o código de autorização do utilizador por um token de acesso ou, se o seu servidor de autorização o suportar (o que é fortemente recomendado), trocar o token de atualização do utilizador por um novo token de acesso.

Método de autenticação. Por defeito, o Prenly utiliza o método de autenticação do cliente do OIDC client_secret_basic ao autenticar-se com o ponto de extremidade do token do servidor de autorização. A Prenly também tem suporte para o método de autenticação de cliente client_secret_post. Se necessitar deste último, informe a Prenly; caso contrário, será utilizado o método de autenticação predefinido.

- Recomendado. Um URL externo para terminar a sessão do utilizador. A autoridade Prenly utilizará o agente do utilizador selecionado do utilizador atual para terminar a sessão do utilizador remotamente no servidor de autorização.
O Prenly pode utilizar marcadores de posição no URL ao criar o pedido de autorização para terminar a sessão do utilizador, fornecendo o seguinte:

◦ O ID do cliente;
◦ O URI de retorno do logout;
◦ O URI de erro de logout;

Tenha em atenção que o estado não pode ser utilizado.
Um exemplo de um parâmetro de consulta de URI de retorno é "post_logout_redirect_uri".

Atualmente, apenas o método HTTP GET é suportado para o URL de fim de sessão.

ID do utilizador

A autoridade Prenly terá de saber como extrair o ID de utilizador único depois de o utilizador ter sido autorizado com êxito pelo servidor de autorização.

Este ID de utilizador único, se estiver a utilizar a API da autoridade remota Prenly, é o parâmetro de pedido `uid` ao solicitar as informações de resumo do utilizador.

Pode escolher um dos seguintes métodos:

- A partir de uma propriedade na resposta do ponto final do token JSON. Se optar por este método, deve informar-nos do nome da propriedade escolhida que contém o ID do utilizador.

- A partir da reivindicação "sub" do OpenID Connect no token de ID assinado (conforme retornado pela propriedade de resposta do token "id_token").
Para poder extrair o ID de utilizador, também tem de fornecer:

◦ Obrigatório. O URL externo para chaves públicas para validar os tokens de ID. Este URL deve conter um conjunto de chaves Web JSON de acordo com as normas JWT, que pode ser referido como JKU ou JWKS.
◦ Opcional. O nome da propriedade na resposta de dados do utilizador que contém um número de cliente.

- A partir da resposta de propriedade "sub" de um ponto de extremidade UserInfo.
Para usar esse método, você também deve fornecer:

◦ Obrigatório. O URL do ponto final UserInfo. O ponto final é utilizado para obter informações básicas sobre o utilizador, utilizando o token de acesso do utilizador para autorizar o pedido.
◦ Opcional. O nome da propriedade na resposta de dados do utilizador que contém um número de cliente.

Servidor de recursos

Pode escolher um servidor de recursos suportado pela Prenly ou pode contactar-nos através do endereço hello@prenly.com para solicitar à Prenly que suporte o seu servidor de recursos específico como uma tarefa de integração, que a Prenly poderá suportar com base numa tarefa de desenvolvimento paga.

De imediato, a Prenly suporta a API de autoridade remota da Prenly a partir da versão 1.4 ou superior como um servidor de recursos. Consulte as nossas informações gerais sobre a API de autoridade remota do Prenly para conhecer o conceito desta API. Para implementar a API de autoridade remota do Prenly como um servidor de recursos, consulte a especificação da API para o ponto final /oauth2/getUser.

O "recurso" que a Prenly solicita ao servidor de recursos é uma lista de produtos de subscrição associados ao utilizador. Os produtos, sob a forma de um código de produto, indicam o estado da subscrição do utilizador, sendo que cada código está configurado para conceder acesso de leitura a publicações na sua aplicação de papel eletrónico.

Para conceder o acesso de leitura correto em função do produto de subscrição, deve também informar a Prenly das publicações a que o código do produto autoriza o acesso de leitura. Qualquer produto desconhecido será ignorado.

Pode não precisar de um servidor de recursos dedicado...

O Prenly pode ignorar completamente um servidor de recursos tradicional se o seu ponto de extremidade UserInfo for capaz de expor o estado da subscrição do proprietário do recurso - o utilizador.

Se o seu ponto de extremidade UserInfo for capaz, tudo o que terá de fornecer é a reivindicação (nome da propriedade) nos dados JSON da resposta do ponto de extremidade UserInfo.

O valor da declaração deve ser uma lista JSON (matriz) de cadeias de caracteres. Cada item da lista representa um código de produto de subscrição.

Fornecer informações

Quando tiver todas as informações necessárias, contacte o serviço de apoio ao cliente da Prenly em hello@prenly.com com as informações. A equipa irá então configurar a autoridade Prenly da aplicação de papel eletrónico escolhida para utilizar o OAuth2 para si.