feat(docs): update migration docs for authentication/authorization

docs/site/migration/auth/built-in.md

@@ -6,8 +6,133 @@ sidebar: lb4_sidebar
 permalink: /doc/en/lb4/migration-auth-built-in.html
 ---
 
-{% include note.html content="
-This is a placeholder page, the task of adding content is tracked by the
-following GitHub issue:
-[loopback-next#3719](https://github.com/strongloop/loopback-next/issues/3719)
-" %}
+## Migrate the authentication flow
+
+### Request access tokens via login
+
+In LoopBack 3, the built-in `User` model exposes a `login` endpoint at
+`POST /Users/login`. It allows a user to be authenticated with `username/email`
+and `password`. Successful login returns a JSON object that contains the `id` as
+the access token. See
+https://loopback.io/doc/en/lb3/Introduction-to-User-model-authentication.html#login-as-the-new-user.
+
+The `login` method can also be used programmatically behind other endpoints. For
+example:
+
+```js
+router.post('/projects', function(req, res) {
+  var email = req.body.email;
+  var password = req.body.password;
+
+  app.models.User.login(
+    {
+      email: email,
+      password: password,
+    },
+    'user',
+    function(err, token) {
+      if (err)
+        return res.render('index', {
+          email: email,
+          password: password,
+          loginFailed: true,
+        });
+
+      token = token.toJSON();
+
+      res.render('projects', {
+        username: token.user.username,
+        accessToken: token.id,
+      });
+    },
+  );
+});
+```
+
+See
+https://github.com/strongloop/loopback-example-access-control/blob/master/server/boot/routes.js#L19-L41.
+
+1. Implement the login endpoint in LoopBack 4:
+
+We can add the `login` method to a controller and expose it as `/users/login`
+endpoint:
+
+- Login method
+
+  - https://github.com/strongloop/loopback4-example-shopping/blob/master/packages/shopping/src/controllers/user.controller.ts#L204
+
+  ```ts
+  @post('/users/login', {
+    responses: {
+      '200': {
+        description: 'Token',
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              properties: {
+                token: {
+                  type: 'string',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  })
+  async login(
+    @requestBody(CredentialsRequestBody) credentials: Credentials,
+  ): Promise<{token: string}> {
+    // ensure the user exists, and the password is correct
+    const user = await this.userService.verifyCredentials(credentials);
+
+    // convert a User object into a UserProfile object (reduced set of properties)
+    const userProfile = this.userService.convertToUserProfile(user);
+
+    // create a JSON Web Token based on the user profile
+    const token = await this.jwtService.generateToken(userProfile);
+
+    return {token};
+  }
+  ```
+
+Optionally, we can provide `UserService` and `TokenService` to verify
+credentials and generate access tokens.
+
+- User service
+
+  - https://github.com/strongloop/loopback4-example-shopping/blob/master/packages/shopping/src/services/user-service.ts
+
+- Token service
+
+  - https://github.com/strongloop/loopback4-example-shopping/blob/master/packages/shopping/src/services/jwt-service.ts
+
+2. Reuse the `User` database from LB3
+
+- Datasource for the User database
+- UserCredentialsRepository
+
+  - https://github.com/strongloop/loopback4-example-shopping/blob/master/packages/shopping/src/repositories/user-credentials.repository.ts
+
+### Mark a method that requires authentication
+
+- @authenticate
+
+### Protect API calls with access tokens
+
+- JWT strategy
+
+  - https://github.com/strongloop/loopback4-example-shopping/blob/master/packages/shopping/src/authentication-strategies/jwt-strategy.ts
+
+## Migrate the authorization flow
+
+### Migrate ACLs
+
+1. Decorate protected methods with `@authorize`
+
+- https://github.com/strongloop/loopback4-example-shopping/blob/11c48ef222a7960cb266bd88878c0eb9f8138127/packages/shopping/src/controllers/user-order.controller.ts#L48
+
+2. Implement an Authorizer
+
+- https://github.com/strongloop/loopback4-example-shopping/blob/master/packages/shopping/src/services/authorizor.ts

docs/site/migration/auth/example.md

@@ -0,0 +1,36 @@
+---
+lang: en
+title:
+  'Migrating authentication and authorization for an example LoopBack 3
+  application'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-auth-example.html
+---
+
+## Example LoopBack 3 application
+
+- https://github.com/strongloop/loopback-example-access-control
+
+## Migration to LoopBack 4
+
+1. Set up `/login` endpoint
+
+2. Set up authentication
+
+- Authentication action
+- `@authenticate`
+- Authentication strategies
+
+3. Set up authorization
+
+- Migrate ACLs -> `@authorize`
+- Migrate custom role resolvers -> `Authorizer` or `Voter`
+
+## Use a third party library as the authorizer
+
+- Casbin
+
+## Use a third party service as the authorizer
+
+- Auth0

docs/site/migration/auth/overview.md

@@ -6,23 +6,119 @@ sidebar: lb4_sidebar
 permalink: /doc/en/lb4/migration-auth-overview.html
 ---
 
+## LoopBack 3 authentication and authorization facilities
+
 LoopBack version 3 provides several options for adding authentication and
-authorization to secure the applications:
+authorization to secure the applications. See
+[docs](https://loopback.io/doc/en/lb3/Authentication-authorization-and-permissions.html)
+for more details.
+
+### Authentication
+
+1. Built-in `User` and `AccessToken` based authentication
+
+LoopBack 3 includes a built-in `User` model with `login` and other methods to
+perform username/password based authentication and return an access token, which
+can then be used to access protected resources.
+
+2. Integration with [Passport](http://www.passportjs.org/)
+
+[loopback-component-passport](https://github.com/strongloop/loopback-component-passport)
+provides integration between LoopBack 3 and
+[Passport](http://www.passportjs.org) to support third-party login and account
+linking for LoopBack applications. The migration path is described in
+[Migrating Passport-based authentication](./passport.md).
+
+3. oAuth 2.0
+
+[loopback-component-oauth2](https://github.com/strongloop/loopback-component-oauth2)
+provides full integration between OAuth 2.0 and LoopBack. It enables LoopBack
+applications to function as an oAuth 2.0 provider to authenticate and authorize
+client applications and/or resource owners (i.e. users) to access protected API
+endpoints. The migration path is described in
+[Migrating OAuth2 provider](./oauth2.md).
+
+### Authorization
 
 - A set of built-in models like `User`, `AccessToken` and `ACL` makes it easy to
   store your user credentials locally and define custom access control checks.
   The migration path is described in
   [Migrating built-in authentication and authorization](./built-in.md).
 
-- [loopback-component-passport](https://github.com/strongloop/loopback-component-passport)
-  provides integration between LoopBack 3 and
-  [Passport](http://www.passportjs.org) to support third-party login and account
-  linking for LoopBack applications. The migration path is described in
-  [Migrating Passport-based authentication](./passport.md).
-
-- [loopback-component-oauth2](https://github.com/strongloop/loopback-component-oauth2)
-  provides full integration between OAuth 2.0 and LoopBack. It enables LoopBack
-  applications to function as an oAuth 2.0 provider to authenticate and
-  authorize client applications and/or resource owners (i.e. users) to access
-  protected API endpoints. The migration path is described in
-  [Migrating OAuth2 provider](./oauth2.md).
+- Built-in ACL based authorization
+
+## LoopBack 4 authentication and authorization facilities
+
+LoopBack 4 focuses on capturing the minimum common metadata for authentication
+and authorization and enabling extensibility so that different security
+strategies/schemes can be plugged in to enforce authentication and
+authorization.
+
+### Authentication
+
+In LoopBack 4, `authentication` is enforced as an action of the `Sequence` for
+REST.
+
+- AuthenticationStrategy
+- PassportAdapter
+
+Please note no built-in username/password based authentication is shipped with
+LoopBack 4.
+
+### Authorization
+
+In LoopBack 4, `authorization` is made possible as an interceptor in front of
+controller methods or proxied repository/service methods.
+
+- Authorizer/Voter
+- Use your own interceptor for authorization
+
+Please note no built-in ACL based authorization is shipped with LoopBack 4.
+
+## Concept mapping
+
+- Authentication (retrieve principal from request)
+  - LB3
+    - built-in User model: provides persistence for user info, login, logout,
+      and other apis
+    - built-in AccessToken model: contains logged in user's auth metadata
+    - built-in authentication system that integrates User, AccessToken and other
+      authorization related models(Role, RoleMapping, ACL) to perform the
+      authentication+authorization as a whole
+  - LB4
+    - create User model to describe data shape, create repository for
+      persistence
+    - create User controller for login, logout, other apis
+    - implement token service for encoding/decoding principal's info
+- Authorization (determine the principal's access)
+  - LB3(I am not very familiar with the lb3 auth, more details TBD)
+    - Role
+    - RoleMapping
+    - ACL
+  - LB4
+
+## General flow
+
+- LB3(see
+  [doc](https://loopback.io/doc/en/lb3/Authentication-authorization-and-permissions.html#general-process))
+  - implement authentication
+  - specify user roles
+  - define access for each role and model method
+  - set-up access control for users
+- LB4
+  - Authentication
+    - create User model, controller(login/logout methods) leveraging User and
+      Token service(we provide interface, developer implements them)
+    - decorate endpoints with `@authenticate()` to specify authentication
+      metadata
+    - implements authentication strategies
+    - mount authentication component and register strategies
+  - Authorization
+    - design the implementation of Role, see
+      [comment](https://github.com/strongloop/loopback-next/issues/4291#issuecomment-572278133)
+    - design the implementation of ACL
+    - decorate endpoints with `@authorize()` to specify authorization metadata
+    - create authorizers
+    - mount authorization component and register authorizers
+  - @loopback/security provides types/interfaces to define the contract of auth
+    related concepts

docs/site/migration/auth/passport.md

@@ -6,8 +6,6 @@ sidebar: lb4_sidebar
 permalink: /doc/en/lb4/migration-auth-passport.html
 ---
 
-{% include note.html content="
-This is a placeholder page, the task of adding content is tracked by the
-following GitHub issue:
-[loopback-next#3958](https://github.com/strongloop/loopback-next/issues/3958)
-" %}
+## Migrate from `loopback-component-passport`
+
+https://github.com/strongloop/loopback-next/tree/master/extensions/authentication-passport