diff --git a/docs/site/Authentication-component-decorator.md b/docs/site/Authentication-component-decorator.md index b600ad574ec2..616f6bdf2754 100644 --- a/docs/site/Authentication-component-decorator.md +++ b/docs/site/Authentication-component-decorator.md @@ -18,15 +18,25 @@ functions with the The decorator's syntax is: -```ts -@authenticate(strategyName: string, options?: object) -``` - -or - -```ts -@authenticate(metadata: AuthenticationMetadata) -``` +- single strategy: `@authenticate(strategyName)` +- multiple strategies: `@authenticate(strategyName1, strategyName2)` +- single strategy with options: + ```ts + @authenticate({ + strategy: strategyName, + options: {option1: 'value1', option2: 'value2'} + }) + ``` +- multiple strategies with options: + ```ts + @authenticate({ + strategy: strategyName1, + options: {option1: 'value1'} + }, { + strategy: strategyName2, + options: {option2: 'value2'} + }) + ``` The **`strategyName`** is the **unique** name of the authentication strategy. @@ -73,7 +83,7 @@ export class WhoAmIController { An example of the decorator when options **are** specified looks like this: ```ts -@authenticate('basic', { /* some options for the strategy */}) +@authenticate({strategy: 'basic', options: { /* some options for the strategy */}}) ``` {% include tip.html content=" diff --git a/docs/site/decorators/Decorators_authenticate.md b/docs/site/decorators/Decorators_authenticate.md index 72cbffff7642..2893c1c920b2 100644 --- a/docs/site/decorators/Decorators_authenticate.md +++ b/docs/site/decorators/Decorators_authenticate.md @@ -10,11 +10,32 @@ permalink: /doc/en/lb4/Decorators_authenticate.html ## Authentication Decorator -Syntax: `@authenticate(strategyName: string, options?: object)` or -`@authenticate(metadata: AuthenticationMetadata)` +Syntax: -Marks a controller method as needing an authenticated user. This decorator -requires a strategy name as a parameter. +- single strategy: `@authenticate(strategyName)` +- multiple strategies: `@authenticate(strategyName1, strategyName2)` +- single strategy with options: + ```ts + @authenticate({ + strategy: strategyName, + options: {option1: 'value1', option2: 'value2'} + }) + ``` +- multiple strategies with options: + ```ts + @authenticate({ + strategy: strategyName1, + options: {option1: 'value1'} + }, { + strategy: strategyName2, + options: {option2: 'value2'} + }) + ``` + +To mark a controller method as needing an authenticated user, the decorator +requires one or more strategies. + +### Method Level Decorator Here's an example using 'BasicStrategy': to authenticate user in function `whoAmI`: @@ -38,6 +59,8 @@ export class WhoAmIController { } ``` +### Class Level Decorator + To configure a default authentication for all methods within a class, `@authenticate` can also be applied at the class level. In the code below, `whoAmI` is protected with `BasicStrategy` even though there is no @@ -68,3 +91,38 @@ export class WhoAmIController { For more information on authentication with LoopBack, visit [here](../Loopback-component-authentication.md). + +### Multiple Strategies + +`@authenticate()` can takes in more than one strategy. For example: + +```ts +import {inject} from '@loopback/core'; +import {securityId, SecurityBindings, UserProfile} from '@loopback/security'; +import {authenticate} from '@loopback/authentication'; +import {get} from '@loopback/rest'; + +export class WhoAmIController { + constructor(@inject(SecurityBindings.USER) private user: UserProfile) {} + + @authenticate('BasicStrategy', 'JWTStrategy') + @get('/whoami') + whoAmI(): string { + return this.user[securityId]; + } +} +``` + +The logic on how the strategies are executed is similar to how +[passport.js](http://www.passportjs.org/) does it: + +- The authentication strategies will be executed in the provided order. +- If at least one authentication strategy succeeds, the request will be further + processed without throwing an error. +- Once a strategy succeeds or redirects, all subsequent strategies will not be + evaluated. +- If all strategies fail, an error will be thrown with the error message of the + first provided strategy. + +{% include note.html content="It is not feasible to use multiple strategies that redirect (e.g. OAuth login redirects) since the first redirect will halt the execution chain. +" %}