diff --git a/docs/site/migration/auth/built-in.md b/docs/site/migration/auth/built-in.md index 6c7e822511d4..f7447e3d9055 100644 --- a/docs/site/migration/auth/built-in.md +++ b/docs/site/migration/auth/built-in.md @@ -6,8 +6,129 @@ 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 + +### 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 diff --git a/docs/site/migration/auth/example.md b/docs/site/migration/auth/example.md new file mode 100644 index 000000000000..9104051bfcff --- /dev/null +++ b/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 diff --git a/docs/site/migration/auth/overview.md b/docs/site/migration/auth/overview.md index 3ab4007e35b8..4a37db055456 100644 --- a/docs/site/migration/auth/overview.md +++ b/docs/site/migration/auth/overview.md @@ -6,23 +6,60 @@ 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 + +- AuthenticationStrategy +- PassportAdapter + +### Authorization + +- Authorizer +- Use your own interceptor for authorization diff --git a/docs/site/migration/auth/passport.md b/docs/site/migration/auth/passport.md index 82b25fb8b735..f8d65981ae1c 100644 --- a/docs/site/migration/auth/passport.md +++ b/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