authentication-service

@sourceloop/authentication-service

Overview

A Microservice for handling authentications. It provides -

• Multi-Tenant support, you can see the database schema here.
• External Identity Provider integration.
• Ability to issue JWT tokens using jsonwebtoken.
• Authenticate JWT tokens using passport-http-bearer.
• Local Signup using a signup token.
• Forgot/Reset/Change password.
• Google OAuth using passport-google-oauth.
• Keycloak OAuth using passport-keycloak-bearer.
• Instagram OAuth using passport-instagram.
• Facebook OAuth using passport-facebook.
• Apple OAuth using passport-apple.
• Cognito OAuth using passport-cognito-oauth2.
• SAML Authentication using @node-saml/passport-saml.
• OTP Auth using custom passport otp strategy.
• Two-Factor Authentication.
• Maintain daily active users.

To get started with a basic implementation of this service, see /sandbox/auth-basic-example.

For a more elaborate and custom implementation that overrides the default models and repositories, see /sandbox/auth-multitenant-example.

Working and Flow

This module uses the decorators provided by loopback4-authentication and loopback4-authorization. For reference, below is the flow for the login code generation that uses the authenticate client, authenticate user and authorization decorators from these npm packages -

Maintaining the activity of the users

Whenever a user logins in to the system we make an entry in the login_activity table marking the users login time and his details. The login type can be "ACCESS","RELOGIN","LOGOUT" based on the action taken by the user. This way a track can be maintained. Api to fetch daily/monthly active users is available that gives a list of active users for the provided date range based on users selection. The actor field is configurable. The dafault value is user.id but can be changed by binding the appropriate field to AuthServiceBindings.ActorIdKey.

this.application.bind(AuthServiceBindings.ActorIdKey).to('id');

Installation

npm i @sourceloop/authentication-service

Usage

