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

[raymondfeng]

Laying out the migration path for authentication and authorization

Checklist

👉 Read and sign the CLA (Contributor License Agreement) 👈

• npm test passes on your machine
• New tests added or existing tests modified to cover all changes
• Code conforms with the style guide
• API Documentation in code was updated
• Documentation in /docs/site was updated
• Affected artifact templates in packages/cli were updated
• Affected example projects in examples/* were updated

👉 Check out how to submit a PR 👈

[hacksparrow]

Please include a link to https://github.com/strongloop/loopback-next/blob/master/packages/authorization/README.md. It was recently updated by Janny to explain the underlying mechanism very clearly.

[hacksparrow]

Not sure if "reuse" is the right choice here. The User models work very differently in LB3 and LB4.

[bajtos]

Thank you @raymondfeng for taking a look at the auth & auth migration story. I am little bit confused about the scope and purpose of this pull request. The task was a spike to build a better understanding of the migration process and create follow-up stories to write detailed guides. This pull request is adding guides without much details. Do you intend to add more content as part of this PR?

I think it's very important to verify the migration process on a real application, this is a kind of an end-to-end acceptance test to check that our guide actually works.

For example, we can start with https://github.com/strongloop/loopback-getting-started which provides a very simple User management & authentication & authorization APIs:

• Anybody can create a new user
• Only owners can view, modify or delete their user profiles/accounts - this requires both authentication and authorization
• I think we can leave out password confirmation and password reset flows for the first iteration and create follow-up tasks to look into this area.

[bajtos]

Can you please provide an example code showing how to implement a typical User service using the artifacts migrated from a LB3 application? The guide does not explain how to "reuse the User database from LB3", I think it's important to include those instructions here.

[bajtos]

Ditto.

Can you please provide an example code showing how to implement a typical Token service using the artifacts migrated from a LB3 application? The guide does not explain how to reuse the AccessToken model from LB3, I think it's important to include those instructions here.

[bajtos]

AFAIK, LoopBack 3 applications are typically not using JWT strategy, because we don't have first class support for that.

Maybe it's possible to set up JWT auth strategy in a LB3 app using loopback-component-passport? That's out of scope of this part of the migration guide, where we should focus on the built-in auth & auth as provided by LB3 core.

[bajtos]

Please explain how to map acls entries from model JSON files to LB4 @authorize calls and show some example code.

Please explain this in more details and provide an example code showing how to implement a typical Authorizer service using the artifacts migrated from a LB3 application. Also explain how to migrate Role and RoleMapping entries that are stored in a database.

What are other sources of authorization rules in LB3 that users may need to migrate to LB4?

[bajtos]

I am afraid the README for the package at the end of your link does not provide enough information to make it clear for LB3 users what changes they need to make to their applications.

[raymondfeng]

@bajtos Thank you for the review comments.

Let me set the correct expectation here:

1. The PR is meant to highlight key items/steps for the fully-fledged migration guide. The markdown files mostly only contain headers and pointers. The details need to be filled in by follow-up user stories.

2. https://github.com/strongloop/loopback-next/blob/auth-migration/docs/site/migration/auth/example.md is intended to be the sample scenario for auth migrations.

[dhmlau]

Added @jannyHou @emonddr and @deepakrkris as reviewers, since they have worked on LB4 authentication and authorization. Thanks.

[bajtos]

@raymondfeng thank you for clarifying the expectations 👍

From my point of view, I'd like the migration guide to offer clear and easy to follow instructions enabling developers to migrate their LB3 application to LB4 while preserving all (or at least most of) the authentication/authorization related functionality.

So for example, when I take the repo https://github.com/strongloop/loopback-getting-started and read the migration guide, I should have pretty good picture of what steps and changes I need to make to upgrade that codebase to use LB4 while preserving the functionality. (This applies to the entire migration guide, not only to the auth/auth parts.) Since loopback-getting-started uses the built-in User and AccessToken models, I would expect the LB4 version to do the same. So for example telling users to switch from LB3 built-ins to JWT in LB4 is not something I would consider as a good default solution for migration, because it has major side effects.

As I was reading your draft, it was not clear to me how would I migrate the different parts and I did not see TODO comments that would indicate that those missing parts are known and be filled later.

I know each of us likes to structure our work differently and I don't want to force my style on you, but at the same time I want to avoid the situation where we end up with a migration guide that's difficult to use or is not useful at all.

I am keeping two goals while reviewing PRs related to migration guide:

1. Ensure all important parts are covered or there are well-defined follow-up tasks to cover them later.
2. For each part, the instructions are clear, comprehensive and easy to follow even by inexperienced developers.

[jannyHou]

Thank you for providing the skeleton of auth migration guide 👍
I commented some points(mostly the concept comparison and implementation process) to be covered in the migration guide in the overview file.
Will write more details for the other files.

[jannyHou]

I would suggest doing a separate spike for migrating the passport based strategies in the 2nd phase after we figured out the migration guide for the main module.

[jannyHou]

same as loopback-component-passport

[jannyHou]

• Should we consider build a component with equivalent User model and AccessToken model?
• (In the follow-up doc story) We can explain the concept difference between LB3 AccessToken and LB4 token
  • LB3
    • a built-in model, belongsTo a User model
    • it carries the logged in user(or principal? not sure which is more accurate)'s scope, has util apis to return info from request
  • LB4
    • it just refers to the token included in a request's header
    • the access token mentioned in our tutorials work with a particular strategy to perform the authentication
    • developer has the flexibility and responsibility to define the encoded info

[jannyHou]

As an overview, I am thinking of make a brief comparison of the concept mapping and general process in 3 and 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 Process:

• LB3(see doc)
  • 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
    • 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