> adonis install @adonisjs/allyYou are viewing the legacy version of AdonisJS. Visit https://adonisjs.com for newer docs. This version will receive security patches until the end of 2021.
Ally is a 1st party social authentication provider for AdonisJs.
Using Ally makes it trivial to authenticate users via 3rd party websites like Google, Twitter, and Facebook.
The Ally Provider supports the following drivers:
Facebook (facebook)
Github (github)
Google (google)
Instagram (instagram)
Linkedin (linkedin)
Twitter (twitter)
Foursquare (foursquare)
As the Ally Provider is not installed by default, we need to pull it from npm:
> adonis install @adonisjs/allyNext, register the provider inside the start/app.js file:
const providers = [
'@adonisjs/ally/providers/AllyProvider'
]
Social authentication configuration is saved inside the config/services.js file, which is created by the adonis install command when installing the Ally Provider.
|
Your config must be stored inside the config/services.js file’s ally object:
module.exports = {
ally: {
facebook: {}
}
}| You can always access the latest config source file on Github. |
Let’s start with a basic example of logging in using Facebook.
First, we need to register routes to redirect the user to Facebook then handle the response when the user is redirected back from Facebook:
Route.get('login/facebook', 'LoginController.redirect')
Route.get('facebook/callback', 'LoginController.callback')| Make sure the Auth Provider and auth-related middleware is configured correctly. |
Next, we need to create the controller to implement our route methods:
> adonis make:controller Loginconst 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 now have a fully working login system in a few lines of code!
Ally’s API is consistent across drivers, so it’s easy to swap facebook with google or any other driver required by your application.
Below is the list of available functions.
Get redirect URL back as a string:
const url = await ally.driver('facebook').getRedirectUrl()
return view.render('login', { url })Define runtime scopes before redirecting the user:
await ally
.driver('facebook')
.scope(['email', 'birthday'])
.redirect()| Check the relevant provider’s official OAuth documentation for a list of their available scopes. |
Fields to be fetched when getting the authenticated user profile:
await ally
.driver('facebook')
.fields(['username', 'email', 'profile_pic'])
.getUser()Get the user profile of an authenticated user (returns an AllyUser instance):
await ally
.driver('facebook')
.fields(['email'])
.getUser()Returns the user details using the accessToken:
await ally.getUserByToken(accessToken)This is helpful when using client-side code to perform the OAuth action and you have access to the accessToken.
The accessSecret parameter is required when the OAuth 1 protocol is used (e.g. Twitter relies on OAuth 1).
|
Below is the list of available methods on an AllyUser instance.
Returns the user email:
user.getEmail()
Some 3rd party providers do not share email, in which case this method returns null.
|
Returns the access token which may be used later to update the user profile:
user.getAccessToken()Refresh token to be used when access token expires:
user.getRefreshToken()| Available only when 3rd party provider implements OAuth 2. |
Access token expiry data:
user.getExpires()| Available only when 3rd party provider implements OAuth 2. |
Returns token secret:
user.getTokenSecret()| Available only when 3rd party provider implements OAuth 1. |