General information - Validation and Authorization
Visiolink has different ways of validating users on Apps. Which solution is best suited to your needs, depends on your current setup, preferences and price (development time). This guide describes 3 types of app validation: "OAuth 2.0 Setup", "OpenID Connect Setup" and "Standard Visiolink Validation Setup", but if you have some other solution, simply provide us with documentation for your setup, including a description on how the setup works.
A setup always consists of 2 parts, Validation and Authorization.
Validation is always a login and that can be handled in the app. Once a user is logged in, we need to do verification of an active subscription every time a user tries to access restricted content such as a publication and rss news. This is done by exchanging information with the Authorization Server. Read more about this in the Authorization Section below.
OAuth 2.0 Setup
Explanation
OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices. You can read more about it on https://oauth.net/2/
If you need a simple description, read the Community Resources -> OAuth 2.0 Simplified.
What is needed
- Client id
- Client Secret
- Authorize endpoint
- Token endpoint
- Resource endpoint
- Testuser - Minimum one testuser
- REDIRECT_URI
- This has to be set to the following: https://device.e-pages.dk/authenticate/oauth/authorized.php
How it works
The first step of an OAuth 2.0 integration is to get authorization from the enduser. This is done using the Authorization Code for grant type. By accessing the authorize endpoint, which will be loaded inside the app in a webview.
This looks something like this:
https://{DOMAIN}.com/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&state={title/date}
On successful login a code will be redirected back to the app.
Once a code has been received the token endpoint will be called to fetch a access_token and refresh_token. These will then be used to verify access to the selected publication.
The request should look something like this:
https://{DOMAIN}.com/visiolink/app-access?acess_token=XXXXX&date=YYYY-MM-DD
You can then reply with a true/false answer or a json output with the product list / entitlements e.g. {access:”true”, products:”epaper,rss”}
You can read more about The Authorization Setup on the Section below.
OpenID Connect Setup
Explanation
OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.
On apps we use the open source openid connect SDK (AppAuth) https://github.com/openid/
What is needed
You need to provide us with the following information.
- OpenID Connect Discovery (https://server.com/.well-known/openid-configuration)
- Authorize URL : https://{DOMAIN}.com/authorize
- clientID
- clientSecret
- endSessionUrl
- Issuer
- Redirect url e.g. {urlscheme}://login (Ask visiolink about the urlscheme for the app)
- Testuser - Minimum one testuser
How it works
It works much like an OAuth 2.0 integration, but with some differences.
Once the user is logged on, the app can fetch user information, in the form of a access_token and an id_token.
The id_token is a JSON Web Token, which can store information about the end user. As a minimum we need it to contain ssoid and email. Please follow openid connect guidelines on how to build your JWT using the documentation found on openid.net/connect.
Once a user has logged in and an access_token and refresh_token is available in the app, these will then be used to verify access to the selected publication.
The request should look something like this:
https://{DOMAIN}.com/visiolink/app-access?acess_token=XXXXX&date=YYYY-MM-DD
You can then reply with a true/false answer or a json output with the product list e.g. {access:”true”, products:”epaper,rss”}
You can read more about The Authorization Setup on the Section below.
Standard Visiolink Validation Setup
Explanation
Whenever a user attempts to download a publication in an app, a request is made to Visiolink’s server to check for access to the publication. If an external web service validation has been set up, this web service will be called to check for access. If the user credentials are valid they will be stored in the app for future use. These user credentials could be email/password or a subscription number.
The app expects a yes / no answer (or TRUE/FALSE , YES/NO, 0/1). The preferred response from the external web service is a JSON response, but both XML and plain text are also valid options.
A request to your validation service from Visiolink’s servers, could look like this:
For your validation service to be able to answer whether to grant access to the selected publication, it must typically have information to identify the user and the publication trying to be accessed. In the example above we have included the minimum, email, password and publication date.
The request can be made as either a GET or POST request.
Forgotten password
Provide us with a url to your forgotten password link or send us information about how to reset your password using an api call e.g. https://domain.com/forgottenpassword?email=vitec@visiolink.com
In app message
If you want to display a message to the user when e.g. “wrong password“ or “No active subscription” – please include this message in the (JSON) response together with access denied.
Multiple publication titles
If your app includes multiple publication titles - an extra parameter “edition={prefix}” could be included in the request sent from the app to your validation webservice. That way you can control the access to different titles if needed.
HTTP codes: You can only use successful respond codes in HTTP (200 - 299) or validation will fail.
Authorization Setup
After having logged in using one of the above mentioned login types, we need to authorize the access to verify that the user has access when clicking on a publication or trying to access restricted rss news articles.
We do this directly from the visiolink server, towards your Authorization Server.
OAuth 2.0 & OIDC (OpenID Connect)
Once a user has logged in and an access_token and refresh_token is available in the app, these will then be used to verify access to e.g. the selected publication.
The request should look something like this:
https://{DOMAIN}.com/visiolink/app-access?access_token=XXXXX&date=YYYY-MM-DD
You can then reply with a true/false answer or a json output with the product list e.g. {access:”true”, products:”epaper,rss”}
This setup very much depends on how you want to handle / restrict access to a publication.
If you for example have multiple regions in your app, you might have a specific entitlements setup that you need to describe. It’s possible to add the entitlement as a parameter to the app access url, or it can be handled by us if you forward the entitlements as part of the json output.
What we need
- Description of endpoints (url, parameters)
- Description of subscription types / entitlements etc.
- Endpoint outputs explained (json, xml, text etc)
- Provide Postman examples, if possible.
- Test Users - A minimum of one test user pr profile type
Examle of test users:
- known user without access
- known user with full access to all content
- know user with limited access to content – for example access to two out of five papers, access to papers but not to live feed etc
Visiolink will only be able to test and verify scenarios based on the provided test users
Comments