Version: 2.1.2 (latest)

Authentification Sociale

You are reading the documentation for version 2 of FoalTS. Instructions for upgrading to this version are available here. The old documentation can be found here.

FoalTS social authentication is based on OAuth2 protocol. To set up social authentication with Foal, you first need to register your application to the social provider you chose (Google, Facebook, etc). This can be done through its website.

Usually your are required to provide:

  • an application name,
  • a logo,
  • and redirect URIs where the social provider should redirect the users after successful authentication (ex: http://localhost:3001/signin/google/callback, https://example.com/signin/facebook/callback)

Once done, you should receive:

  • a client ID that is public and identifies your application,
  • and a client secret that must not be revealed and can therefore only be used on the backend side.

You must obtain a client secret. If you do not have one, it means you probably chose the wrong option at some point.

Configuration#

First install the appropriate package.

npm install @foal/social

Then, you will need to provide your client ID, client secret and your redirect URIs to Foal. This can be done through the usual configuration files.

default.yml

settings:
social:
google:
clientId: xxx
redirectUri: 'http://localhost:3001/signin/google/callback'

production.yml

settings:
social:
cookie:
secure: true # In production, your website should use HTTPS.
google:
redirectUri: 'https://example.com/signin/google/callback' # Your redirect URI in production

.env

SETTINGS_SOCIAL_GOOGLE_CLIENT_SECRET=yyy

Social Providers#

Authentication is managed by social providers. These are services whose methods can be called within a controller to build a social login.

// 3p
import {
Context,
dependency,
Get,
HttpResponseRedirect,
} from '@foal/core';
import { GoogleProvider } from '@foal/social';
import { User } from '../entities';
export class AuthController {
@dependency
google: GoogleProvider;
@Get('/signin/google')
redirectToGoogle() {
// Your "Login In with Google" button should point to this route.
// The user will be redirected to Google auth page.
return this.google.redirect();
}
@Get('/signin/google/callback')
async handleGoogleRedirection(ctx: Context) {
// Once the user gives their permission to login with Google, the provider
// will redirect the user to this route. This route must match the redirect URI.
const { userInfo, tokens } = await this.google.getUserInfo(ctx);
// Do something with the user information AND/OR the access token.
// If you only need the access token, you can call the "getTokens" method.
// The method usually ends with a HttpResponseRedirect object as returned value.
}
}

You can also override the scopes in the redirect method:

return this.google.redirect({ scopes: [ 'email' ] });

Additional parameters can passed to the redirect and getUserInfo methods depending on the provider.

Google#

Service nameDefault scopesAvailable scopes
GoogleProvideropenid, profile, emailGoogle scopes

Register an OAuth application#

Visit the Google API Console to obtain a client ID and a client secret.

Redirection parameters#

The redirect method of the GoogleProvider accepts additional parameters. These parameters and their description are listed here and are all optional.

Example

this.google.redirect({ /* ... */ }, {
access_type: 'offline'
})

Facebook#

Service nameDefault scopesAvailable scopes
FacebookProvideremailFacebook permissions

Register an OAuth application#

Visit Facebook's developper website to create an application and obtain a client ID and a client secret.

Redirection parameters#

The redirect method of the FacebookProvider accepts an additional auth_type parameter which is optional.

Example

this.facebook.redirect({ /* ... */ }, {
auth_type: 'rerequest'
});
NameTypeDescription
auth_type'rerequest'If a user has already declined a permission, the Facebook Login Dialog box will no longer ask for this permission. The auth_type parameter explicity tells Facebook to ask the user again for the denied permission.

User info parameters#

The getUserInfo and getUserInfoFromTokens methods of the FacebookProvider accept an additional fields parameter which is optional.

Example

const { userInfo } = await this.facebook.getUserInfo(ctx, {
fields: [ 'email' ]
})
NameTypeDescription
fieldsstring[]List of fields that the returned user info object should contain. These fields may or may not be available depending on the permissions (scopes) that were requested with the redirect method. Default: ['id', 'name', 'email'].

Github#

Service nameDefault scopesAvailable scopes
GithubProvidernoneGithub scopes

Register an OAuth application#

Visit this page to create an application and obtain a client ID and a client secret.

Additional documentation on Github's redirect URLs can be found here.

Redirection parameters#

The redirect method of the GithubProvider accepts additional parameters. These parameters and their description are listed below and are all optional.

Example

this.github.redirect({ /* ... */ }, {
allow_signup: false
})
NameTypeDescription
loginstringSuggests a specific account to use for signing in and authorizing the app.
allow_signupbooleanWhether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. The default is true. Use false in the case that a policy prohibits signups.

Source: https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#parameters

LinkedIn#

Service nameDefault scopesAvailable scopes 
LinkedInProviderr_liteprofileAPI documentation

Register an OAuth application#

Visit this page to create an application and obtain a client ID and a client secret.

User info parameters#

The getUserInfo and getUserInfoFromTokens methods of the LinkedInProvider accept an additional projection parameter which is optional.

Example

const { userInfo } = await this.linkedin.getUserInfo(ctx, {
fields: [ 'id', 'firstName' ]
})
NameTypeDescription
fieldsstring[]List of fields that the returned user info object should contain. Additional documentation on field projections.
projectionstringLinkedIn projection parameter.

Sign In and Sign Up Example#

This example shows how to implement a sign in and sign up flow with sessions and a TypeORM User entity.

user.entity.ts

import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';
@Entity()
export class User {
@PrimaryGeneratedColumn()
id: number;
@Column({ unique: true })
email: string;
}

auth.controller.ts

// 3p
import {
Context,
dependency,
Get,
HttpResponseRedirect,
Store,
UseSessions,
} from '@foal/core';
import { GoogleProvider } from '@foal/social';
import { User } from '../entities';
export class AuthController {
@dependency
google: GoogleProvider;
@dependency
store: Store;
@Get('/signin/google')
redirectToGoogle() {
return this.google.redirect();
}
@Get('/signin/google/callback')
@UseSessions({
cookie: true,
})
async handleGoogleRedirection(ctx: Context) {
const { userInfo } = await this.google.getUserInfo(ctx);
let user = await User.findOne({ email: userInfo.email });
if (!user) {
// If the user has not already signed up, then add them to the database.
user = new User();
user.email = userInfo.email;
await user.save();
}
ctx.session.setUser(user);
return new HttpResponseRedirect('/');
}
}

Custom Provider#

If necessary, you can also implement your own provider. This one must inherit the abstract class AbstractProvider.

Example

// 3p
import { AbstractProvider, SocialTokens } from '@foal/core';
export interface GithubAuthParameter {
// ...
}
export interface GithubUserInfoParameter {
// ...
}
export class GithubProvider extends AbstractProvider<GithubAuthParameter, GithubUserInfoParameter> {
protected configPaths = {
clientId: 'social.github.clientId',
clientSecret: 'social.github.clientSecret',
redirectUri: 'social.github.redirectUri',
};
protected authEndpoint = '...';
protected tokenEndpoint = '...';
protected userInfoEndpoint = '...'; // Optional. Depending on the provider.
protected defaultScopes: string[] = [ 'email' ]; // Optional
async getUserInfoFromTokens(tokens: SocialTokens, params?: GithubUserInfoParameter) {
// ...
}
}