Setting up authentication is difficult! Improve docs?

[joeytwiddle]

https://loopback.io/doc/en/lb4/Loopback-component-authentication.html

The authentication document is very detailed in explanation, but perhaps less helpful than it could be for developers.

I am working on the idea that a developer with mid-level web experience wants to start adding authentication to their app. They might care less about how the system works internally and more about the steps required to get started with authentication.

I wish LB4's authentication was easy. (Presumably it is one of the most common requirements for Loopback users.)

Problems

Some problems I have experienced and/or witnessed with developers using the current docs:

• The doc contains full listings for some files when actually only a few lines need to be added to files which already exist inside the application. (E.g. sequence.ts and application.ts) I have seen developers miss out the lines they are supposed to copy because they are hidden inside all the other code.

• The doc also contains full listings for files from the loopback's npm packages. I have seen a developer copy the entire file and then wonder how to integrate it into their app. In fact they don't need to touch those files at all.

There is another authentication document which I should not neglect:

https://loopback.io/doc/en/lb4/Authentication-Tutorial.html (the JWT tutorial)

• I have not followed this tutorial through so I cannot make much comment on it, except to say: It also look quite long, and not everybody will want to use JWTs.

Expected behavior

What I like about many node.js / GitHub projects is that they offer in their README a few lines of code, or a few examples, which the developer can easily copy-paste to get started with trying out and using the software.

Suggested resolution

I have tried to create such a document, containing just the bare requirements to get authentication working, and nothing else.

Here it is: #910

Concerns:

• It's not a complete solution:

• Because OAuth2 requires two strategies (Basic and Bearer), but my aim is for simplicity, I have only demonstrated the first strategy.

• Because I don't know the shape of the user's DB, I have commented out the code that talks to the UserRepository, and left that for the developer to implement later. This is good for devs who just want to understand the basics of authentication, and fill in the details themselves. It's not so good for devs who want a complete authentication solution ASAP.

Next steps:

• Find out what other developers really want. Do they want JWT or OAuth2, or do they want a basic introduction, so they can implement their own authentication mechanism?

• I suspect what most users really want is a CLI command that will ask a few questions, and do all this work for them: lb4 authentication

• Review and critique my tutorial. Should I expand it? Or is it better that it's short and simple?

• My tutorial includes a re-implementation of this BasicAuthenticationStrategy. Should we perhaps make that available for developers to simply import?

• Is there also a TokenService implementation that developers could simply drop in if they don't want to write their own?

I apologise in advance if I don't have time to update this PR in future. You are very welcome to take it and modify it as you see fit.

[dhmlau]

@joeytwiddle, thanks a lot for the tutorial. I've commented in your PR #910 that the source of our docs is in loopback-next repo.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[dhmlau]

With the new extension @loopback/authentication-jwt, we're going to tailor the tutorial to use that extension. See loopbackio/loopback-next#5421.

[joeytwiddle]

I had wanted to share a JWT-free approach, for developers who perhaps want to integrate with an existing authentication system (e.g. migrating an existing service to Loopback).

I wanted to show the very basics of LB authentication, with few assumptions, so the developer can fill in their specific method. (Although I did assume OAuth2 in the end!)

Anyway that was just my use case. Please do whatever the developers are asking for!

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.