• Create a new Loopback4 Application (If you don't have one already) lb4 testapp

• Install the authentication service npm i @sourceloop/authentication-service

• Set the environment variables.

• Run the migrations.

• Add the AuthenticationServiceComponent to your Loopback4 Application (in application.ts).

  // import the AuthenticationServiceComponent
  import {AuthenticationServiceComponent} from '@sourceloop/authentication-service';
  // add Component for AuthenticationService
  this.component(AuthenticationServiceComponent);

• Set up a Loopback4 Datasource with dataSourceName property set to AuthDbSourceName. You can see an example datasource here.

• Set up a Loopback4 Datasource for caching tokens with dataSourceName property set to AuthCacheSourceName.

• Bind any of the custom providers you need.

• OTP -

  • Implement OtpSenderProvider(refer this) in your application and bind it to its respective key in application.ts

  import {
    VerifyBindings,
    AuthServiceBindings,
  } from '@sourceloop/authentication-service';
  this.bind(VerifyBindings.OTP_SENDER_PROVIDER).toProvider(OtpSenderProvider);
  this.bind(AuthServiceBindings.MfaConfig).to({
    secondFactor: STRATEGY.OTP,
  });
  this.bind(AuthServiceBindings.OtpConfig).to({
    method: OtpMethodType.OTP,
  });

  • This provider is responsible for sending OTP to user.
  • By default OTP is valid for 5 minutes. To change it, set OTP_STEP and OTP_WINDOW (refer otp-options) as per your need in .env.

• Google Authenticator -

  • To use google Authenticator in your application, add following to application.ts

  import {AuthServiceBindings} from '@sourceloop/authentication-service';
  this.bind(AuthServiceBindings.MfaConfig).to({
    secondFactor: STRATEGY.OTP,
  });
  this.bind(AuthServiceBindings.OtpConfig).to({
    method: OtpMethodType.GOOGLE_AUTHENTICATOR,
  });

• Set APP_NAME in .env.

• To authenticate using only OTP or Authenticator app, use the following APIs:

  • /send-otp
  • /auth/check-qr-code
  • /auth/create-qr-code
  • /verify-otp

• Two-Factor-Authentication -

  • As of now, 2nd Factor will always be either OTP or Google Authenticator.

  • Implement MfaProvider(refer this) in your application setting its value to true and bind it to its respective key in application.ts

    import {VerifyBindings} from '@sourceloop/authentication-service';
    this.bind(VerifyBindings.MFA_PROVIDER).toProvider(MfaProvider);

  • It works for almost all authentication methods provided by this service.

  • Use /verify-otp to enter otp or code from authenticator app. for using Google Authenticator user needs to pass client id in the payload which is optional in case for OTP

• OAuth- using Azure AD -

  • Passport strategy for authenticating via Azure Ad using passport-azure-ad. Make sure you have an account on Azure and have your application registered. Follow the steps here.

  • Refer the .env.example file to add all the relevant env variables for Azure Auth. Note - For boolean values that need to passed as false keep them blank. We are using cookie based approach instead of session based, so the library requires a cookie-parser middleware. To bind the middleware to you application set AZURE_AUTH_ENABLED=true in env file so the middleware will be added to the sequence. Also the verifier function uses Signup provider whose implementation needs to be added by the user. Bind the provider key to its corresponding value.

    this.providers[SignUpBindings.AZURE_AD_SIGN_UP_PROVIDER.key] =
      AzureAdSignupProvider;

    export class AzureAdSignupProvider implements Provider<AzureAdSignUpFn> {
      value(): AzureAdSignUpFn {
        // sonarignore:start
        return async profile => {
          // sonarignore:end
          throw new HttpErrors.NotImplemented(
            `AzureAdSignupProvider not implemented`,
          );
        };
      }
    }

    Also bind VerifyBindings.AZURE_AD_PRE_VERIFY_PROVIDER and VerifyBindings.AZURE_AD_POST_VERIFY_PROVIDER to override the basic implementation provided by default.

• Authorizing Public & Private Clients

  • In order to authorize public and private clients separately in your application, add the following to application.ts before binding AuthenticationComponent

    import { AuthenticationBindings, AuthenticationConfig} from 'loopback4-authentication';
    this.bind(AuthenticationBindings.CONFIG).to({
    secureClient: true,
    } as Authentication Config);

  • Authorizing Public & Private Clients-Migrations :

    add client_type column to auth_clients table with values public/private

    ALTER TABLE main.auth_clients
    ADD client_type varchar(100) DEFAULT 'public';

    For a more elaborate implementation , see /sandbox/auth-public-private-client.

• Authenticating JWT using RSA Encryption

  To generate the keys, we have exposed an endpoint through which both keys can be generated.

  Endpoint:- {AUTH_SERVICE_URL}/connect/generate-keys

  It will generate the “N” number of keys in the database, where N = process.env.MAX_JWT_KEYS. You need to set another env variable named "process.env.JWT_PRIVATE_KEY_PASSPHRASE", which will be used to encrypt/decrypt private key.

  By default we are employing asymmetric token signing and verification, but if symmetric signing and verification is required it has to be explicitly provided in the manner below

  this.bind(AuthServiceBindings.Config).to({
    useSymmetricEncryption: true,
  });

• Authenticating Password using RSA Encryption

  In order to authenticate password using RSA encrytion we need to provide private key through an env variable called PRIVATE_DECRYPTION_KEY. By employing RSA encryption and the private key through the environment variable, this approach enhances the security of password authentication, ensuring that passwords are transmitted and stored in an encrypted manner, and can only be deciphered using the designated private key.

  Its implemented through password decryption provider here which accepts password in encrypted format.It uses node-forge as default for decryption but can be overriden through this password decryption provider for using any other library.

  Note: When using .env file put your private key in single line with line breaks escaped with \n, one of the ways of doing so can be found here.

• JWT keys rotation

  After the generation, the following endpoint will be created to generate a new key, delete the oldest key, and add the new key to the DB. Endpoint:- {AUTH_SERVICE_URL}/connect/rotate-keys

  This api should be called after a configurable time. It can be a cron job or a background task which will call the api to rotate the keys.

  • It will generate a new pair of keys.
  • It will delete the oldest set of keys from the db.
  • It will add the newly generated keys to the db.

• Using with Sequelize

  This service supports Sequelize as the underlying ORM using @loopback/sequelize extension. And in order to use it, you'll need to do following changes.

  • To use Sequelize in your application, add following to application.ts:

  this.bind(AuthServiceBindings.Config).to({
    useCustomSequence: false,
    useSequelize: true,
  });

  • Use the SequelizeDataSource in your audit datasource as the parent class. Refer this for more details.

• Customizable Password Hashing for Enhanced Security

  For hashing and verifying of password two providers utilized are as follows:

  PasswordHashingProvider: This provider here generates a hash of a given password using bcrypt's hashing function.

  PasswordVerifyProvider: This provider here verifies whether a plain password matches a hashed password using bcrypt's comparison function

  These providers offer a flexible and modular approach to password hashing and verification within a LoopBack application. Users can easily swap out these implementations with their preferred hashing algorithms by overriding the providers, allowing for customization according to specific security requirements.

• Start the application npm start

Using sourceloop/authentication-service as Identity Server

Authenttication service can be used as a identity server. Following endpoints have been exposed for use:-

Endpoint	HTTP Type	Description
/connect/generate-keys	POST	It is generating private and public keys in the jwt-keys table. The number of keys generated will be defined by env variable name MAX_JWT_KEYS
/.well-known/openid-configuration	GET	The discovery endpoint can be used to retrieve metadata about IdentityServer - it returns information like the issuer name, key material, supported scopes, etc
/connect/get-keys	GET	This endpoint will return the public keys available in the database
/connect/rotate-keys	POST	this endpoint will help rotate the keys. It will delete the oldest key and generate a new one
/connect/userinfo	GET	The UserInfo endpoint can be used to retrieve identity information about a subject. It requires a valid access token with at least the ‘openid’ scope.
/connect/token	POST	The token endpoint can be used to programmatically request or refresh tokens (resource owner password credential flow, authorization code flow, client credentials flow, and custom grant types).
/connect/endsession	POST	Redirecting to the logout endpoint clears the authentication session and cookie.

Environment Variables

Name	Required	Description	Default Value
NODE_ENV	Y	Node environment value, i.e. `dev`, `test`, `prod
LOG_LEVEL	Y	Log level value, i.e. `error`, `warn`, `info`, `verbose`, `debug`
DB_HOST	Y	Hostname for the database server.
DB_PORT	Y	Port for the database server.
DB_USER	Y	User for the database.
DB_PASSWORD	Y	Password for the database user.
DB_DATABASE	Y	Database to connect to on the database server.
DB_SCHEMA	Y	Database schema used for the data source. In PostgreSQL, this will be `public` unless a schema is made explicitly for the service.
REDIS_HOST	Y	Hostname of the Redis server.
REDIS_PORT	Y	Port to connect to the Redis server over.
REDIS_URL	Y	Fully composed URL for Redis connection. Used instead of other settings if set.
REDIS_PASSWORD	Y	Password for Redis if authentication is enabled.
REDIS_DATABASE	Y	Database within Redis to connect to.
JWT_SECRET	Y	Symmetric signing key of the JWT token.
JWT_ISSUER	Y	Issuer of the JWT token.
JWT_PRIVATE_KEY_PASSPHRASE	Y	Passphrase to encrypt/decrypt private key
MAX_JWT_KEYS	Y	Maximum number of jwt keys generated in the database
USER_TEMP_PASSWORD	N	Temporary password that can be used during development.
GOOGLE_AUTH_URL	N	Google OAuth2.0 authorization URL if authentication strategy is set to Google
GOOGLE_AUTH_CLIENT_ID	N	Google client ID for the service
GOOGLE_AUTH_CLIENT_SECRET	N	Google client secret for the service
GOOGLE_AUTH_TOKEN_URL	N	Google OAuth2.0 authorization URL if authentication strategy is set to Google
GOOGLE_AUTH_CALLBACK_URL	N	Google callback URL for the client configuration in Google
FORGOT_PASSWORD_LINK_EXPIRY	N	Expiration period of temporary password in seconds. 1800 seconds (30minutes) is the default.	1800
KEYCLOAK_HOST	N	Hostname of the Keycloak instance. For all keycloak version below 17, user can still use this by only updating the KEYCLOCK_HOST and appending '/auth/realms' to its existing value
KEYCLOAK_REALM	N	Realm (tenant) in Keycloak
KEYCLOAK_CLIENT_ID	N	Keycloak client ID for the service
KEYCLOAK_CLIENT_SECRET	N	Keycloak client secret for the service
KEYCLOAK_CALLBACK_URL	N	Keycloak callback URL for the client configuration in Google
HTTPS_PROXY	N	Https proxy url for keycloak auth

Setting up a DataSource

Here is a sample Implementation DataSource implementation using environment variables and PostgreSQL as the data source. The auth-multitenant-example utilizes both Redis and PostgreSQL as data sources.

import {inject, lifeCycleObserver, LifeCycleObserver} from '@loopback/core';
import {juggler} from '@loopback/repository';
import {AuthDbSourceName} from '@sourceloop/authentication-service';

const config = {
  name: AuthDbSourceName,
  connector: 'postgresql',
  url: '',
  host: process.env.DB_HOST,
  port: process.env.DB_PORT,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_DATABASE,
  schema: process.env.DB_SCHEMA,
};

@lifeCycleObserver('datasource')
export class AuthenticationDbDataSource
  extends juggler.DataSource
  implements LifeCycleObserver
{
  static dataSourceName = AuthDbSourceName;
  static readonly defaultConfig = config;

  constructor(
    // You need to set datasource configuration name as 'datasources.config.Authentication' otherwise you might get Errors
    @inject('datasources.config.authentication', {optional: true})
    dsConfig: object = config,
  ) {
    super(dsConfig);
  }
}

Migrations

The migrations required for this service are processed during the installation automatically if you set the AUTH_MIGRATION or SOURCELOOP_MIGRATION env variable. The migrations use db-migrate with db-migrate-pg driver for migrations, so you will have to install these packages to use auto-migration. Please note that if you are using some pre-existing migrations or databases, they may be affected. In such a scenario, it is advised that you copy the migration files in your project root, using the AUTH_MIGRATION_COPY or SOURCELOOP_MIGRATION_COPY env variables. You can customize or cherry-pick the migrations in the copied files according to your specific requirements and then apply them to the DB.

This migration script supports both MySQL and PostgreSQL databases, controlled by environment variables. By setting MYSQL_MIGRATION to 'true', the script runs migrations using MySQL configuration files; otherwise, it defaults to PostgreSQL. .

Additionally, there is now an option to choose between SQL migration or PostgreSQL migration. NOTE : For @sourceloop/cli users, this choice can be specified during the scaffolding process by selecting the "type of datasource" option.

Database Schema

Providers

You can find documentation for some of the providers available in this service here

ATTENTION

We would like to inform you that we have deprecated '/auth/login-token' due to security vulnerabilities. Your immediate action is required to transition away from its usage. We encourage you to transition to OAuth-compliant APIs such as '/auth/login' and '/auth/token' for secure authentication and data exchange. Refer to our documentation and reach out for support if needed. Your cooperation is appreciated in safeguarding our systems integrity.

Common Headers

Authorization: Bearer where is a JWT token signed using JWT issuer and secret. Content-Type: application/json in the response and in request if the API method is NOT GET

Common Request path Parameters

{version}: Defines the API Version

Common Responses

200: Successful Response. Response body varies w.r.t API 401: Unauthorized: The JWT token is missing or invalid 403: Forbidden : Not allowed to execute the concerned API 404: Entity Not Found 400: Bad Request (Error message varies w.r.t API) 201: No content: Empty Response

API Details

Visit the OpenAPI spec docs

License

Sourceloop is MIT licensed.