@loopback/authentication-passport 0.1.0

package/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) IBM Corp. 2017,2019. All Rights Reserved.
+Node module: @loopback/authentication-passport
+This project is licensed under the MIT License, full text below.
+
+--------
+
+MIT license
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# Passport Strategy Adapter
+
+_Important: We strongly suggest that users understand LoopBack's
+[authentication system](https://loopback.io/doc/en/lb4/Loopback-component-authentication.html)
+before using this module_
+
+This is an adapter module created for plugging in
+[`passport`](https://www.npmjs.com/package/passport) based strategies to the
+authentication system in `@loopback/authentication@2.x`.
+
+## Installation
+
+```sh
+npm i @loopback/authentication-passport --save
+```
+
+## Background
+
+`@loopback/authentication@2.x` allows users to register authentication
+strategies that implement the interface
+[`AuthenticationStrategy`](https://apidocs.strongloop.com/@loopback%2fdocs/authentication.html#AuthenticationStrategy)
+
+Since `AuthenticationStrategy` describes a strategy with different contracts
+than the passport
+[`Strategy`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/passport/index.d.ts#L79),
+and we'd like to support the existing 500+ community passport strategies, an
+**adapter class** is created in this package to convert a passport strategy to
+the one that LoopBack 4 authentication system wants.
+
+## Usage
+
+### Simple Usage
+
+1. Create an instance of the passport strategy
+
+Taking the basic strategy exported from
+[`passport-http`](https://github.com/jaredhanson/passport-http) as an example,
+first create an instance of the basic strategy with your `verify` function.
+
+```ts
+import {BasicStrategy} from 'passport-http';
+
+function verify(username: string, password: string, cb: Function) {
+  users.find(username, password, cb);
+}
+const basicStrategy = new BasicStrategy(verify);
+```
+
+It's a similar configuration as you do when adding a strategy to a `passport` by
+calling `passport.use()`.
+
+2. Apply the adapter to the strategy
+
+```ts
+const AUTH_STRATEGY_NAME = 'basic';
+
+const basicAuthStrategy = new StrategyAdapter(
+  // The configured basic strategy instance
+  basicStrategy,
+  // Give the strategy a name
+  // You'd better define your strategy name as a constant, like
+  // `const AUTH_STRATEGY_NAME = 'basic'`.
+  // You will need to decorate the APIs later with the same name.
+  AUTH_STRATEGY_NAME,
+);
+```
+
+3. Register(bind) the strategy to app
+
+```ts
+import {Application, CoreTags} from '@loopback/core';
+import {AuthenticationBindings} from '@loopback/authentication';
+
+app
+  .bind('authentication.strategies.basicAuthStrategy')
+  .to(basicAuthStrategy)
+  .tag({
+    [CoreTags.EXTENSION_FOR]:
+      AuthenticationBindings.AUTHENTICATION_STRATEGY_EXTENSION_POINT_NAME,
+  });
+```
+
+### With Provider
+
+If you need to inject stuff (e.g. the verify function) when configuring the
+strategy, you may want to provide your strategy as a provider.
+
+_Note: If you are not familiar with LoopBack providers, check the documentation
+in
+[Extending LoopBack 4](https://loopback.io/doc/en/lb4/Extending-LoopBack-4.html)_
+
+1. Create a provider for the strategy
+
+Use `passport-http` as the example again:
+
+```ts
+class PassportBasicAuthProvider implements Provider<AuthenticationStrategy> {
+  value(): AuthenticationStrategy {
+    // The code that returns the converted strategy
+  }
+}
+```
+
+The Provider should have two functions:
+
+- A function that takes in the verify callback function and returns a configured
+  basic strategy. To know more about the configuration, please check
+  [the configuration guide in module `passport-http`](https://github.com/jaredhanson/passport-http#usage-of-http-basic).
+
+- A function that applies the `StrategyAdapter` to the configured basic strategy
+  instance. Then in the `value()` function, you return the converted strategy.
+
+So a full implementation of the provider is:
+
+```ts
+import {BasicStrategy, BasicVerifyFunction} from 'passport-http';
+import {StrategyAdapter} from `@loopback/passport-adapter`;
+import {AuthenticationStrategy} from '@loopback/authentication';
+
+class PassportBasicAuthProvider implements Provider<AuthenticationStrategy> {
+  constructor(
+    @inject('authentication.basic.verify') verifyFn: BasicVerifyFunction,
+  );
+  value(): AuthenticationStrategy {
+    const basicStrategy = this.configuredBasicStrategy(verify);
+    return this.convertToAuthStrategy(basicStrategy);
+  }
+
+  // Takes in the verify callback function and returns a configured basic strategy.
+  configuredBasicStrategy(verifyFn: BasicVerifyFunction): BasicStrategy {
+    return new BasicStrategy(verifyFn);
+  }
+
+  // Applies the `StrategyAdapter` to the configured basic strategy instance.
+  // You'd better define your strategy name as a constant, like
+  // `const AUTH_STRATEGY_NAME = 'basic'`
+  // You will need to decorate the APIs later with the same name
+  convertToAuthStrategy(basic: BasicStrategy): AuthenticationStrategy {
+    return new StrategyAdapter(basic, AUTH_STRATEGY_NAME);
+  }
+}
+```
+
+2. Register the strategy provider
+
+Register the strategy provider in your LoopBack application so that the
+authentication system can look for your strategy by name and invoke it:
+
+```ts
+// In the main file
+
+import {addExtension} from '@loopback/core';
+import {MyApplication} from '<path_to_your_app>';
+import {PassportBasicAuthProvider} from '<path_to_the_provider>';
+import {
+  AuthenticationBindings,
+  registerAuthenticationStrategy,
+} from '@loopback/authentication';
+
+const app = new MyApplication();
+
+// In a real app the function would be imported from a community module
+function verify(username: string, password: string, cb: Function) {
+  users.find(username, password, cb);
+}
+
+app.bind('authentication.basic.verify').to(verify);
+registerAuthenticationStrategy(app, PassportBasicAuthProvider);
+```
+
+3. Decorate your endpoint
+
+To authenticate your request with the basic strategy, decorate your controller
+function like:
+
+```ts
+class MyController {
+  constructor(
+    @inject(AuthenticationBindings.CURRENT_USER) private user: UserProfile,
+  ) {}
+
+  // Define your strategy name as a constant so that
+  // it is consistent with the name you provide in the adapter
+  @authenticate(AUTH_STRATEGY_NAME)
+  async whoAmI(): Promise<string> {
+    return this.user.id;
+  }
+}
+```

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './strategy-adapter';

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+function __export(m) {
+    for (var p in m) if (!exports.hasOwnProperty(p)) exports[p] = m[p];
+}
+Object.defineProperty(exports, "__esModule", { value: true });
+__export(require("./strategy-adapter"));
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;AAAA,wCAAmC"}

package/dist/strategy-adapter.d.ts

@@ -0,0 +1,28 @@
+import { AuthenticationStrategy, UserProfile } from '@loopback/authentication';
+import { Request } from '@loopback/rest';
+import { Strategy } from 'passport';
+/**
+ * Adapter class to invoke passport-strategy
+ *   1. provides express dependencies to the passport strategies
+ *   2. provides shimming of requests for passport authentication
+ *   3. provides lifecycle similar to express to the passport-strategy
+ *   4. provides state methods to the strategy instance
+ * see: https://github.com/jaredhanson/passport
+ */
+export declare class StrategyAdapter implements AuthenticationStrategy {
+    private readonly strategy;
+    readonly name: string;
+    /**
+     * @param strategy instance of a class which implements a passport-strategy;
+     * @description http://passportjs.org/
+     */
+    constructor(strategy: Strategy, name: string);
+    /**
+     * The function to invoke the contained passport strategy.
+     *     1. Create an instance of the strategy
+     *     2. add success and failure state handlers
+     *     3. authenticate using the strategy
+     * @param request The incoming request.
+     */
+    authenticate(request: Request): Promise<UserProfile>;
+}

package/dist/strategy-adapter.js

@@ -0,0 +1,60 @@
+"use strict";
+// Copyright IBM Corp. 2017,2019. All Rights Reserved.
+// Node module: @loopback/authentication-passport
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+Object.defineProperty(exports, "__esModule", { value: true });
+const rest_1 = require("@loopback/rest");
+const passportRequestMixin = require('passport/lib/http/request');
+/**
+ * Adapter class to invoke passport-strategy
+ *   1. provides express dependencies to the passport strategies
+ *   2. provides shimming of requests for passport authentication
+ *   3. provides lifecycle similar to express to the passport-strategy
+ *   4. provides state methods to the strategy instance
+ * see: https://github.com/jaredhanson/passport
+ */
+class StrategyAdapter {
+    /**
+     * @param strategy instance of a class which implements a passport-strategy;
+     * @description http://passportjs.org/
+     */
+    constructor(strategy, name) {
+        this.strategy = strategy;
+        this.name = name;
+    }
+    /**
+     * The function to invoke the contained passport strategy.
+     *     1. Create an instance of the strategy
+     *     2. add success and failure state handlers
+     *     3. authenticate using the strategy
+     * @param request The incoming request.
+     */
+    authenticate(request) {
+        return new Promise((resolve, reject) => {
+            // mix-in passport additions like req.logIn and req.logOut
+            for (const key in passportRequestMixin) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                request[key] = passportRequestMixin[key];
+            }
+            // create a prototype chain of an instance of a passport strategy
+            const strategy = Object.create(this.strategy);
+            // add success state handler to strategy instance
+            strategy.success = function (user) {
+                resolve(user);
+            };
+            // add failure state handler to strategy instance
+            strategy.fail = function (challenge) {
+                reject(new rest_1.HttpErrors.Unauthorized(challenge));
+            };
+            // add error state handler to strategy instance
+            strategy.error = function (error) {
+                reject(new rest_1.HttpErrors.InternalServerError(error));
+            };
+            // authenticate
+            strategy.authenticate(request);
+        });
+    }
+}
+exports.StrategyAdapter = StrategyAdapter;
+//# sourceMappingURL=strategy-adapter.js.map

package/dist/strategy-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy-adapter.js","sourceRoot":"","sources":["../src/strategy-adapter.ts"],"names":[],"mappings":";AAAA,sDAAsD;AACtD,iDAAiD;AACjD,+CAA+C;AAC/C,gEAAgE;;AAGhE,yCAAmD;AAGnD,MAAM,oBAAoB,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;AAElE;;;;;;;GAOG;AACH,MAAa,eAAe;IAC1B;;;OAGG;IACH,YAA6B,QAAkB,EAAW,IAAY;QAAzC,aAAQ,GAAR,QAAQ,CAAU;QAAW,SAAI,GAAJ,IAAI,CAAQ;IAAG,CAAC;IAE1E;;;;;;OAMG;IACH,YAAY,CAAC,OAAgB;QAC3B,OAAO,IAAI,OAAO,CAAc,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAClD,0DAA0D;YAC1D,KAAK,MAAM,GAAG,IAAI,oBAAoB,EAAE;gBACtC,8DAA8D;gBAC7D,OAAe,CAAC,GAAG,CAAC,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC;aACnD;YAED,iEAAiE;YACjE,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAE9C,iDAAiD;YACjD,QAAQ,CAAC,OAAO,GAAG,UAAS,IAAiB;gBAC3C,OAAO,CAAC,IAAI,CAAC,CAAC;YAChB,CAAC,CAAC;YAEF,iDAAiD;YACjD,QAAQ,CAAC,IAAI,GAAG,UAAS,SAAiB;gBACxC,MAAM,CAAC,IAAI,iBAAU,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC;YACjD,CAAC,CAAC;YAEF,+CAA+C;YAC/C,QAAQ,CAAC,KAAK,GAAG,UAAS,KAAa;gBACrC,MAAM,CAAC,IAAI,iBAAU,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC;YACpD,CAAC,CAAC;YAEF,eAAe;YACf,QAAQ,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AA5CD,0CA4CC"}

package/index.d.ts

@@ -0,0 +1,6 @@
+// Copyright IBM Corp. 2017,2018. All Rights Reserved.
+// Node module: @loopback/authentication-passport
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+export * from './dist';

package/index.js

@@ -0,0 +1,6 @@
+// Copyright IBM Corp. 2017,2018. All Rights Reserved.
+// Node module: @loopback/authentication-passport
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+module.exports = require('./dist');

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@loopback/authentication-passport",
+  "version": "0.1.0",
+  "description": "A package creating adapters between the passport module and @loopback/authentication",
+  "engines": {
+    "node": ">=8.9"
+  },
+  "scripts": {
+    "acceptance": "lb-mocha \"dist/__tests__/acceptance/**/*.js\"",
+    "build:apidocs": "lb-apidocs",
+    "build": "lb-tsc",
+    "clean": "lb-clean loopback-authentication-passport*.tgz dist tsconfig.build.tsbuildinfo package",
+    "pretest": "npm run build",
+    "test": "lb-mocha \"dist/__tests__/**/*.js\"",
+    "unit": "lb-mocha \"dist/__tests__/unit/**/*.js\"",
+    "verify": "npm pack && tar xf loopback-authentication-passport*.tgz && tree package && npm run clean"
+  },
+  "author": "IBM Corp.",
+  "copyright.owner": "IBM Corp.",
+  "license": "MIT",
+  "keywords": [
+    "Passport",
+    "Authentication",
+    "TypeScript"
+  ],
+  "files": [
+    "README.md",
+    "index.js",
+    "index.d.ts",
+    "dist",
+    "src",
+    "!*/__tests__"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/strongloop/loopback-next.git"
+  },
+  "dependencies": {
+    "@loopback/authentication": "^2.0.0",
+    "@loopback/context": "^1.16.0",
+    "@loopback/core": "^1.7.1",
+    "@loopback/metadata": "^1.1.5",
+    "@loopback/openapi-v3": "^1.4.0",
+    "@loopback/rest": "^1.11.2",
+    "passport": "^0.4.0",
+    "util-promisifyall": "^1.0.6"
+  },
+  "devDependencies": {
+    "@loopback/build": "^1.5.5",
+    "@loopback/openapi-spec-builder": "^1.1.11",
+    "@loopback/testlab": "^1.2.10",
+    "@loopback/eslint-config": "^1.1.1",
+    "@types/node": "^10.14.8",
+    "@types/passport": "^1.0.0",
+    "@types/passport-http": "^0.3.8",
+    "passport-http": "^0.3.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './strategy-adapter';

package/src/strategy-adapter.ts

@@ -0,0 +1,64 @@
+// Copyright IBM Corp. 2017,2019. All Rights Reserved.
+// Node module: @loopback/authentication-passport
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {AuthenticationStrategy, UserProfile} from '@loopback/authentication';
+import {HttpErrors, Request} from '@loopback/rest';
+import {Strategy} from 'passport';
+
+const passportRequestMixin = require('passport/lib/http/request');
+
+/**
+ * Adapter class to invoke passport-strategy
+ *   1. provides express dependencies to the passport strategies
+ *   2. provides shimming of requests for passport authentication
+ *   3. provides lifecycle similar to express to the passport-strategy
+ *   4. provides state methods to the strategy instance
+ * see: https://github.com/jaredhanson/passport
+ */
+export class StrategyAdapter implements AuthenticationStrategy {
+  /**
+   * @param strategy instance of a class which implements a passport-strategy;
+   * @description http://passportjs.org/
+   */
+  constructor(private readonly strategy: Strategy, readonly name: string) {}
+
+  /**
+   * The function to invoke the contained passport strategy.
+   *     1. Create an instance of the strategy
+   *     2. add success and failure state handlers
+   *     3. authenticate using the strategy
+   * @param request The incoming request.
+   */
+  authenticate(request: Request): Promise<UserProfile> {
+    return new Promise<UserProfile>((resolve, reject) => {
+      // mix-in passport additions like req.logIn and req.logOut
+      for (const key in passportRequestMixin) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (request as any)[key] = passportRequestMixin[key];
+      }
+
+      // create a prototype chain of an instance of a passport strategy
+      const strategy = Object.create(this.strategy);
+
+      // add success state handler to strategy instance
+      strategy.success = function(user: UserProfile) {
+        resolve(user);
+      };
+
+      // add failure state handler to strategy instance
+      strategy.fail = function(challenge: string) {
+        reject(new HttpErrors.Unauthorized(challenge));
+      };
+
+      // add error state handler to strategy instance
+      strategy.error = function(error: string) {
+        reject(new HttpErrors.InternalServerError(error));
+      };
+
+      // authenticate
+      strategy.authenticate(request);
+    });
+  }
+}