Skip to main content

Auth using token

What is it?#

This integration allow make an automatic login to specific user when this exist in the database. If the user do not exist, will be create one and login then.

This integration is for automatic synchronous login from customer page to store. Is necessary that the user click link to use for login or create and login automatically. This integration cannot to use for registers user like an API.

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).

https://yout-store.com/auth/token?external-auth-token={new-jwt-token}

Pre-requisites#

Contact us at support@publica.la to get the following data:

  • 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.

How to configure it?#

  1. Create a JWT token:
KeyDescription
issSlug to identify who signs the token. You must use the issuer provided in the previous step
jtiA unique id for the token, could be in UUID V4 format.
expExpiry date of the token, it’s a timestamp expressed in seconds. It
audIdentifies the token destinataire. It must be the string farfalla.
subIt must be the string user
intended_urlAllows 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.
userAn 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.

Example

{
"iss": "publicala", // Slug to identify who signs the token. You must use the issuer provided in the prerequisites step.
"jti": "jnosqixu-waibsvsz8x89wgyxtfdy4x6r", // A unique id for the token, could be in UUID V4 format.
"exp": 1614556800, // 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. https://www.unixtimestamp.com/
"aud": "farfalla", // Identifies the token destinataire. It must be the string farfalla
"sub": "user", // It must be the string user always.
"intended_url": "https://your-store.com/reader/publication-name" // Allows you to configure the destination URL after authenticating the user. You can check how configure this in How use intended url section.
"user": {
"uuid": "44b8cc41-503c-4e76-9144-7193af85384e", // [required ] 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": "example@publica.la", // [optional] Used to identify users within the system and when analyzing usage stats.
"picture_url": "https://image-picture-domain.com/picture.jpg" // [optional] If present it is used as a profile picture.
}
}

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;
  1. In case you need to redirect users to a specific URL inside store such as the publication page or a specific filter you may add the intended_url parameter to your token.
    • If no URL is set the user will be redirected to the main 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.

Troubleshooting#

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://your-library-url.com?external-auth-token-error=invalid-token&external-auth-token-error-details=eyJ0b2tlbiI6eyJleHAiOiJUb2tlbiBlcyBleHBpcmVkIG9yIGBleHBgIGF0dHJpYnV0ZSBub3QgcHJlc2VudC4ifX0=

{
"token": {
"exp": "Token es expired or `exp` attribute not present."
}
}

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. Ex: of an error on the field email inside the object user: https://your-library-url.com?external-auth-token-error=invalid-user&external-auth-token-error-details=eyJlbWFpbCI6WyJUaGUgZW1haWwgbXVzdCBiZSBhIHZhbGlkIGVtYWlsIGFkZHJlc3MuIl19.

{
"email": [
"The email must be a valid email address."
]
}

If you read other error, you need to contact to support for more help.