Users Registration & Login

The platform allows the registration and login of users using the following methods.

1. Token Integration

Endpoint

The system has a route /auth/token that searches a parameter named external-auth-token on query strings, cookies or headers. This parameter is a JWT with specific information and signed with a shared key (The algorithm is HS256).

How to create a Token?

Required information

In order to set up the integration we will provide the following information:

  • redirect_url: URL for redirection in case of failure in the process of Login or Registration
  • key: Used during the creation of the token. It's a shared key used to sign the tokens.
  • issuer: Identifies the trusted signer of the token. It is used in the payload data of the token.

Optional:

  • logout_url: URL to where the users are sent in case of logout.

Payload

This are the required parameters to create a token:

  • iss Slug to identify who signs the token. You must use the issuer provided in the previous step.
  • jti A unique id for the token, could be in UUID V4 format.
  • exp Expiry date of the token, it’s a timestamp expressed in seconds. It must be 60 seconds in the future. The time zone used is UTC.
  • aud Identifies the token destinataire. It must be the string farfalla.
  • sub It must be the string user.

  • intended_url Allows you to configure the destination URL after authenticating the user. Take the following considerations into account:

    • If no URL is set the user will be redirected to the mail library /library by default.
    • The dynamic path /redirect-to-latest-issue can be used so that the user always arrives at the last publication.
    • If you want to redirect the user to an specific publication you must use the reader's publication obtained in Control Panel -> Publications. Access control rules are normally evaluated after redirection.

  • user An object with the following fields:

    • uuid It is a required string and is used to identify each user. It is essential that it is unique for each user, it could be the user id casted to string (eg 1234) or a UUID (eg eeb78e86-8105-443d-bd28-b2eee1607d52).
    • email (Optional) Used to identify users within the system and when analyzing usage stats.
    • picture_url (Optional) If present it is used as a profile picture.

The payload data will look as follows:

In the following example we will use a dummy account called “Nación Digital” whose slug will be “naciondigital” and its website URL is https://naciondigital.com.

{
"iss": "naciondigital",
"jti": "jnosqixu-waibsvsz8x89wgyxtfdy4x6r",
"exp": 1540520566,
"aud": "farfalla",
"sub": "user",
"intended_url": URL
"user": {
  "uuid": "44b8cc41-503c-4e76-9144-7193af85384e",
  "email": "example@publica.la",
  "picture_url": "./picture.jpg"
}
}

Token generation snippets:

The following code may be used as example to create JWT tokens.

PHP

use Lcobucci\JWT\Builder;
use Ramsey\Uuid\Uuid;
use Lcobucci\JWT\Signer\Hmac\Sha256;

$tokenSecret = 'ee9a9f38-81b0-40de-8919-23f6ef75ea0d';
$userUuid = 'f1853db8-a9e5-4a38-b1cd-540a7e74d4b8';
$userEmail = 'exampoleuser@gmail.com';
$userPictureUrl = 'https://storage.com/userpci.jpg';

$token = (new Builder())
    ->setIssuer('naciondigital')
    ->setAudience('farfalla')
    ->setId(Uuid::uuid4(), true)
    ->setIssuedAt(time())
    ->setExpiration(time() + 3600)
    ->set('sub', 'user')
    ->set('user', [
        'uuid' => $userUuid,
        'email' => $userEmail,
        'picture_url' => $userPictureUrl,
    ])
    ->sign(new Sha256(), $tokenSecret)
    ->getToken();

$tokenString = (string) $token;

Django

# Example token generation inside a Django view or context processor (note the request parameter used)

import jwt
from time import time
from uuid import uuid4
from django.conf import settings

encoded_token = jwt.encode({
    'iss': 'naciondigital', 'jti': uuid4().hex, 'exp': int(time()) + 60,
    'aud': 'farfalla', 'sub': 'user', 'user': {
        'uuid': str(request.user.id), 'email': request.user.email}
    }, settings.JWT_SECRET, algorithm='HS256')

Node.js

// Example token generation and redirection inside an Express route
const jwt = require('jsonwebtoken');
const uuidv4 = require('uuid/v4');

const libraryUrl = 'https://biblioteca.naciondigital.com';
const tokenSecret = 'ee9a9f38-81b0-40de-8919-23f6ef75ea0d';

router.get('/go-to-library', async (req, res) => {
    try {
        const token = jwt.sign(
            {
                iss: 'naciondigital',
                jti: uuidv4(),
                aud: 'farfalla',
                sub: 'user',
                user: { uuid: req.query.uuid },
            },
            tokenSecret,
            { algorithm: 'HS256' }
          );
        res.redirect(`${libraryUrl}/auth/token?external-auth-token=${token}`);
    } catch (error) {
        console.log('Error trying to generate token', {
            error: error,
            request: req,
        });
        res.status(500).send('error');
    }
});

The resulting URL will be similar to the following: https://biblioteca.naciondigital.com/auth/token?external-auth-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJuYWNpb25kaWdpdGFsIiwianRpIjoiam5vc3FpeHUtd2FpYnN2c3o4eDg5d2d5eHRmZHk0eDZyIiwiZXhwIjoxNTQwNTIwNTY2LCJhdWQiOiJmYXJmYWxsYSIsInN1YiI6InVzZXIiLCJ1c2VyIjp7InV1aWQiOiI0NGI4Y2M0MS01MDNjLTRlNzYtOTE0NC03MTkzYWY4NTM4NGUifX0.xlxgw9wi0zPZXfdWJtc0MljMUKjIX4bjWntd5OokqWs

Where:

  • 'https://biblioteca.naciondigital.com' is the domain of the library
  • '/auth/token' is the endpoint
  • 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJuYWNpb25kaWdpdGFsIiwianRpIjoiam5vc3FpeHUtd2FpYnN2c3o4eDg5d2d5eHRmZHk0eDZyIiwiZXhwIjoxNTQwNTIwNTY2LCJhdWQiOiJmYXJmYWxsYSIsInN1YiI6InVzZXIiLCJ1c2VyIjp7InV1aWQiOiI0NGI4Y2M0MS01MDNjLTRlNzYtOTE0NC03MTkzYWY4NTM4NGUifX0.xlxgw9wi0zPZXfdWJtc0MljMUKjIX4bjWntd5OokqWs' is the generated token.

Error Handling

Any problem with the token or the user will return an error code contained in the redirection URL under the parameter external-auth-token-error.

The know error cases are two:

  • invalid-token:

    A problem with the token. It adds a parameter external-auth-token-details includes a JSON object encoded in base64 with the error’s details:

    Example: https://naciondigital.com/suscripciones/?external-auth-token-error=invalid-token&external-auth-token-error-details=eyJ0b2tlbiI6eyJleHAiOiJUb2tlbiBlcyBleHBpcmVkIG9yIGBleHBgIGF0dHJpYnV0ZSBub3QgcHJlc2VudC4ifX0=

  • invalid-user:

    A problem with the user. It adds a parameter external-auth-token-details includes a JSON object on base64 with the error’s details:

    Example of an error on the field email inside the object user: https://naciondigital.com/suscripciones/?external-auth-token-error=invalid-user&external-auth-token-error-details=eyJlbWFpbCI6WyJUaGUgZW1haWwgbXVzdCBiZSBhIHZhbGlkIGVtYWlsIGFkZHJlc3MuIl19

Users login

The platform allows to provide a way for multiple readers to login through a single access to the platform.

The statistics associated to the activity of the users logged through the following methods will be reflected to only one user in the system.

  • IP: (For now, take a look here)
  • Referrer: (For now, take a look here)