Improve and refactor the authentication documentations

[neha2683]

Hello
Is there a better tutorial or video to demonstrate integration of authentication and authorization into Loopback 4 application.
The current tutorial on loopback.io is little confusing for me . Thanks for the pointers .

---

Updated by Janny

A plan for the layout of new authentication documentation:

• Authentication Overview (includes Concept and architecture, brief description, not code)
  • Getting started with JWT todo example as the authentication tutorial
    • Copy the usage from its README file
  • Component @loopback/authentication - what's provided out-of-the-box
    • Explain concepts (see the concepts in Improve and refactor the authentication documentations #5294 (comment))
    • Put usage in @loopback/authentication's README file
  • JWT auth extension @loopback/authentication-jwt-extension - what's provided out-of-the-box
  • create your own auth strategy - for extension developers
  • Passport adapter @loopback/authentication-passport
  • Advanced tutorial create jwt auth extension (use https://github.com/HrithikMittal/Loopback4-auth)

Acceptance Criteria

• Create a overview page for authentication, only describes the architecture and concepts
• Refactor loopback-authentication-component to reflect the current code and easier to understand
• Update @loopback/authentication's README file to have a concise usage
• Add JWT auth extension page in loopback.io, the usage can point to the module's readme file
• Add JWT todo example fix: jwt auth tutorial #5421 mostly ready for merge
• Refactor the JWT tutorial in shopping example to be easier to understand
• Refactor the passport adapter page to be easier to understand

[achrinza]

I don't have any video tutorials as my disposal, but here's a quote from my previous response on a breakdown of the different concepts:

Concept breakdown

Just to quote from my response on Gitter:

These concepts are the building blocks of lb4. They serve a specific purpose while following the OOP paradigm.

It may look like a lot, but these are essentially the different extension points in LoopBack 4 (hence why lb4 is extremely extensible).
Let's see if we can break it down:

Decorators (in general)

The decorators in lb4 are no different to the standard decorators in TypeScript. They add metadata to classes, methods. properties, or parameters. They don't actually add any functionality, only metadata.

Think of it like the file properties on your file system: It's not visible when interacting with the file normally, but those who want to access those properties will be able to via a standard interface.
There's more benefits to Decorators, but the above explanation is the watered-down gist of it.

Sequence (in general)

Sequences are a group of Actions. It simply indicates which actions should be used by the server to process the request.

Sequence Actions (in general)

Sequence Actions (or simply "Actions") are stateless, meaning that they only have the basic concept
Elements.

Converting into Express.js terminology; Think of an Action as an middleware. And think of an Element as the contents that a middleware receives. They work differently, but the high-level idea is about the same.

They are unaware of other higher-level concepts such as Controllers, DataSource, Models, etc.

Components (in general)

When adding functionality to lb4, you'll usually need to add a combination of Providers, Booters, etc. This can tedious to manage. Hence, Components are registered once in the lb4 Application, which will then register the other stuff for you.

@ authenticate

Adds authentication metadata.

AuthenticationComponent

A component to register the necessary artifacts.

AuthenticationActionProvider

This is a Sequence Action. Essentially, it adds an "authentication" step to the Sequence.

AuthenticationStrategyProvider

This is a standard interface that the @loopback/authentiation package understands. Hence, any authentication strategy that adopts this interface can be used in @loopback/authentication. Think of it like the standard interface for Passport.js uses to interface with many different authentication strategies

---

We also have an experimental JWT authentication extension that has built-in models, token service, etc. Though at least some customization is required as there isn't one-size-fits-all for everyone's use-case.

[jannyHou]

@achrinza Thank you for providing the concise (but very accurate) summary of the key concepts in authentication 👍

Some of the authentication documentations were created early when team first worked on it. As time goes on we added new features, now it's a good opportunity to reorganize and improve them.

@achrinza has a pretty good break down of the concepts, neat 👍
And thank you @neha2683 for bringing up this issue, video tutorial is definite a good idea, but doc is still the first material that people will visit, we need to make sure it's clear. So I am thinking of turning this story into a doc improvement. WDYT?
And any suggestions are welcomed 🙇‍♀️

[rhiwn]

hi, I had jwt authentication working on my controller methods. I updgraded loopback/cli and ran lb4 update yesterday and now the methods don't authenticate any more. Is there something else I need to do to get authentication working again?

[rhiwn]

ah solved - I had followed Raymonds instructions on updating sequence.ts at #5368 and had missed out my authentication sequence. All working now :)

[dhmlau]

@jannyHou, could you please add acceptance criteria for estimation? Thanks.

[jannyHou]

Hi everyone, I wrote a new layout for the authentication doc and updated the acceptance criteria accordingly. Feedback is welcomed!

I would suggest we use this story to focus on authentication doc refactor, and use #5441 for authorization.

[dhmlau]

@jannyHou, i'd suggest to make this an epic and break down the tasks into separate GH issues. It might also help if any community users would like to help as well. Thanks.

[jannyHou]

An update:

A few PRs are created to re-structure the authentication doc:

• Auth doc refactor #5598
• auth doc refactor - customizing strategy #5683
• Auth doc component #5643
• docs: add jwt extension #5641
• docs: refactor passport doc #5640

[jannyHou]

Closing it as all PRs are merged :)