lang | title | keywords | sidebar | permalink |
---|---|---|---|---|
en |
Authentication |
LoopBack 4.0, LoopBack 4 |
lb4_sidebar |
/doc/en/lb4/Loopback-component-authentication.html |
Security is of paramount importance when developing a web or mobile application and usually consists of two distinct pieces:
- Authentication
- Authorization
Authentication is a process of verifying someone's identity before a protected resource is accessed.
Authorization is a process of deciding if a user can perform an action on a protected resource.
{% include note.html content="
For a description of an Authorization
process, please see Authorization.
" %}
This document describes the details of the LoopBack 4 Authentication
component
from the @loopback/authentication
package.
Here is a high level overview of the authentication component.
- A decorator to express an authentication requirement on controller methods
- A provider to access method-level authentication metadata
- An action in the REST sequence to enforce authentication
- An extension point to discover all authentication strategies and handle the delegation
Here is a detailed overview of the authentication component.
Basically, to secure your API endpoints, you need to:
- decorate the endpoints of a controller with the
@authenticate(strategyName, options?)
decorator (app developer) - insert the authentication action in a custom sequence (app developer)
- create a custom authentication strategy with a unique name (extension developer)
- register the custom authentication strategy (app developer)
The Authentication Component takes care of the rest.
npm install --save @loopback/authentication
To utilize authentication
in an application application.ts
, you must load
the authentication component named AuthenticationComponent
.
export class MyApplication extends BootMixin(
ServiceMixin(RepositoryMixin(RestApplication)),
) {
constructor(options?: ApplicationConfig) {
super(options);
//...
this.component(AuthenticationComponent);
//...
}
}
The AuthenticationComponent
is defined as follows:
export class AuthenticationComponent implements Component {
providers?: ProviderMap;
constructor() {
this.providers = {
[AuthenticationBindings.AUTH_ACTION.key]: AuthenticateActionProvider,
[AuthenticationBindings.STRATEGY.key]: AuthenticationStrategyProvider,
[AuthenticationBindings.METADATA.key]: AuthMetadataProvider,
};
}
}
As you can see, there are a few providers which make up the bulk of the authenticaton component.
Essentially
- The binding key
AuthenticationBindings.AUTH_ACTION.key
is bound toAuthenticateActionProvider
which returns an authenticating function of typeAuthenticateFn
- The binding key
AuthenticationBindings.STRATEGY.key
is bound toAuthenticationStrategyProvider
which resolves and returns an authentication strategy of typeAuthenticationStrategy
- The binding key
AuthenticationBindings.METADATA.key
is bound toAuthMetadataProvider
which returns authentication decorator metadata of typeAuthenticationMetadata
The purpose of these providers and the values they return will be explained in the sections below.
Securing your application's API endpoints is done by decorating controller functions with the Authentication Decorator.
The decorator's syntax is:
@authenticate(strategyName: string, options?: object)
The strategyName is the unique name of the authentication strategy.
When the options object is specified, it must be relevant to that particular strategy.
Here is an example of the decorator using a custom authentication strategy named
'basic' without options, for the endpoint /whoami
in a controller named
WhoAmIController
. (We will
create and
register the 'basic'
authentication strategy in later sections)
import {inject} from '@loopback/context';
import {
AuthenticationBindings,
UserProfile,
authenticate,
} from '@loopback/authentication';
import {get} from '@loopback/rest';
export class WhoAmIController {
constructor(
@inject(AuthenticationBindings.CURRENT_USER)
private userProfile: UserProfile,
) {}
@authenticate('basic')
@get('/whoami')
whoAmI(): string {
return this.userProfile.id;
}
}
An example of the decorator when options are specified looks like this:
@authenticate('basic', { /* some options for the strategy */})
{% include tip.html content=" To avoid repeating the same options in the @authenticate decorator for many endpoints in a controller, you can instead define global options which can be injected into an authentication strategy thereby allowing you to avoid specifying the options object in the decorator itself. For controller endpoints that need to override a global option, you can specify it in an options object passed into the decorator. Your authentication strategy would need to handle the option overrides. " %}
After a request is successfully authenticated, the current user profile is
available on the request context. You can obtain it via dependency injection by
using the AuthenticationBindings.CURRENT_USER
binding key.
Parameters of the @authenticate
decorator can be obtained via dependency
injection using the AuthenticationBindings.METADATA
binding key. It returns
data of type AuthenticationMetadata
provided by AuthMetadataProvider
. The
AuthenticationStrategyProvider
, discussed in a later section, makes use of
AuthenticationMetadata
to figure out what name you specified as a
parameter in the @authenticate
decorator of a specific controller endpoint.
In a LoopBack 4 application with REST API endpoints, each request passes through a stateless grouping of actions called a Sequence.
Here is an example of the default sequence that is created in a LoopBack 4 application.
export class DefaultSequence implements SequenceHandler {
/**
* Constructor: Injects findRoute, invokeMethod & logError
* methods as promises.
*
* @param {FindRoute} findRoute Finds the appropriate controller method,
* spec and args for invocation (injected via SequenceActions.FIND_ROUTE).
* @param {ParseParams} parseParams The parameter parsing function (injected
* via SequenceActions.PARSE_PARAMS).
* @param {InvokeMethod} invoke Invokes the method specified by the route
* (injected via SequenceActions.INVOKE_METHOD).
* @param {Send} send The action to merge the invoke result with the response
* (injected via SequenceActions.SEND)
* @param {Reject} reject The action to take if the invoke returns a rejected
* promise result (injected via SequenceActions.REJECT).
*/
constructor(
@inject(SequenceActions.FIND_ROUTE) protected findRoute: FindRoute,
@inject(SequenceActions.PARSE_PARAMS) protected parseParams: ParseParams,
@inject(SequenceActions.INVOKE_METHOD) protected invoke: InvokeMethod,
@inject(SequenceActions.SEND) public send: Send,
@inject(SequenceActions.REJECT) public reject: Reject,
) {}
/**
* Runs the default sequence. Given a handler context (request and response),
* running the sequence will produce a response or an error.
*
* Default sequence executes these steps
* - Finds the appropriate controller method, swagger spec
* and args for invocation
* - Parses HTTP request to get API argument list
* - Invokes the API which is defined in the Application Controller
* - Writes the result from API into the HTTP response
* - Error is caught and logged using 'logError' if any of the above steps
* in the sequence fails with an error.
*
* @param context The request context: HTTP request and response objects,
* per-request IoC container and more.
*/
async handle(context: RequestContext): Promise<void> {
try {
const {request, response} = context;
const route = this.findRoute(request);
const args = await this.parseParams(request, route);
const result = await this.invoke(route, args);
debug('%s result -', route.describe(), result);
this.send(response, result);
} catch (error) {
this.reject(context, error);
}
}
}
By default, authentication is not part of the sequence of actions, so you must create a custom sequence and add the authentication action.
An authentication action AuthenticateFn
is provided by the
AuthenticateActionProvider
class.
AuthenticateActionProvider
is defined as follows:
export class AuthenticateActionProvider implements Provider<AuthenticateFn> {
constructor(
// The provider is instantiated for Sequence constructor,
// at which time we don't have information about the current
// route yet. This information is needed to determine
// what auth strategy should be used.
// To solve this, we are injecting a getter function that will
// defer resolution of the strategy until authenticate() action
// is executed.
@inject.getter(AuthenticationBindings.STRATEGY)
readonly getStrategy: Getter<AuthenticationStrategy>,
@inject.setter(AuthenticationBindings.CURRENT_USER)
readonly setCurrentUser: Setter<UserProfile>,
) {}
/**
* @returns authenticateFn
*/
value(): AuthenticateFn {
return request => this.action(request);
}
/**
* The implementation of authenticate() sequence action.
* @param request The incoming request provided by the REST layer
*/
async action(request: Request): Promise<UserProfile | undefined> {
const strategy = await this.getStrategy();
if (!strategy) {
// The invoked operation does not require authentication.
return undefined;
}
const userProfile = await strategy.authenticate(request);
if (!userProfile) {
// important to throw a non-protocol-specific error here
let error = new Error(
`User profile not returned from strategy's authenticate function`,
);
Object.assign(error, {
code: USER_PROFILE_NOT_FOUND,
});
throw error;
}
this.setCurrentUser(userProfile);
return userProfile;
}
}
AuthenticateActionProvider
's value()
function returns a function of type
AuthenticateFn
. This function attempts to obtain an authentication strategy
(resolved by AuthenticationStrategyProvider
via the
AuthenticationBindings.STRATEGY
binding). If no authentication strategy
was specified for this endpoint, the action immediately returns. If an
authentication strategy was specified for this endpoint, its
authenticate(request)
function is called. If a user profile is returned, this
means the user was authenticated successfully, and the user profile is added to
the request context (via the AuthenticationBindings.CURRENT_USER
binding);
otherwise an error is thrown.
Here is an example of a custom sequence which utilizes the authentication
action.
export class MyAuthenticatingSequence implements SequenceHandler {
constructor(
@inject(SequenceActions.FIND_ROUTE) protected findRoute: FindRoute,
@inject(SequenceActions.PARSE_PARAMS)
protected parseParams: ParseParams,
@inject(SequenceActions.INVOKE_METHOD) protected invoke: InvokeMethod,
@inject(SequenceActions.SEND) protected send: Send,
@inject(SequenceActions.REJECT) protected reject: Reject,
@inject(AuthenticationBindings.AUTH_ACTION)
protected authenticateRequest: AuthenticateFn,
) {}
async handle(context: RequestContext) {
try {
const {request, response} = context;
const route = this.findRoute(request);
//call authentication action
await this.authenticateRequest(request);
// Authentication successful, proceed to invoke controller
const args = await this.parseParams(request, route);
const result = await this.invoke(route, args);
this.send(response, result);
} catch (error) {
//
// The authentication action utilizes a strategy resolver to find
// an authentication strategy by name, and then it calls
// strategy.authenticate(request).
//
// The strategy resolver throws a non-http error if it cannot
// resolve the strategy. When the strategy resolver obtains
// a strategy, it calls strategy.authenticate(request) which
// is expected to return a user profile. If the user profile
// is undefined, then it throws a non-http error.
//
// It is necessary to catch these errors and add HTTP-specific status
// code property.
//
// Errors thrown by the strategy implementations already come
// with statusCode set.
//
// In the future, we want to improve `@loopback/rest` to provide
// an extension point allowing `@loopback/authentication` to contribute
// mappings from error codes to HTTP status codes, so that application
// don't have to map codes themselves.
if (
error.code === AUTHENTICATION_STRATEGY_NOT_FOUND ||
error.code === USER_PROFILE_NOT_FOUND
) {
Object.assign(error, {statusCode: 401 /* Unauthorized */});
}
this.reject(context, error);
return;
}
}
}
Notice the new dependency injection in the sequence's contructor.
@inject(AuthenticationBindings.AUTH_ACTION)
protected authenticateRequest: AuthenticateFn,
The binding key AuthenticationBindings.AUTH_ACTION
gives us access to the
authentication function authenticateRequest
of type AuthenticateFn
provided
by AuthenticateActionProvider
.
Now the authentication function authenticateRequest
can be called in our
custom sequence anywhere before
the invoke
action in order secure the
endpoint.
There are two particular protocol-agnostic errors
AUTHENTICATION_STRATEGY_NOT_FOUND
and USER_PROFILE_NOT_FOUND
which must be
addressed in the sequence, and given an HTTP status code of 401 (UnAuthorized).
It is up to the developer to throw the appropriate HTTP error code from within a custom authentications strategy or its custom services.
If any error is thrown during the authentication process, the controller function of the endpoint is never executed.
Now that we've defined a custom sequence that performs an authentication action
on every request, we must bind it to the application application.ts
export class MyApplication extends BootMixin(
ServiceMixin(RepositoryMixin(RestApplication)),
) {
constructor(options?: ApplicationConfig) {
super(options);
//...
this.sequence(MyAuthenticatingSequence);
//...
}
}
Support for multiple authentication strategies is possible with a common authentication strategy interface, and an extensionPoint/extensions pattern used to register and discover authentication strategies.
The AuthenticationComponent
declares a common authentication strategy
interface named AuthenticationStrategy
.
export interface AuthenticationStrategy {
/**
* The 'name' property is a unique identifier for the
* authentication strategy (for example: 'basic', 'jwt', etc)
*/
name: string;
/**
* The 'authenticate' method takes in a given request and returns a user profile
* which is an instance of 'UserProfile'.
* (A user profile is a minimal subset of a user object)
* If the user credentials are valid, this method should return a 'UserProfile' instance.
* If the user credentials are invalid, this method should throw an error
* If the user credentials are missing, this method should throw an error, or return 'undefined'
* and let the authentication action deal with it.
*
* @param request - Express request object
*/
authenticate(request: Request): Promise<UserProfile | undefined>;
}
Developers that wish to create a custom authentication strategy must implement
this interface. The custom authentication strategy must have a unique name
and have an authenticate
function which takes in a request and returns the
user profile of an authenticated user.
Here is an example of a basic authentication strategy
BasicAuthenticationStrategy
with the name 'basic'
in
basic-strategy.ts
:
export interface Credentials {
username: string;
password: string;
}
export class BasicAuthenticationStrategy implements AuthenticationStrategy {
name: string = 'basic';
constructor(
@inject(UserServiceBindings.USER_SERVICE)
private userService: UserService,
) {}
async authenticate(request: Request): Promise<UserProfile | undefined> {
const credentials: Credentials = this.extractCredentials(request);
const user = await this.userService.verifyCredentials(credentials);
const userProfile = this.userService.convertToUserProfile(user);
return userProfile;
}
extractCredentials(request: Request): Credentials {
let creds: Credentials;
/**
* Code to extract the 'basic' user credentials from the Authorization header
*/
return creds;
}
}
As you can see in the example, an authentication strategy can inject custom services to help it accomplish certain tasks. See the complete examples for basic authentication strategy and jwt authentication strategy.
The AuthenticationComponent
component also provides two optional service
interfaces which may be of use to your application:
UserService
and
TokenService.
The registration and discovery of authentication strategies is possible via the Extension Point and Extensions pattern.
You don't have to worry about the discovery of authentication strategies,
this is taken care of by AuthenticationStrategyProvider
which resolves and
returns an authentication strategy of type AuthenticationStrategy
.
The AuthenticationStrategyProvider
class (shown below) declares an
extension point
named
AuthenticationBindings.AUTHENTICATION_STRATEGY_EXTENSION_POINT_NAME
via the
@extensionPoint
decorator. The binding scope is set to transient because
an authentication strategy may differ with each request.
With the aid of metadata of type AuthenticationMetadata
(provided by
AuthMetadataProvider
and injected via the AuthenticationBindings.METADATA
binding key), the name of the authentication strategy, specified in the
@authenticate
decorator for this request, is obtained.
Then, with the aid of the @extensions()
getter decorator,
AuthenticationStrategyProvider
is responsible for finding and
returning the authentication strategy which has that specific name and
has been registered
as an extension of the aforementioned extension
point.
@extensionPoint(
AuthenticationBindings.AUTHENTICATION_STRATEGY_EXTENSION_POINT_NAME,
{scope: BindingScope.TRANSIENT},
) //this needs to be transient, e.g. for request level context.
export class AuthenticationStrategyProvider
implements Provider<AuthenticationStrategy | undefined> {
constructor(
@extensions()
private authenticationStrategies: Getter<AuthenticationStrategy[]>,
@inject(AuthenticationBindings.METADATA)
private metadata?: AuthenticationMetadata,
) {}
async value(): Promise<AuthenticationStrategy | undefined> {
if (!this.metadata) {
return undefined;
}
const name = this.metadata.strategy;
const strategy = await this.findAuthenticationStrategy(name);
if (!strategy) {
// important to throw a non-protocol-specific error here
let error = new Error(`The strategy '${name}' is not available.`);
Object.assign(error, {
code: AUTHENTICATION_STRATEGY_NOT_FOUND,
});
throw error;
}
return strategy;
}
async findAuthenticationStrategy(name: string) {
const strategies = await this.authenticationStrategies();
const matchingAuthStrategy = strategies.find(a => a.name === name);
return matchingAuthStrategy;
}
}
In order for your custom authentication strategy to be found, it needs to be registered.
Registering a custom authentication strategy BasicAuthenticationStrategy
as an extension of the
AuthenticationBindings.AUTHENTICATION_STRATEGY_EXTENSION_POINT_NAME
extension
point in an application application.ts
is as simple as:
import {registerAuthenticationStrategy} from '@loopback/authentication';
export class MyApplication extends BootMixin(
ServiceMixin(RepositoryMixin(RestApplication)),
) {
constructor(options?: ApplicationConfig) {
super(options);
//...
registerAuthenticationStrategy(this, BasicAuthenticationStrategy);
//...
}
}
We've gone through the main steps for adding authentication
to your LoopBack 4
application.
Your application.ts
should look similar to this:
import {
AuthenticationComponent,
registerAuthenticationStrategy,
} from '@loopback/authentication';
export class MyApplication extends BootMixin(
ServiceMixin(RepositoryMixin(RestApplication)),
) {
constructor(options?: ApplicationConfig) {
super(options);
/* set up miscellaneous bindings */
//...
// load the authentication component
this.component(AuthenticationComponent);
// register your custom authentication strategy
registerAuthenticationStrategy(this, BasicAuthenticationStrategy);
// use your custom authenticating sequence
this.sequence(MyAuthenticatingSequence);
this.static('/', path.join(__dirname, '../public'));
this.projectRoot = __dirname;
this.bootOptions = {
controllers: {
dirs: ['controllers'],
extensions: ['.controller.js'],
nested: true,
},
};
}
You can find a working example of a LoopBack 4 shopping cart application with JWT authentication here.