# @loopback/example-passport-login

A tutorial for implementing authentication in LoopBack 4 using
[passport](https://github.com/jaredhanson/passport) modules.

- [Overview](#overview)
- [Prerequisites](#prerequisites)
- [Install](#install-the-example-locally)
- [Tutorial - Facebook](#Try-it-out-with-FaceBook)
- [Tutorial - Google](#Try-it-out-with-Google)

## Overview

This example demonstrates how to use the LoopBack 4 features (like
`@authenticate` decorator, strategy providers, etc) with
[passport strategies](http://passportjs.org). It includes the OAuth2 strategies
to interact with external OAuth providers like Facebook, Google, etc as well as
local and basic strategies.

You can use this example to see how to,

- Log in or Sign up into a LoopBack App using passport strategy modules
- Log in via external apps like Facebook or link those external profiles with a
  LoopBack user (for example, a LoopBack user can have associated
  Facebook/Google accounts to retrieve pictures).
- Use basic or local passport strategy modules

## Prerequisites

Before starting this tutorial, make sure you have Client-ids/Secrets from third
party apps

- [Facebook](https://developers.facebook.com/apps)
- [Google](https://console.developers.google.com/project)
- [twitter](https://developer.twitter.com/apps)

## Authentication using passport strategies as Express middleware

Take a look at how to use passport strategies
[as Express middleware using interceptors](src/authentication-interceptors)

## Authentication using passport strategies as a step in Application Sequence

Take a look at how to use passport strategies
[by invoking independent of Express](src/authentication-strategies)

## Install the example locally

1. Run the `lb4 example` command to install `example-passport-login` repository:

   ```sh
   lb4 example passport-login
   ```

2. change into directory and then install the required dependencies:

   ```sh
   cd loopback4-example-passport-login && npm i
   ```

## Run the application

By default the user data is stored using a memory connector and saved locally to
`data/db.json`

Start the application with

```sh
$ npm start
```

To use Google, Facebook or Twitter logins, you'll need:

- Copy `oauth2-providers.template.json` from this example project's root to
  `oauth2-providers.json`.
- Update Google/Facebook/Twitter configuration in the json file.
- Set `OAUTH_PROVIDERS_LOCATION` environment variable to
  `../oauth2-providers.json`.

## Test the login scenarios

Open browser to http://localhost:3000

### Scenario 1 : Sign up as a local user

1. Click on `Sign Up` from the header menu and register as a local user.
2. If the email provided during registration, matches with your account in
   Facebook or Google you can link those profiles with your local account.
3. Click on `Login` from the header menu and enter registered email id and
   password. The `View account` page loads with user information.

### Scenario 2 : Link external profiles with a local user

1. Click on `Login` from the header menu, You will see various buttons under
   `Other login options`.
   - [Facebook](#Try-it-out-with-Facebook)
   - [Google](#Try-it-out-with-Google)
   - [Twitter](#Try-it-out-with-Twitter)
2. When you click on any login option, the page is redirected to that social
   app's login page. On successful login with the social app, the `View account`
   page is loaded.
3. If the email-id registered in the social media app matches with a email-id
   registered locally, then the profiles will be linked and the `View account`
   page will display all the `linked accounts` for that locally registered user.
4. Click on Logout to log out of user session

### Scenario 3 : Sign up via an external Social Media app

1. Click on `Login` from the header menu, You will see various buttons under
   `Other login options`.
   - [Facebook](#Try-it-out-with-Facebook)
   - [Google](#Try-it-out-with-Google)
   - [Twitter](#Try-it-out-with-Twitter)
2. When you click on any login option, the page is redirected to that social
   app's login page. On successful login with the social app, the `View account`
   page is loaded.
3. If the email-id registered in the social media app does not match any
   email-ids registered locally, then a new user is signed up. `View account`
   page will display the external profile used to login under the
   `linked accounts` section.
4. Click on Logout to log out of user session

## Try it out with Facebook

### Create a test app and test user in Facebook

1. Login to Facebook developer console: https://developers.facebook.com/apps
2. Click on `My Apps` tab in the dashboard menu, and then select `Add a new App`
3. This loads the `App creation` page. Pick the platform as `Website` and then
   enter app category, app name and "Site URL" (Skip the quick start)
4. Click `Settings` tab from the left hand side navigation menu, note the "App
   ID" and "App Secret" and save
5. Click the `Roles` tab from the left hand side navigation menu, then the
   `Test users` link under it, to display a list of test users. You can also
   create a new test user.
6. On any listed test user, click the edit button to open an actions menu ->
   click `Change permissions granted by this test user` and add [`email`,
   `manage_pages`] scopes to permissions

- NOTE:
  - Your app may not work if the settings are missing a contact email and/or
    "Site URL".
  - if you are testing locally, you can simply use `localhost:[port#]` as your
    "Site URL".

### Create oauth2-providers.json

- Copy `oauth2-providers.template.json` from this example project's root to
  `oauth2-providers.json`
- Update Facebook oauth2 config with the values for `clientID/clientSecret` from
  your test app.

  ```json
  "facebook-login": {
    "provider": "facebook",
    "module": "passport-facebook",
    "clientID": "xxxxxxxxxxxxxxx",
    "clientSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "callbackURL": "/auth/facebook/callback",
    "authPath": "/auth/facebook",
    "callbackPath": "/auth/facebook/callback",
    "successRedirect": "/auth/account",
    "failureRedirect": "/login",
    "scope": ["email"],
    "failureFlash": true,
    "profileFields": ["gender", "link", "locale", "name", "timezone", "verified", "email", "updated_time"]
  }
  ```

The `profileFields` field above tells Facebook details to return in profile data
after authentication. For more information regarding the providers template, see
http://loopback.io/doc/en/lb2/Configuring-providers.json.html.

### Log in with Facebook

- Open your browser to the example app with `http://localhost:3000`
- Click `Log In` from the example app header menu
- Click on `Log In with Facebook` button
- FaceBook login page opens, enter test user-id and password
- example app loads again on successful login
- redirect to example app will fail if Facebook did not return profile with
  email-id

## Try it out with Google

### Create test credentials in Google

1. Login to Google developer console: https://console.developers.google.com You
   may have to create a sample project if you are new to Google developer
   console
2. Click on `OAuth consent screen` from the left hand side navigation menu,
   select `External`, click `Create` button
3. This loads the `Application` page to register your app. Enter app name and
   check if scopes has `email` permission
4. Click on `Credentials` link in the left hand side navigation menu
5. Then click `Create Credentials` tab, and select `OAuth Client ID`
6. This loads the `Create Client ID` page. Select application type as
   `web application`, enter name and click `Create` button
7. A pop up loads with the created credentials. Note the displayed "Client ID"
   and "Client Secret" and save

### Create oauth2-providers.json

- Copy `oauth2-providers.template.json` from this example project's root to
  `oauth2-providers.json`
- Update Google oauth2 config with the values for `clientID/clientSecret` from
  your Google test app.

  ```json
  "google-login": {
      "provider": "google",
      "module": "passport-google-oauth2",
      "strategy": "OAuth2Strategy",
      "clientID": "{google-client-id}",
      "clientSecret": "{google-client-secret}",
      "callbackURL": "/api/auth/thirdparty/google/callback",
      "authPath": "/api/auth/thirdparty/google",
      "callbackPath": "/api/auth/thirdparty/google/callback",
      "successRedirect": "/auth/account",
      "failureRedirect": "/login",
      "scope": ["email", "profile"],
      "failureFlash": true
  }
  ```

### Log in with Google

- Open your browser to the example app with, `http://localhost:3000`
- Click on `Log In` from the example app header menu
- Click on `Log In with Google` button
- Google login page opens, enter Google user-id and password
- example app loads again on successful login

## Try it out with Twitter

### Create a test app and test user in Twitter

1. Login to Twitter developer page: https://developer.twitter.com/apps
2. Click on `Create an app` to create a new app.
3. In the `App details` page, fill the `callback URL` field with
   `http://localhost:3000/api/auth/thirdparty/twitter/callback`.
4. In the same page, you also need to fill in the `Terms of Service URL` and
   `Privacy policy URL`. This is needed since we will need to request users for
   email address in the `Permissions` settings.
5. In the `Keys and tokens` tab, no changes are needed. You will see the
   `Consumer API keys` section which has the API key and secret. These values
   will be used in the LoopBack application.
6. In the `Permissions` tab, under `additional permissions` section, select
   `Request email address`. Make sure you have the term of service and privacy
   policy urls information filled in in the `Add details` tab, otherwise the
   `Request email address` will be disabled for you.

- NOTE:
  - If you change the permission settings after the app is being created, you
    might need to regenerate the tokens again by going to the `Keys and tokens`
    tab for regeneration.
  - For details in getting email address from the login profile, see
    [this discussion in `passport-twitter` repo](https://github.com/jaredhanson/passport-twitter/issues/67).
  - The
    [passport-twitter strategy](http://www.passportjs.org/packages/passport-twitter/)
    used in this example is using OAuth 1.0a API.

### Create oauth2-providers.json

- Copy `oauth2-providers.template.json` from this example project's root to
  `oauth2-providers.json`
- Update Twitter oauth config with the values for `consumerKey/consumerSecret`
  from your test app.

  ```json
  "twitter-login": {
      "provider": "twitter",
      "module": "passport-twitter",
      "strategy": "OAuth2Strategy",
      "consumerKey": "xxxxxxxxxxxxxx",
      "consumerSecret": "xxxxxxxxxxxxxxx",
      "callbackURL": "/api/auth/thirdparty/twitter/callback?source=twitter",
      "authPath": "/api/auth/thirdparty/twitter",
      "callbackPath": "/api/auth/thirdparty/twitter/callback",
      "successRedirect": "/auth/account",
      "failureRedirect": "/login",
      "includeEmail": true,
      "scope": ["email", "profile"],
      "failureFlash": true
    },
  ```

### Log in with Twitter

- Open your browser to the example app with `http://localhost:3000`
- Click `Log In` from the example app header menu
- Click on `Log In with Twitter` button
- You'll be asked to authorize the Twitter app to access your account. Click
  `Authorize app`.
- Example app loads again on successful login
- Redirect to example app will fail if Twitter did not return profile with
  email-id