What is it and what is it for?
It is an integration that allows access to users through JWT tokens (secure parameters) that are sent from an external resource to the store. External resources could be for example the intranet of an educational organization or company.
This integration allows automatic login to a specific user when it exists in the store database. If the user does not exist, one will be created and logged in.
It is used for automatic synchronous login from your client's page to the store. To do this, users must click on a link (button or link on the external platform) to automatically log in to the store.
The system has a route /auth/token that looks for a parameter named external-auth-token in 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}
For example: https:// alephdigital.publica.la /auth/token? external-auth-token= eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJwdWJsaWNhbGEiLCJqdGkiOiJqbm9zcWl4dS13YWlic3Zzejh4ODl3Z3l4dGZkeTR4NnIiLCJleHAiOjE2MjM0NTQ3NzgsImF1ZCI6ImZhcmZhbGxhIiwic3ViIjoidXNlciIsInVzZXIiOnsidXVpZCI6ImQ5ZGZiNWNmLWU4MTctNDJkZi1hZDE1LTdmM2U4NTMwNDNkMiIsImVtYWlsIjoiZ29uemFsZXpAdGVzdC5zeW5jcm9taW5kLmNvbSJ9fQ.RvoGxFq9e9uJMehG87Y5ISbaqMz_4wtKBVA
💡 Puede complementarse para asignar permisos de lectura a usuarios mediante Api Orders . Here we share our technical documentation. ⚠️ This integration cannot be used for user registrations as an API.
We recommend you review HERE our technical documentation where we share examples to create JWT tokens with PHP, Python and JavaScript and additional information to solve problems that may arise.
📹 We leave you here a complete instructive.
SETTING:
1. Pre-requisites. Once you have created the JWT token, you must write to [email protected] to provide us with the following information:
redirect_url: URL for redirection in case of failure in the login or registration process.
For example " https://www.alephdigital.publica.la/?libros-digitales=error "
jti – A key that is used during token creation. It is a shared key that is used to sign the tokens. You can get more information in step 2.
For example "&BKcc7<XX:7>~V2A"
⚠️ Do not use the API key that you will find in your Control Panel. Use the one generated in the provided tool or in the preferred website for this step and the following ones.
issuer – Identifies the trusted signer of the token and is used in the token payload data. Here you can place the slug or name of the store.
For example "alephdigital"
2. Create a JWT token. Below we share an example and the references of each key:
To generate a JWT key as explained below you can use the jwt.io tool .
{
"iss" : "publicala" , // Slug para identificar quién firma el token. Debe utilizar el emisor proporcionado en el paso de requisitos previos. Recomendamos sea el nombre de la tienda.
"jti" : "jnosqixu-waibsvsz8x89wgyxtfdy4x6r" , // Una identificación única para el token, podría estar en formato UUID V4. Puedes utilizar Passwords Generator.
"exp" : 1614556800 , // Fecha de vencimiento del token, es una marca de tiempo expresada en segundos. Debe ser 60 segundos en el futuro. La zona horaria utilizada es UTC. Puedes utilizar https://www.unixtimestamp.com/
"aud" : "farfalla" , // Identifica el destino del token. No modificar, siempre debe ser la cadena "farfalla".
"sub" : "usuario" , // No modificar, siempre debe ser la cadena "usuario".
"intended_url" : "https://your-store.com/reader/publication-name" // Le permite configurar la URL de destino después de autenticar al usuario. Puede verificar cómo configurar esto en la sección Cómo usar la URL deseada.
"user" : {
"uuid" : "44b8cc41-503c-4e76-9144-7193af85384e" , // [obligatorio] Es una cadena obligatoria y se utiliza para identificar a cada usuario. Es esencial que sea único para cada usuario, podría ser la identificación de usuario convertida en cadena (por ejemplo, 1234) o un UUID (por ejemplo, eeb78e86-8105-443d-bd28-b2eee1607d52).
"email" : "[email protected]" , // [opcional] Se utiliza para identificar a los usuarios dentro del sistema y al analizar las estadísticas de uso. Si no se incluye, el sistema generará al nuevo usuario.
"picture_url" : "https://image-picture-domain.com/picture.jpg", // [opcional] Si está presente, se utiliza como imagen de perfil.
"accept_terms_and_policies": true // [opcional] Booleano. Se utiliza para aceptar automáticamente los términos y condiciones una vez el usuario ha sido creado.
}
}
key | Description |
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 | Token expiration date, is a timestamp expressed in seconds. You can use this tool to generate it. |
aud | Identifies the destination of the token. It must be the string farfalla. |
sub | It must be the user string . |
intended_url | Allows you to configure the destination URL after authenticating the user. Keep the following considerations in mind:
|
user | An object with the following fields:
|
Helpful tools:
- jwt.io
For future integrations by Token you should always use the same information that you gave us in the first step .
We hope this tutorial has been easy for you and if you have any further questions write to us at [email protected] .