blank-adonis-apiAuth, licencia MIT.

1. Info
2. Enlaces
3. Instalación
- 3.1. Configuración (.env)
- 3.2. Migraciones
4. Servidor de desarrollo
5. Routes
6. Controllers
- 6.1. Auth
7. Listeners
- 7.1. Auth
8. Middleware
9. Validators

1. Info

API realizada con el framework de Node.js Adonis.js.

> adonis new nombreProyecto --api-only

La intención de este repositorio es la de ahorrarnos tiempo cada vez que queramos iniciar un proyecto API que requiera de autenticación de usuarios.

2. Enlaces

Principales:

Consultados:

Iniciando com AdonisJS: Autenticação JWT e API REST
Adonis Tutorial - JWT Authentication
Lausanne-eSports/api.els.team
How to prevent default html reponse on api only project errors?
- Para visualizar las respuestas en JSON y no html hay que modificar la variable NODE_ENV=development a NODE_ENV=production.
Anexo:Códigos de estado HTTP

3. Instalación

Descargamos el repositorio con git.

> git clone https://github.com/rogerforner/blank-adonis-apiAuth.git nombreProyecto

> cd nombreProyecto

Instalamos las dependencias con npm.

> npm install

Dependencias (package.json):

"dependencies": {
  "@adonisjs/ace": "^5.0.8",
  "@adonisjs/antl": "^2.0.7",
  "@adonisjs/auth": "^3.0.7",
  "@adonisjs/bodyparser": "^2.0.5",
  "@adonisjs/cors": "^1.0.7",
  "@adonisjs/fold": "^4.0.9",
  "@adonisjs/framework": "^5.0.9",
  "@adonisjs/ignitor": "^2.0.8",
  "@adonisjs/lucid": "^6.1.3",
  "@adonisjs/mail": "^3.0.9",
  "@adonisjs/persona": "^1.0.5",
  "@adonisjs/validator": "^5.0.6",
  "sqlite3": "^4.0.6"
},

"sqlite3" cambiará dependiendo del tipo de gestor de base de datos que se vaya a utilizar.

3.1. Configuración (.env)

Copiamos el archivo .env.example a .env e insertamos todos los datos necesarios.

> cp .env.example .env

Generamos la APP_KEY.

> adonis key:generate

Variables propias:

APP_LOCALE= Insertaremos el código de idioma ISO639 tal y como se explica en la documentación de Adonis (Internationalization). El directorio en el que generar más idiomas/traducciones es resources/locales.
MAIL_FROM= Insertaremos el email que queramos que aparezca como remitente. Por ejemplo MAIL_FROM=no-reply@rogerforner.com.
APP_URL_VIEW= URL en la que se encuentren las vistas de nuestra APP. Por ejemplo, no es útil redirigir a nuestra API dado que a través de ésta no se visualizan las vistas.

3.2. Migraciones

Ejecutar el siguente comando para llevar adelante las migraciones.

> adonis migration:run

4. Servidor de desarrollo

> adonis serve --dev

5. Routes

start/routes.js

> adonis route:list

┌───────────────────────────┬──────────┬───────────────────────────────────────────────┬───────────────────────────────┬──────────────────────┬────────┐
│ Route                     │ Verb(s)  │ Handler                                       │ Middleware                    │ Name                 │ Domain │
├───────────────────────────┼──────────┼───────────────────────────────────────────────┼───────────────────────────────┼──────────────────────┼────────┤
│ /                         │ HEAD,GET │ Closure                                       │                               │ /                    │        │
├───────────────────────────┼──────────┼───────────────────────────────────────────────┼───────────────────────────────┼──────────────────────┼────────┤
│ /auth/register            │ POST     │ Auth/RegisterController.store                 │ av:AuthRegister               │ /register            │        │
├───────────────────────────┼──────────┼───────────────────────────────────────────────┼───────────────────────────────┼──────────────────────┼────────┤
│ /auth/verify-email/:token │ POST     │ Auth/RegisterVerifyEmailController.validate   │                               │ /verify-email/:token │        │
├───────────────────────────┼──────────┼───────────────────────────────────────────────┼───────────────────────────────┼──────────────────────┼────────┤
│ /auth/login               │ POST     │ Auth/LoginController.authenticate             │ av:AuthLogin                  │ /login               │        │
├───────────────────────────┼──────────┼───────────────────────────────────────────────┼───────────────────────────────┼──────────────────────┼────────┤
│ /auth/psw-forgot          │ POST     │ Auth/PasswordController.forgotPassword        │                               │ /psw-forgot          │        │
├───────────────────────────┼──────────┼───────────────────────────────────────────────┼───────────────────────────────┼──────────────────────┼────────┤
│ /auth/psw-update/:token   │ PUT      │ Auth/PasswordController.updatePasswordByToken │ av:AuthPasswordByToken        │ /psw-update/:token   │        │
├───────────────────────────┼──────────┼───────────────────────────────────────────────┼───────────────────────────────┼──────────────────────┼────────┤
│ /auth/register-unverified │ POST     │ Auth/RegisterController.unverified            │ auth                          │ /register-unverified │        │
├───────────────────────────┼──────────┼───────────────────────────────────────────────┼───────────────────────────────┼──────────────────────┼────────┤
│ /auth/logout              │ DELETE   │ Auth/LogoutController.deauthenticate          │ auth,verified                 │ /logout              │        │
├───────────────────────────┼──────────┼───────────────────────────────────────────────┼───────────────────────────────┼──────────────────────┼────────┤
│ /auth/profile             │ HEAD,GET │ Auth/ProfileController.currentData            │ auth,verified                 │ /profile             │        │
├───────────────────────────┼──────────┼───────────────────────────────────────────────┼───────────────────────────────┼──────────────────────┼────────┤
│ /auth/profile-update      │ PUT      │ Auth/ProfileController.update                 │ auth,verified,av:AuthProfile  │ /profile-update      │        │
├───────────────────────────┼──────────┼───────────────────────────────────────────────┼───────────────────────────────┼──────────────────────┼────────┤
│ /auth/psw-update          │ PUT      │ Auth/PasswordController.updatePassword        │ auth,verified,av:AuthPassword │ /psw-update          │        │
└───────────────────────────┴──────────┴───────────────────────────────────────────────┴───────────────────────────────┴──────────────────────┴────────┘

