Required dependencies

npm install @loopback/authentication @loopback/authorization
npm install @loopback/core @loopback/context @loopback/rest @loopback/security
npm install @loopback/metadata
# TypeScript peer requirements
npm install --save-dev typescript @types/node

No native modules, no pod install, no Android linking required. All packages are pure TypeScript/JavaScript.

Project setup

1. Copy the source/ directory into your project root, e.g. vendor/loopback/.

2. If you are working from source (not installed npm packages), add path aliases in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@loopback/authentication": ["./vendor/loopback/authentication/src"],
      "@loopback/authorization": ["./vendor/loopback/authorization/src"],
      "@loopback/core": ["./vendor/loopback/core/src"],
      "@loopback/context": ["./vendor/loopback/context/src"],
      "@loopback/rest": ["./vendor/loopback/rest/src"],
      "@loopback/security": ["./vendor/loopback/security/src"]
    },
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "strict": true,
    "target": "ES2018",
    "module": "commonjs"
  }
}

3. experimentalDecorators and emitDecoratorMetadata are mandatory; the decorator system will silently fail without them.

4. Register the authentication component in your application class:

import {AuthenticationComponent} from '@loopback/authentication';
import {AuthorizationComponent} from '@loopback/authorization';

this.component(AuthenticationComponent);
this.component(AuthorizationComponent);

5. No required environment variables for the packages themselves. If implementing JWT, supply your secret via process.env.JWT_SECRET in your own token service implementation.

Public API

authenticate

function authenticate(
  strategyName: string,
  options?: object,
): MethodDecorator & ClassDecorator;

Decorates a controller method (or class) to require a named authentication strategy. The REST sequence will invoke the matching strategy and reject unauthenticated requests before the method body executes. Use it on any route that must be protected.

AuthenticationComponent

class AuthenticationComponent implements Component {
  providers?: ProviderMap;
  bindings?: Binding[];
}

A LoopBack 4 Component that registers all authentication providers (AuthMetadataProvider, AuthenticateActionProvider, AuthenticationStrategyProvider) into the application context. Mount it once in your Application constructor via this.component(AuthenticationComponent).

TokenService

interface TokenService {
  verifyToken(token: string): Promise<UserProfile>;
  generateToken(userProfile: UserProfile): Promise<string>;
}

An interface (from authentication/src/services/token.service.ts) that your JWT or session token logic must implement. Bind your concrete class to AuthenticationBindings.TOKEN_SERVICE so the framework can inject it wherever token operations are needed.

UserService

interface UserService<U, C> {
  verifyCredentials(credentials: C): Promise<U>;
  convertToUserProfile(user: U): UserProfile;
}

Abstracts credential verification and user-to-profile conversion. Implement this interface and bind it to wire your database/user-store into the authentication pipeline.

authorize

function authorize(spec: AuthorizationMetadata): MethodDecorator & ClassDecorator;

From @loopback/authorization. Decorates controller methods with authorization rules (allowed roles, denied roles, scopes). The AuthorizeInterceptor reads this metadata and invokes registered voters/enforcers before allowing method execution.

Working examples

Scenario - Protecting a route with a named strategy

A REST controller method that requires callers to present a valid JWT.

import {authenticate} from '@loopback/authentication';
import {get} from '@loopback/rest';
import {SecurityBindings, UserProfile} from '@loopback/security';
import {inject} from '@loopback/core';

export class ProfileController {
  @authenticate('jwt')
  @get('/me')
  async whoAmI(
    @inject(SecurityBindings.USER) currentUser: UserProfile,
  ): Promise<UserProfile> {
    return currentUser;
  }
}

The 'jwt' string must match the name property of a registered AuthenticationStrategy implementation. If no strategy matches, the framework throws a 401.

Scenario - Implementing and registering a JWT TokenService

Wire a concrete TokenService into the authentication component.

import {injectable, BindingScope} from '@loopback/core';
import {UserProfile, securityId} from '@loopback/security';
import {TokenService} from '@loopback/authentication';
import * as jwt from 'jsonwebtoken';

@injectable({scope: BindingScope.SINGLETON})
export class JWTService implements TokenService {
  private secret = process.env.JWT_SECRET ?? 'change-me';

  async verifyToken(token: string): Promise<UserProfile> {
    const decoded = jwt.verify(token, this.secret) as {id: string; email: string};
    return {[securityId]: decoded.id, email: decoded.email};
  }

  async generateToken(userProfile: UserProfile): Promise<string> {
    return jwt.sign(
      {id: userProfile[securityId], email: userProfile.email},
      this.secret,
      {expiresIn: '1h'},
    );
  }
}

// In your Application constructor:
// import {AuthenticationBindings} from '@loopback/authentication';
// this.bind(AuthenticationBindings.TOKEN_SERVICE).toClass(JWTService);

Scenario - Role-based authorization on a controller method

Restrict an admin endpoint to users with the admin role using @authorize.

import {authenticate} from '@loopback/authentication';
import {authorize} from '@loopback/authorization';
import {del, param} from '@loopback/rest';

