NB: Denne artikel findes p.t. kun på engelsk - vi arbejder på en dansk version.
Visiolink can cooperate with your subscription system and grant users access to a publication. When we do so, it is called External User Validation.
The flow of the External User Validation is quite simple and happens in an instant:
Prerequisites for the customer
In order to validate the user-access when sent to the Visiolink Access Server from your website (step2), you need a service that can handle our request for verification (the Validation URL) of the user-access (step 3 and 4). When we call this service (by http request), we expect that you can sort out information and REPLY a simple YES / NO, if the e-pages reader should be opened.
Also, we need a landing page (error URL) when your service replies NO, e.g.: your shop if the user’s subscription has run out.
Implementing External User Validation
The implementation of External User Validation is done in these steps:
- 1. You determine which values should be part of the validation process, e.g. username, e-mail-address. You should note, however, that the validation for device apps is different from the validation for e-pages. The apps include a login/password validation combined with access validation. E-pages only have access validation. This means that for e-pages, the login/password handling occurs on the customer’s side (typically, the user logs on to the customer’s website).
- 2. The description and implementation of the validation is the customer’s responsibility. Typically, an URL in the customer’s system is set up to receive and verify the key string. It should return a positive or negative response depending on whether the user should be granted access to the requested publication or not. A simple format response is preferred. It can be true/false, simple XML or simple JSON. The important thing is that all positive responses are the same every time. Normally Visiolink doesn't parse a response for something other than the expected positive reply.
The Validation URL will typically have the following basic structure: http:// + Verification URL + Key string.
The key string could contain a user ID (a parameter that identifies the user in your system – this must be fixed), a token (usually a session id - must be fixed) and a publication ID or date (to identify the publication that this user wants to view).
For the latter, date is the preferred way to identify a publication, typically formatted as yyyy-mm-dd.
Instead of the date parameter, it is also possible to use a publication id (Visiolink’s catalog id) to identify which publication to open. Since publication id’s are unique among all publications from a customer, we can find the date of the publication based on that. This parameter might be useful if more than one publication is published on a single date.
If the date parameter or catalog id is not set, then the last available publication will be opened.
Other parameters are optional and depend on what is needed for the call back service to grant/reject access for the user in question.
- 3. Send the Verification URL and key string parameter names to Visiolink.
- 4. Based on the received key strings for the validation URL, the structure of the activation URL is determined by Visiolink. An activation URL is a link on the customer’s website that sends a simple GET request to Visiolink’s server. Visiolink uses the parameters from the activation URL and sends the request to the customer’s call back service (by building a validation URL) to verify that the user should be granted access to the requested publication. This is why the activation URL should contain all of the parameters necessary for the call back service to verify that a user should be granted access to the publication when trying to open e-pages on the website.
The activation URL will have the following basic structure:
http:// + prefix.e-pages.dk/?mode=kc& + Key string
The parameter mode=kc is a mandatory switch parameter that is used by the Visiolink server. Visiolink will use the parameters from the activation URL to send a request to the customer’s call back service, which will then respond whether the user should be granted access to the requested publication. If the responsive is positive, the requested publication will be opened, otherwise, the error URL will be called. The error URL could be a special access_denied page, or/and the login page.
The prefix will be supplied by Visiolink.
- 5. When the validation is set up, you can start testing using the activation URL. The activation URL will open the requested publication if the user has access to it, or redirect to the error URL provided by the customer if the permission was not granted.
Visiolink usually validates one publication at the time, but if the user is supposed to have access to all available publications and an access token is used as a parameter, it is important that the access token can be reused for publications from different dates. This means that the access token should not depend on publication identifier parameters such as date or publication id.
- 6. Go live.
Example of key strings used by Visiolink customers
Activation URL on customer site:
When the Visiolink Access Server receives a request like that it:
- Splits the parameters in:
a) uid - the user identifier (12345)
b) skey - the token (abcdsf12345687hjsr)
c) date - the publication identifier (2012-09-20)
d) and the rest of the agreed upon key-value pairs (paper=DAGB2).
- Builds the Validation URL
- Sends a request to that URL, and if it returns a positive response, the publication will open. Otherwise the user will be redirected to an agreed upon error URL.