Encabezado necesario para las peticiones a la API a través de una ruta protegida con el middleware auth:

Authorization: Bearer tokenUsuario

Es necesario el token del usuario para llevar adelante las peticiones HTTP.

6. Controllers

app/Controllers/Http

6.1. Auth

Controladores utilizados única y exclusivamente para llevar adelante la autenticación de usuarios así como, también, la obtención de los datos del usuario autentificado.

LoginController: Gestionar la autenticación de los usuarios. Devuelve un token cuyo será utilizado para realizar las peticiones HTTP a través del middleware auth.
LogoutController: Gestionar la desautenticación de los usuarios. El equivalente a cerrar la sesión iniciada através del LoginController.
PasswordController: Gestionar todas las peticiones relacionadas con el password:
- Actualizar password a través del método updatePassword ({ request, auth, response }) {}. Útil si el usuario está autentificado (panel de administración).
- Actualizar password (token) a través del método updatePasswordByToken ({ request, params, response }) {}. Útil si el usuario necesita recuperar el password y no tiene acceso (no auth).
- Solicitud de Recuperar password a través del método forgotPassword ({ request }) {}. Conseguiremos el token para el método updatePasswordByToken().
ProfileController: Gestionar todas las peticiones relacionas con el perfil del usuario (email, nombre de usuario, nombre...):
- Obtener datos usuario a través del método currentData ({ auth }) {}.
- Actualizar datos usuario a través del método update ({ request, auth, response }) {}.
RegisterController: Gestionar el registro de un usuario.
- Registrar/Crear el usuario a través del método store ({ request, auth, response }) {}.
- Reenviar email de verificación a través del método unverified ({ auth }) {}.
RegisterVerifyEmailController: Gestionar si un usuario ha verificado su cuenta haciendo clic en el enlace enviado a través de correo electrónico.

7. Listeners

app/Listeners

Los "listeners" son llamados a través de los eventos, cuyos se encuentran en start/events.js. Mirar la documentación de Persona, además de la propia de Adonis (Events).

// start/events.js

Event.on('user::created', 'Auth/SendEmailVerifyEmail.method');
Event.on('forgot::password', 'Auth/SendEmailForgotPassword.method');

7.1. Auth

SendEmailForgotPassword: Enviar un correo electrónico de recuperación de contraseña.
SendEmailVerifyEmail: Enviar un correo electrónico cuando se registra un usuario con la intención de verificar la cuenta.

8. Middleware

app/Middleware

EmailVerified: Controlar el estado de verificación del email del usuario.
ForceJson: Forzar las respuestas en JSON. Por ejemplo, evitar las respuestas de errores en HTML.

9. Validators

app/Validators

AuthLogin: Validar los datos necesarios para efectuar el login/autenticación del usuario.
AuthPassword: Validar los datos necesarios para actualizar el password del usuario (auth - panel de administración).
AuthPasswordByToken: Validar los datos necesarios para actualizar el password del usuario (no auth - recuperar password).
AuthProfile: Validar los datos que forman el perfil del usuario (sin tener en cuenta sus uids).
AuthRegister: Validar los datos necesarios para efectuar el registro de un usuario.

johfermq/blank-adonis-apiAuth