Page Contents

@loopback/example-passport-login

A tutorial for implementing authentication in LoopBack 4 using passport modules.

Overview

This example demonstrates how to use the LoopBack 4 features (like @authenticate decorator, strategy providers, etc) with passport strategies. 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

Authentication using passport strategies as Express middleware

Take a look at how to use passport strategies as Express middleware using 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

Install the example locally

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

    lb4 example passport-login

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

    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

$ 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.
  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.
  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.

    "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.

    "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.
    • The passport-twitter strategy 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.

    "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