You are viewing the legacy version of AdonisJS. Visit for newer docs. This version will receive security patches until the end of 2021.

Social authentication

Adonis Ally is a social authentication provider for AdonisJs. It makes it super easy to authenticate users via 3rd party websites like Facebook, Twitter, Google, so on, with minimum efforts.

Here is the list of supported drivers

  • Facebook

  • Github

  • Google

  • Instagram

  • Linkedin

  • Twitter

  • Foursquare


Since ally is not installed by default, we need to install it from npm.

adonis install @adonisjs/ally

Next, register the provider inside start/app.js file.

const providers = [


Installing ally using adonis install command creates the config/services.js file if one does not exists. However, you can always access the latest configuration from github.

The configuration must be stored inside config/services.js file, under an object called ally.

module.exports = {
  ally: {
    facebook: {}

Basic Example

Let’s start with a basic example of Login using Facebook.

Route.get('login/facebook', 'LoginController.redirect')
Route.get('facebook/callback', 'LoginController.callback')

We registered a couple of routes, to redirect the user to Facebook and then handle the response when the user is redirected back from Facebook.

Make sure the auth provider and middleware is configured correctly.
adonis make:controller Login
const User = use('App/Models/User')

class LoginController {
  async redirect ({ ally }) {
    await ally.driver('facebook').redirect()

  async callback ({ ally, auth }) {
    try {
      const fbUser = await ally.driver('facebook').getUser()

      // user details to be saved
      const userDetails = {
        email: fbUser.getEmail(),
        token: fbUser.getAccessToken(),
        login_source: 'facebook'

      // search for existing user
      const whereClause = {
        email: fbUser.getEmail()

      const user = await User.findOrCreate(whereClause, userDetails)
      await auth.login(user)

      return 'Logged in'
    } catch (error) {
      return 'Unable to authenticate. Try again later'

We have a fully working login system in a few lines of code. The API is consistent across all the drivers, so it is easier to swap facebook with google or some other one.

Ally API

Below is the list of available functions.


Redirect user to the 3rd party website

await ally.driver('facebook').redirect()


Get redirect URL back as a string over redirecting the user.

const url = await ally.driver('facebook').getRedirectUrl()

return view.render('login', { url })


Define runtime scopes before redirecting the user.

You must check the official OAuth documentation of the provider to get a list of available scopes.
await ally
  .scope(['email', 'birthday'])


Fields to be fetched when getting authenticated user profile.

await ally
  .fields(['username', 'email', 'profile_pic'])


Get user profile of an authenticated user. An instance of AllyUser is returned.

User API

Below is the list of available methods on a user instance.


Returns the user name

const user = await ally



Returns the user email.

Some 3rd party providers do not share email, in which case this method returns null.


Returns the nick name/display name of the user.



Returns public URL to the profile picture



Returns the access token which may be used later to update the user profile.



Refresh token to be used when access token expires. Available only when 3rd party provider implements OAuth2.



Access token expiry data. Available only when 3rd party provider implements OAuth2.



Returns token secret. Available only when 3rd party provider uses OAuth1.



Original payload returned by the 3rd party provider.