adonis-auth

Offical authentication provider for Adonis framework

Usage no npm install needed!

<script type="module">
  import adonisAuth from 'https://cdn.skypack.dev/adonis-auth';
</script>

README

AdonisJs Auth

Version Build Status Coverage Status Downloads License

Gitter Trello Support AdonisJs


AdonisJs Auth is a fully featured authentication system for AdonisJs framework.
It supports by default multiple authentication schemes to authenticate HTTP requests.

  1. Sessions
  2. Basic-Auth
  3. JSON Web Token
  4. API Token

In order to verify users credentials, it makes use of Serializers and below serializers are shipped with this library.

  1. Lucid
  2. Database Provider

You are free to add your own schemes and serializers and documentation for same is written on the official website.




Table of Contents


## Config

Configuration settings are slightly different for each scheme. When you define settings, we call them authenticators.

In short, an authenticator is a combination of scheme, serializer and common settings around them.

Example

// config/auth.js
{
  authenticator: 'session',

  session: {
    // ...
  }
}

Session

session: {
  serializer: 'Lucid',
  scheme: 'session',
  model: 'App/Model/User',
  uid: 'email',
  password: 'password'
}

Basic Auth

basicAuth: {
  serializer: 'Lucid',
  scheme: 'basic',
  model: 'App/Model/User',
  uid: 'email',
  password: 'password'
}

JSON Web Token

jwt: {
  serializer: 'Lucid',
  scheme: 'jwt',
  model: 'App/Model/User',
  secret: Config.get('app.appKey')
}

API Token

Personal api tokens are like passwords for a given account. Majority of API's needs API based authentication because:

  1. Their customers developers want to use the API in order to build something.
  2. Sharing account details with the developer is never secure, so instead they can generate a token and give it to the developer for testing.
{
  serializer: 'Lucid',
  scheme: 'api',
  model: 'App/Model/Token',
  expiry: '30d'
}

Also you need to create the relationship between the user and the token, so that the Lucid serializer can make use of it.

// app/Model/User.js
class User extends Lucid {

  apiTokens () {
    return this.hasMany('App/Model/Token')
  }

}
// app/Model/Token.js
class Token extends Lucid {

  user () {
    return this.belongsTo('App/Model/User')
  }

}

## Setup

In order to make use of the Auth provider, you need to register it inside your bootstrap/app.js file.

Required Setup

const providers = [
  ...,
  'adonis-auth/providers/AuthManagerProvider'
]

Next you need to register the AuthInit middleware. This middleware will create a new instance of Auth Manager and will assign it to the request object.

// app/Http/kernel.js
const globalMiddleware = [
  ...,
  'Adonis/Middleware/AuthInit'
]

and you are good to go. From here you can make use of request.auth to authenticate/login your users.

Usage

// find if a user is logged in
yield request.auth.check()

// attempt to login a user
yield request.auth.attempt('email', 'password')

// login using user object
yield request.auth.login(user)
yield request.auth.loginViaId(1)
yield request.auth.logout()

Automatic Authentication

Auth provider also ships with an extra middleware, which can be assigned to your routes to authenticate them.

// app/Http/kernel.js
const namedMiddleware = {
  auth: 'Adonis/Middleware/Auth'
}

and then inside your routes file you can do.

Using default authenticator

Route
  .get('account', 'AccountsController.index')
  .middleware('auth')

Defining authenticator

Route
  .get('account', 'AccountsController.index')
  .middleware('auth:basic')

## Team Members
## Contribution Guidelines

In favor of active development we accept contributions for everyone. You can contribute by submitting a bug, creating pull requests or even improving documentation.

You can find a complete guide to be followed strictly before submitting your pull requests in the Official Documentation.