NestJS Easy Auth

Elegant and simple authentication solution for NestJS.

@Module({
  imports: [
    AuthModule.withConfiguration({
      jwtConfig: {
        secret: 'my-secret',
        accessTokenExpiresIn: '1h',
        refreshTokenExpiresIn: '1d',
        tokenExtraction: ExtractJwt.fromAuthHeaderAsBearerToken(),
        ignoreExpiration: false
      },
      modelProvider: DefaultModelProvider.withModels({
        credentials: CredentialsMock,
        user: UserMock
      }),
      methods: [SignInEmailPassword.forRoot(), LogInEmailPassword.forRoot()]
    })
  ]
})
export class ApiModule {}

Table of Contents

• Installation
• Quick start
  1. Provide your database
  2. Provide your jwt configuration
  3. Provide your models
  4. Provide your authentication methods
• Documentation
  • Introduction
  • Authentication methods
    • Sign in with email and password
    • Login with email and password
  • Creating your own authentication method

Installation

You can install the package using the following commands:

$ yarn
yarn add nestjs-easy-auth

$ npm
npm install nestjs-easy-auth

Quick start

1. Provide your database

This package allows you to use your own database for the credentials and user storage. You can create your own CredentialsStorage and UserStorage.

You can use MongoDB as the main storage. Thi, you can install nestjs-easy-auth-mongo which provides a MongoDB implementation. To get started, import the AuthMongoProviderModule in your ApiModule.

$ yarn
yarn add nestjs-easy-auth-mongo

$ npm
npm install nestjs-easy-auth-mongo

@Module({
  imports: [
    AuthMongoProviderModule.withConfiguration({
      dbName: 'your-database-name',
      uri: 'mongodb://user:[email protected]:27017',
      schemas: {
        credentials: DBCredentialsSchema,
        user: DBUserSchema
      }
    })
  ]
})
export class ApiModule {}

2. Provide your jwt configuration

Provide your jwt configuration using the jwtConfig property.

AuthModule.withConfiguration({
  jwtConfig: {
    secret: 'my-secret',
    accessTokenExpiresIn: '1h',
    refreshTokenExpiresIn: '1d',
    tokenExtraction: ExtractJwt.fromAuthHeaderAsBearerToken(),
    ignoreExpiration: false
  }
});

3. Provide your models

This package allows you to use your own Credentials and User models. Your models needs to conforms to the CredentialsRepresentation and UserRepresentation interfaces.

export class Credentials implements CredentialsRepresentation<DBCredentials, PublicCredentials> {
  public constructor(
    public readonly userId: string,
    public readonly authType: string,
    public readonly accessToken: string,
    public readonly refreshToken: string,
    public readonly accessTokenExpiration: Date,
    public readonly refreshTokenExpiration: Date
  ) {}

  // Required to convert the model to a database model.
  public toDatabaseModel(): DBCredentials {
    return new DBCredentials(
      this.userId,
      this.authType,
      this.accessToken,
      this.refreshToken,
      this.accessTokenExpiration,
      this.refreshTokenExpiration
    );
  }

  // Required to convert the model to a public model.
  public toPublicModel(): PublicCredentials {
    return new PublicCredentials(
      this.userId,
      this.authType,
      this.accessToken,
      this.refreshToken,
      this.accessTokenExpiration,
      this.refreshTokenExpiration
    );
  }
}

export class User implements UserRepresentation<DBUser, PublicUser> {
  public constructor(
    public readonly id: string,
    public readonly email: string,
    public readonly hashedPassword?: string
  ) {}

  // Required to convert the model to a database model.
  public toDatabaseModel(): DBUser {
    return new DBUser(this.id, this.email, this.hashedPassword);
  }

  // Required to convert the model to a public model.
  // Do not include the hashed password in the public model.
  public toPublicModel(): PublicUser {
    return new PublicUser(this.id, this.email);
  }
}

You can provide your models using the DefaultModelProvider class.

AuthModule.withConfiguration({
  jwtConfig: { ... },
  modelProvider: DefaultModelProvider.withModels({
    credentials: CredentialsMock,
    user: UserMock
  })
});

4. Provide your authentication methods

You can provide your authentication methods using the methods property. These methods will be used to authenticate your users.

AuthModule.withConfiguration({
  jwtConfig: { ... },
  modelProvider: DefaultModelProvider.withModels({ ... }),
  methods: [SignInEmailPassword.forRoot(), LogInEmailPassword.forRoot()]
});

With theses methods, you can create and authentify users using their email and password with the following HTTP requests:

POST /auth/sign-in
{
  "email": "[email protected]",
  "password": "my-password"
}

POST /auth/login
{
  "email": "[email protected]",
  "password": "my-password"
}

You can also refresh you credentials using the POST /auth/refresh endpoint.

POST /auth/refresh
{
  "refresh_token": "your-refresh-token"
}

Documentation

Authentication methods

SignInEmailPassword

Inputs

| Property | Example | | ------------ | --------------------- | | email | [email protected] | | password | yourpassword |

Options

| Option | Default value | | ------------ | -------------------------------- | | hashPassword | SignInEmailPassword.brcyptHash |

LoginEmailPassword

Inputs

| Property | Example | | ------------ | --------------------- | | email | [email protected] | | password | yourpassword |

Options

| Option | Default value | | --------------- | --------------------------------------------- | | comparePassword | LoginEmailPassword.bcryptPasswordComparison |