export class UserAdminController {
  @authenticate('jwt')
  @authorize({allowedRoles: ['admin']})
  @del('/users/{id}')
  async deleteUser(@param.path.string('id') id: string): Promise<void> {
    // Only reachable when the JWT principal has role 'admin'
    await this.userRepository.deleteById(id);
  }
}

The AuthorizationComponent must be registered and at least one authorizer (voter function or class) must be bound to AuthorizationBindings.AUTHORIZER for the interceptor to make a decision.

File walkthrough

• authentication/src/index.ts - Package entry; re-exports everything from component, decorators, keys, providers, services, and types.
• authentication/src/authentication.component.ts - Declares and registers all authentication providers as a single mountable component.
• authentication/src/decorators/authenticate.decorator.ts - Implements the @authenticate(strategyName) method/class decorator.
• authentication/src/keys.ts - Binding keys (AuthenticationBindings) for strategy, token service, user service, and metadata.
• authentication/src/types.ts - Core TypeScript interfaces: AuthenticationStrategy, AuthenticationMetadata.
• authentication/src/providers/auth-action.provider.ts - REST sequence action that triggers authentication for each request.
• authentication/src/providers/auth-metadata.provider.ts - Reads @authenticate metadata from the current route's controller method.
• authentication/src/providers/auth-strategy.provider.ts - Resolves the correct registered strategy by name for the current request.
• authentication/src/services/token.service.ts - TokenService interface definition.
• authentication/src/services/user-identity.service.ts - UserIdentityService interface for linking external identities to local users.
• authentication/src/services/user.service.ts - UserService interface for credential verification and profile conversion.
• authentication/docs/ - Detailed markdown guides for each auth strategy (JWT, OAuth2, SAML, OIDC, Basic).
• authorization/src/index.ts - Package entry; re-exports component, interceptor, decorator, keys, and types.
• authorization/src/authorization-component.ts - Mounts the authorization interceptor and default bindings.
• authorization/src/authorize-interceptor.ts - Global interceptor that reads @authorize metadata and calls registered voters.
• authorization/src/decorators/authorize.ts - Implements the @authorize(spec) decorator.
• authorization/src/keys.ts - AuthorizationBindings keys for authorizers, metadata, and options.
• authorization/src/types.ts - Interfaces: AuthorizationContext, AuthorizationMetadata, Authorizer, AuthorizationDecision.

Common pitfalls and fixes

• Missing emitDecoratorMetadata: Injections silently receive undefined. Fix: set "emitDecoratorMetadata": true in tsconfig.json.
• Strategy name mismatch: @authenticate('jwt') fails with "strategy not found" if the registered strategy's name property differs. Fix: ensure strategy.name === 'jwt' exactly.
• Component not mounted: Authentication/authorization is silently skipped if this.component(AuthenticationComponent) is omitted. Fix: add both components in the Application constructor before starting the server.
• No authorizer bound: @authorize has no effect and requests pass through if no voter is bound to AuthorizationBindings.AUTHORIZER. Fix: bind at least one authorizer function or class.
• ESM/CJS interop with jsonwebtoken: import jwt from 'jsonwebtoken' may fail in strict ESM. Fix: use import * as jwt from 'jsonwebtoken' or set "esModuleInterop": true in tsconfig.json.
• SecurityBindings.USER injection returning undefined: The UserProfile is only populated after the auth action runs. Fix: ensure your sequence calls await this.authenticateRequest(request) before invoking the controller.

Vibe-coding prompt template

I have a LoopBack 4 backend project and I have placed the LoopBack 4 core
packages source under `vendor/loopback/` (from the `source/` directory
described in USAGE.md). I also have USAGE.md open for reference.

Please help me integrate `@loopback/authentication` and `@loopback/authorization`
into my project step by step:

1. Read USAGE.md and `vendor/loopback/authentication/src/index.ts` to understand
   all available exports.
2. Add the required tsconfig paths so TypeScript resolves `@loopback/authentication`
   and `@loopback/authorization` from `vendor/loopback/`.
3. Register `AuthenticationComponent` and `AuthorizationComponent` in my
   Application class (`src/application.ts`).
4. Create a `JWTService` implementing the `TokenService` interface from
   `@loopback/authentication` and bind it to `AuthenticationBindings.TOKEN_SERVICE`.
5. Create a JWT `AuthenticationStrategy` class, register it, and show me how
   to use `@authenticate('jwt')` on a controller method.
6. Add `@authorize({allowedRoles: ['admin']})` to an existing controller method
   and create a simple role-based authorizer voter function.
7. Show me how to write a unit test using `@loopback/testlab` to verify
   that an unauthenticated request returns 401.

Use only the real exported symbols from USAGE.md. Do not invent APIs.
Reference the upstream package: loopback-monorepo (loopbackio/loopback-next).

License and credit

The source is licensed under the MIT License (see source/authentication/LICENSE and source/authorization/LICENSE). Original work is copyright IBM Corp. and LoopBack contributors.

Upstream repository: https://github.com/loopbackio/loopback-next Official documentation: https://loopback.io/doc/en/lb4/

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.