OAuth2

Prenly supports OAuth2 with or without OpenID Connect extension (OIDC) as long as the authorisation server follows the OAuth2 specification RFC 6749. You will likely need an authorisation server that supports OIDC.

Prenly only supports the authorisation grant Authorization Code.

The client Prenly will use in the OAuth2 flow is the e-paper's application authority (a technical implementation that decides how authentication and authorisation are handled by the e-paper application within Prenly's backend).

Prenly will need to know a few things to be able to act as the client for the authorisation flow:

• Optional*. The chosen issuer.
This is only mandatory if you want to use the OpenID Connect extension ID token claim.

• Mandatory. The client ID you want the Prenly authority to use.

• Mandatory. The client secret you want the Prenly authority to use when exchanging the provided authorisation grant for an access token when authenticating the Prenly authority (the client).

• Optional. Scope. You may choose to make Prenly use a space-separated list of scopes defining the issued token's permission. The scope(s) will be used with the authorisation endpoint.

• Optional. State. Prenly supports generating of state in the authorisation request. You may choose to either let Prenly generate a state or make the authority skip it.

• Mandatory. Authorisation endpoint. The Prenly authority will navigate the user agent to this endpoint to initiate the authorisation flow with the authorisation server by logging in the user to obtain the authorisation code grant.

• Mandatory. Token endpoint. The Prenly authority will try to exchange the user's authorisation code for an access token or, if your authorisation server supports it (which is strongly recommended), exchange the user's refresh token for a new access token.

Authentication method. On default, Prenly uses the OIDC's client authentication method client_secret_basic when authenticating with the authorisation server's token endpoint. Prenly also has support for the client authentication method client_secret_post. Please notify Prenly if you require the latter, otherwise the default authentication method will be used.

• Recommended. An external URL to log out the user. The Prenly authority will use the current user's selected user agent to log out the user remotely at the authorisation server.
Prenly is capable of using placeholders in the URL when creating the authorisation request to log out the user by providing the following:

◦ The Client ID;
◦ The logout return URI;
◦ The logout error URI;

Please note that state cannot be used.
An example of a return URI query parameter is "post_logout_redirect_uri".

Currently, only the HTTP method GET is supported for the logout URL.

User ID

The Prenly authority will need to know how to extract the unique user ID after the user has been successfully authorised by the authorisation server.

This unique user ID, if you are using the Prenly Remote authority API, is the `uid` request parameter when requesting the user summary information.

You may choose one of the following methods:

• From a property in the JSON token endpoint response. If you choose this you must inform us of your chosen property name containing the user ID.

• From the OpenID Connect "sub" claim in the signed ID token (as returned by the "id_token" token response property. 
To be able to extract the user ID you must also provide:

◦ Required. The external URL to public keys to validate the ID tokens. This URL must contain a JSON Web Key Set according to JWT standards, which can be referred to as either JKU or JWKS.
◦ Optional. The property name in the user data response that contains a customer number.

• From the "sub" property response from a UserInfo endpoint.
To use this method you must also provide:

◦ Required. The UserInfo endpoint URL. The endpoint is used to fetch basic information about the user by using the user's access token to authorise the request.
◦ Optional. The property name in the user data response that contains a customer number.

Resource server

You may choose a resource server that Prenly supports or you are free to contact us at hello@prenly.com to make a request to Prenly to support your specific resource server as an integration task, which Prenly might support based on a paid development task.

Out of the box, Prenly supports Prenly Remote authority API from version 1.4 or higher as a resource server. See our general information about Prenly Remote authority API for the concept of this API. To implement Prenly Remote authority API as a resource server please see the API specification for the endpoint /oauth2/getUser.

The "resource" Prenly is requesting from the resource server is a list of subscription products associated with the user. The products, in the form of a product code, indicate the user's subscription status where each code is configured to grant read access to publications within your e-paper application.

To grant the correct read access depending on the subscription product you must also inform Prenly which publications the product code authorises read access to. Any unknown product will be ignored.

You might not need a dedicated resource server...

Prenly can bypass a traditional resource server altogether if your UserInfo endpoint is capable of exposing the subscription status of the resource owner – the user.

If your UserInfo endpoint is capable, all you will have to provide is the claim (property name) in the UserInfo endpoint response JSON data.

The claim value must be a JSON list (array) of strings. Each list item represents a subscription product code.

Provide information

When you have all the required information please contact Prenly's customer service at hello@prenly.com with the information. The team will then set up the chosen e-paper application's Prenly authority to use OAuth2 for you.