README.md

lbx-jwt

This packages aims to take care of most of your authentication and authorization concerns.

It's inspired by @loopback/authentication-jwt but adds a lot more functionality, including:

• Saving roles inside jwts
• Handling refresh tokens and automatic reuse detection
• Add the possibility to use two factor authentication for specific requests (The jwt strategy reads out a specific header for this to work)
• Providing an out of the box controller for:
  • login
  • logout
  • refreshing the token
  • requesting the reset of a password (Including an html email sent to the user or saved locally, depending on the environment)
  • confirming and actually resetting the password
  • Activating and Deactivating two factor authentication
• Providing a simple role authorizer to use with the @authorize decorator

Usage

Register the component

The minimum required code changes to use the library to its full extend is simply registering it in the application.ts:

import { BaseUserRepository, CredentialsRepository, LbxJwtBindings, LbxJwtComponent, RefreshTokenRepository, PasswordResetTokenRepository, LbxJwtAuthController } from 'lbx-jwt';
import { AuthenticationComponent } from '@loopback/authentication';
import { AuthorizationBindings, AuthorizationComponent, AuthorizationDecision, AuthorizationOptions } from '@loopback/authorization';

export class MyApplication extends BootMixin(ServiceMixin(RepositoryMixin(RestApplication))) {
    constructor(options: ApplicationConfig = {}) {
        // ...
        this.component(AuthenticationComponent);
        this.component(LbxJwtComponent);
        this.bind(LbxJwtBindings.ACCESS_TOKEN_SECRET).to('JwtS3cr3t');
        this.bind(LbxJwtBindings.REFRESH_TOKEN_SECRET).to('JwtR3fr3shS3cr3t');
        this.bind(LbxJwtBindings.MAIL_SERVICE).toClass(MailService);
        this.repository(BaseUserRepository);
        this.repository(CredentialsRepository);
        this.repository(RefreshTokenRepository);
        this.repository(PasswordResetTokenRepository);
        this.controller(LbxJwtAuthController);

        const authOptions: AuthorizationOptions = {
            precedence: AuthorizationDecision.DENY,
            defaultDecision: AuthorizationDecision.DENY
        };
        this.configure(AuthorizationBindings.COMPONENT).to(authOptions);
        this.component(AuthorizationComponent);
        // ...
    }
}

If you don't want to use the predefined controller you can omit the this.controller(LbxJwtAuthController); part.

Almost everything above comes from the library out of the box. You only need to create your own MailService.

Create your own MailService

@injectable({ scope: BindingScope.TRANSIENT })
export class MailService extends BaseMailService<Roles> {
    protected readonly WEBSERVER_MAIL: string = 'webserver@test.com';
    protected readonly BASE_RESET_PASSWORD_LINK: string = 'http://localhost:4200/reset-password';
    protected readonly webserverMailTransporter: Transporter;
    protected readonly PRODUCTION: boolean = false;
    protected readonly SAVED_EMAILS_PATH: string = path.join(__dirname, '../../../test-emails');
    protected readonly LOGO_HEADER_URL: string = 'https://via.placeholder.com/165x165';
    protected readonly LOGO_FOOTER_URL: string = 'https://via.placeholder.com/500x60';
    protected readonly ADDRESS_LINES: string[] = ['my address', 'my name'];
}

Create your own biometric credentials service

@bind({ scope: BindingScope.TRANSIENT })
export class BiometricCredentialsService extends BaseBiometricCredentialsService {
    protected readonly RP_NAME: string = 'Test';
    protected readonly RP_DOMAIN: string = 'localhost';
}

Enjoy!

That's it, now you can use it inside your code:

import { roleAuthorization } from 'lbx-jwt';
// ...
@authenticate('jwt')
@authorize({ voters: [roleAuthorization], allowedRoles: ['admin'] })
getAdminExclusiveData(): string {
    // ...
}
// ...

Two Factor Authentication

To use two factor authentication, you first need to call /2fa/turn-on and display a qrCode with the returned otp link.

Then you need to call /2fa/confirm-turn-on with a 6 digit code generated by eg. Google Authenticator. This code needs to be passed as a custom http header. The header name can be overriden (LbxJwtBindings,TWO_FACTOR_HEADER) by default it is "X-Authorization-2FA".

Now that two factor authentication is setup the user gets prompted to enter his two factor code when he tries to login.

If you want to enable the feature for other endpoints aswell, you can configure the @authenticate decorator accordingly:

// ...
@authenticate({ strategy: 'jwt', options: { require2fa: true } })
doSomethingThatRequiresATwoFactorCode(): string {
    // ...
}
// ...

Customization

The library is highly customizable through the usage of Bindings.

Almost everything can be overriden by you when you provide a value for the specific Binding:

import { LbxJwtBindings } from 'lbx-jwt';
// ...
this.bind(LbxJwtBindings.ACCESS_TOKEN_EXPIRES_IN_MS).to(1234567);
// ...

All bindings can be accessed under LbxJwtBindings.