Rockets NestJS Federated Authentication

Authenticate via federated login

Project

Table of Contents

1. Tutorials
   • Introduction
   • Getting Started with Federated Authentication
     • Step 1: Create User Entity
     • Step 2: Create Federated Entity
     • Step 3: Implement FederatedUserModelServiceInterface
     • Step 4: Configure the Module
     • Step 5: Integrate with other Oauth Module
2. How-To Guides
   • Implement FederatedUserModelServiceInterface
   • Using federated with Rockets Github Module
3. Reference
4. Explanation
   • Federated Services
   • Module Options Responsibilities

Tutorials

Introduction

Before we begin, you'll need to set up OAuth Apps for the social providers you wish to use (e.g., GitHub, Google, Facebook) to obtain the necessary credentials. For detailed guides on creating OAuth Apps and obtaining your Client IDs and Client Secrets, please refer to the official documentation of each provider and refer to the @concepta/nestjs-auth-github, nestjs-auth-apple, and @concepta/nestjs-auth-google documentation to use our modules.

Getting Started with Federated Authentication

Installation

To get started, install the FederatedModule package:

yarn add @concepta/nestjs-federated

Step 1: Create User Entity

First, let's create the UserEntity:

import { Entity, PrimaryGeneratedColumn, Column, OneToMany } from 'typeorm';
import { FederatedEntity } from '../federated/federated.entity';

@Entity()
export class UserEntity {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column()
  name: string;

  @OneToMany(() => FederatedEntity, (federated) => federated.user)
  federated!: FederatedEntity;
}

Step 2: Create Federated Entity

Next, create the FederatedEntity:

import { Entity, ManyToOne } from 'typeorm';
import { FederatedSqliteEntity } from '@concepta/nestjs-typeorm-ext';
import { UserEntity } from '../user/user.entity';

@Entity()
export class FederatedEntity extends FederatedSqliteEntity {
  @ManyToOne(() => UserEntity, (user) => user.federated)
  user!: UserEntity;
}

Step 3: Implement FederatedUserModelServiceInterface

Refer to Implement FederatedUserModelServiceInterface section

Step 4: Configure the Module

Finally, set up the module configuration:

import { AuthenticationModule } from '@concepta/nestjs-authentication';
import { FederatedModule } from '@concepta/nestjs-federated';
import { JwtModule } from '@concepta/nestjs-jwt';
import { Module } from '@nestjs/common';
import { FederatedUserModelService } from './federated/federated-model.service';
import { FederatedEntity } from './federated/federated.entity';
import { AuthGithubModule } from '@concepta/nestjs-auth-github';
import { TypeOrmExtModule } from '@concepta/nestjs-typeorm-ext';
import { UserEntity } from './user/user.entity';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
    }),
    TypeOrmExtModule.forRoot({
      type: 'sqlite',
      database: ':memory:',
      entities: [UserEntity, FederatedEntity],
    }),
    JwtModule.forRoot({}),
    AuthenticationModule.forRoot({}),
    TypeOrmExtModule.forFeature({
      federated: {
        entity: FederatedEntity,
      },
    }),
    FederatedModule.forRoot({
      userModelService: new FederatedUserModelService(),
    }),
  ],
  controllers: [],
  providers: [],
})
export class AppModule {}

This configuration uses SQLite for testing, but you can use any database supported by TypeORM.

Step 5: Integrate with other Oauth Module

To complete the integration with OAuth providers and set up the whole authentication flow, you'll need to implement one of the @concepta social authentication modules. Follow the documentation for the specific module you want to use:

1. GitHub Authentication: Refer to the @concepta/nestjs-auth-github documentation for detailed instructions on setting up GitHub OAuth authentication.

2. Apple Authentication: For Apple Sign-In, follow the nestjs-auth-apple documentation to implement Apple's OAuth flow.

3. Google Authentication: To set up Google OAuth, consult the @concepta/nestjs-auth-google documentation for step-by-step guidance.

These documentation resources will guide you through:

• Obtaining the necessary OAuth credentials from the respective providers
• Configuring the OAuth module in your NestJS application
• Setting up the required controllers and routes
• Implementing the authentication flow

By following these provider-specific guides, you'll be able to complete the federated authentication setup and enable users to log in using their preferred social accounts.

How-To Guides

Implement FederatedUserModelServiceInterface

Create a service that implements FederatedUserModelServiceInterface:

// user.mock.ts
export const mockUser = {
  id: 'abc',
  email: '[email protected]',
  username: '[email protected]',
}

// user-model.service.ts
import { Injectable } from '@nestjs/common';
import { ReferenceEmail } from '@concepta/nestjs-common';
import {
  FederatedUserModelServiceInterface 
  FederatedCredentialsInterface,
} from '@concepta/nestjs-federated';
import { mockUser } from './user.mock';


@Injectable()
export class UserModelServiceFixture
  implements FederatedUserModelServiceInterface
{
  async byId(
    id: string
  ): ReturnType<FederatedUserModelServiceInterface['byId']> {
    if (id === mockUser.id) {
      return mockUser;
    } else {
      throw new Error();
    }
  }

  async byEmail(
    email: ReferenceEmail
  ): Promise<UserInterface | null> {
    return email === mockUser.email ? mockUser : null;
  }

  async create(
    _object: ReferenceEmailInterface & ReferenceUsernameInterface
  ): Promise<FederatedCredentialsInterface> {
    return mockUser;
  }
}

Using federated with Rockets Github Module

For detailed instructions on using the federated module with the Rockets GitHub module, please refer to the @concepta/nestjs-auth-github documentation.

Reference

For detailed information on the properties, methods, and classes used in the @concepta/nestjs-federated, please refer to the API documentation available at FederatedModule API Documentation. This documentation provides comprehensive details on the interfaces and services that you can utilize to customize and extend the authentication functionality within your NestJS application.

Explanation

Federated Services

1. User Creation and Association: The federated service then takes over:
   • It checks if a user associated with the provider (e.g., GitHub, Google, Facebook) account already exists.
   • If the user doesn't exist, it creates a new user account.
   • It associates the provider with the user account, creating a link between the user's application account and their provider identity.

Module Options Responsibilities

The FederatedOptionsInterface defines the configuration options for the federated module. Here are the responsibilities of each option:

• userModelService: This is an implementation of the FederatedUserModelServiceInterface. It is responsible for looking up users based on various criteria such as user ID or email. This service ensures that the application can retrieve user information from the database or any other storage mechanism.

By configuring these options, you can customize the behavior of the federated module to suit your application's requirements, ensuring seamless integration with multiple social authentication providers.