Build a Node.js gRPC Server and Client: Register and Login User 2024

This article will teach you how to create a Node.js gRPC server and client to authenticate a user with JSON Web Tokens using TypeScript, Node.js, PostgreSQL, Redis, Prisma, and Docker-compose.

Build gRPC API with Node.js and Prisma Series:

Build a Node.js gRPC Server and Client Register and Login User

What the course will cover

How to create a gRPC API server method to register and login a user
How to create a gRPC API server method to authenticate users with access and refresh tokens.
How to build a gRPC client to interact with the gRPC API server
How to build a gRPC API server to get the authenticated user’s credentials

Prerequisites

Before you begin this tutorial:

Software

Basic knowledge of Node.js and PostgreSQL will be helpful
An intermediate understanding of Prisma, and how to use ORMs and pgAdmin will be highly beneficial.
Have Docker and Node.js installed

VS Code Extensions

DotENV – Get syntax highlighting for any environment variables file having .env extension.
Proto3 – To get syntax highlighting, syntax validation, line and block comments, compilation, code snippets, code completion, and code formatting for all files ending with .proto extension.
MySQL – A database client for VS Code. This extension will enable us to view the data stored in the database.

The VS Code Proto3 extension uses the Protocol buffer compiler under the hood so you need to install the Protoc compiler for it to function properly.

You can visit the official gRPC website to install the Protocol buffer compiler needed for your operating system.

By default, the protocol buffer compiler looks for the proto files in the root directory and we need to manually tell it the location of the proto files.

To do that, open the settings page in VS Code and search for Proto3. Next, click on the Edit in settings.json link and add this option to the Protoc configuration.


{
   "options": ["--proto_path=proto"]
}

Setting up PostgreSQL and Redis Servers

PostgreSQL originally named POSTGRES is a powerful, free, and open-source relational database management system developed at the University of California, Berkeley.

Usually, we install the PostgreSQL server from the official Postgres website, however, we are going to use Docker to run the PostgreSQL server on our machine. This will give us the ability to easily run and maintain it in a development environment.

Since we want to run the Redis and PostgreSQL Docker containers simultaneously, we will be using a docker-compose.yml file to easily configure and run them.

First and foremost, let’s create a project folder named node-grpc-prisma and open it with an IDE or text editor.

$ mkdir node-grpc-prisma

In the project root directory, create a docker-compose.yml file and add the following code to configure the Redis and PostgreSQL images.

docker-compose.yml


version: '3'
services:
  postgres:
    image: postgres
    container_name: postgres
    ports:
      - '6500:5432'
    restart: always
    env_file:
      - ./.env
    volumes:
      - postgres-db:/var/lib/postgresql/data
  redis:
    image: redis:latest
    container_name: redis
    ports:
      - '6379:6379'
    volumes:
      - redis:/data
volumes:
  postgres-db:
  redis:

The Postgres Docker image requires some credentials to set up the PostgreSQL server so add the following environment variables:

.env


DATABASE_PORT=6500
POSTGRES_PASSWORD=password123
POSTGRES_USER=postgres
POSTGRES_DB=grpc-node-prisma
POSTGRES_HOST=postgres
POSTGRES_HOSTNAME=127.0.0.1

.gitignore


node_modules
.env

Now run the Redis and PostgreSQL containers with this command:

docker-compose up -d

You can stop the containers with this command:

docker-compose down

Creating the gRPC Protocol Buffer Messages

Before we can start using gRPC, we need to create the Protocol Buffer files to list the RPC services and methods using the protocol buffer language.

One best practice is to keep all the Protocol buffer files in a single folder to make your project cleaner and enable you to easily generate the gRPC server and client stubs or interfaces.

Now create a proto folder in the root directory. This folder will contain all the Protocol buffer files.

Define the gRPC User Protocol Buffer Message

To define a protocol buffer message, we specify the version of the protocol buffer language at the beginning of the proto file, in our example the Protobuf language is proto3.

Next, we specify the package name using the package keyword provided by the proto3 language.

Benefits of using Protobuf packages

Grouping the Protobuf messages under packages will help us:

Avoid naming conflicts in the Protobuf message objects
For easy portability. This ensures that the generated TypeScript interfaces and type aliases are also grouped in folders.
To load the Protobuf files in Node.js based on the packages they belong to.

Now to define the field (name/value pairs) of a protocol buffer message, we specify the field type followed by the field name and a unique identifier that will be used by the gRPC framework to easily identify the fields in the message binary format.

The field numbers that range from 1 to 15 take one byte to encode, whereas numbers in the range 16 through 2047 take two bytes to encode.

You can learn more about how to fields are encoded from the Protocol Buffer Encoding website.

Now let’s create a reusable Protobuf message that we can use in other Protobuf messages:

proto/user.proto


syntax = "proto3";

package auth;

import "google/protobuf/timestamp.proto";

message User {
  string id = 1;
  string name = 2;
  string email = 3;
  string role = 4;
  string photo = 5;
  string provider = 6;
  google.protobuf.Timestamp created_at = 7;
  google.protobuf.Timestamp updated_at = 8;
}

message UserResponse { User user = 1; }

message GenericResponse {
  string status = 1;
  string message = 2;
}

Quite a lot going on in the above, let’s break it down:

We created a User Protobuf message to contain the fields a user object should have.

Google has a standard library of popular data types including the Timestamp type which was not included in the built-in types of Protobuf.

So we imported the google.protobuf.Timestamp data type from the Google standard library and assigned it to the created_at and updated_at fields.

Define the gRPC Protocol Buffer Message to SignUp User

proto/rpc_signup_user.proto


syntax = "proto3";

package auth;

import "user.proto";

message SignUpUserInput {
  string name = 1;
  string email = 2;
  string password = 3;
  string passwordConfirm = 4;
  string photo = 5;
  string provider = 6;
}

message SignUpUserResponse { User user = 1; }

Define the gRPC Protocol Buffer Message to Login User

proto/rpc_signin_user.proto


syntax = "proto3";

package auth;

message SignInUserInput {
  string email = 1;
  string password = 2;
}

message SignInUserResponse {
  string status = 1;
  string access_token = 2;
  string refresh_token = 3;
}

Creating the RPC Services and Methods

Now that we have the RPC messages already defined, let’s create the gRPC service and add the RPC definitions.

Create a proto/services.proto file to contain all the gRPC services and other Protobuf messages.

proto/services.proto


syntax = "proto3";

package auth;

import "user.proto";
import "rpc_signup_user.proto";
import "rpc_signin_user.proto";

service AuthService {
  rpc SignUpUser(SignUpUserInput) returns (SignUpUserResponse) {}
  rpc SignInUser(SignInUserInput) returns (SignInUserResponse) {}
  rpc RefreshToken(RefreshTokenInput) returns (RefreshTokenResponse) {}
  rpc GetMe(GetMeInput) returns (UserResponse) {}
}

message GetMeInput { string access_token = 1; }
message RefreshTokenInput { string refresh_token = 1; }
message RefreshTokenResponse {
  string access_token = 1;
  string refresh_token = 2;
}

In the above code, we created an AuthService having the following RPC methods:

SignUpUser – To register a new user
SignInUser – To login the registered user
RefreshToken – To refresh the expired access token
GetMe – To retrieve the currently authenticated user’s credentials.

Later, we will twerk the SignUpUser RPC method to send a verification code to the email address provided by the user.

This authentication step is required to ensure that only users with valid email addresses can log into our gRPC application.

Generating the gRPC Client and Server TypeScript Files

To begin, let’s initialize a new Node.js TypeScript project with this command:


yarn init -y && yarn add -D typescript && npx tsc --init

Replace the content of the “tsconfig.json” file with the following. This step is only needed when you are using Typegoose with MongoDB.

tsconfig.json


{
  "compilerOptions": {
    "target": "es2018",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "module": "commonjs",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "strictPropertyInitialization": false,
    "skipLibCheck": true
  }
}

Now let’s add the dependencies needed to generate TypeScript files from the Protobuf definitions.


yarn add @grpc/grpc-js @grpc/proto-loader

@grpc/grpc-js – A feature-rich implementation of gRPC for Nodejs.
@grpc/proto-loader – This library contains utility functions for loading .proto files for use with gRPC.

Create a proto-gen.sh file and add this script to help us generate the TypeScript file from the Protobuf files.

proto-gen.sh


#!/bin/bash

rm -rf pb/
yarn proto-loader-gen-types --longs=String --enums=String --defaults --keepCase --oneofs --grpcLib=@grpc/grpc-js --outDir=pb/ proto/*.proto

Alternatively, you can copy the individual commands and run them directly in the terminal.

When the proto-gen.sh script is executed, the @grpc/proto-loader package will generate the TypeScript files from the proto files and put the resulting generated files in a pb folder.

You can open the pb folder to see the generated TypeScript files.

Generate the JWT Private and Public Keys

There are numerous ways we can generate the JSON Web Token private and public keys, however, we are going to use a Private and Public Keys Generation Site.

This website will enable us to generate the keys with just a click of a button. I already added the base64 encoded private and public keys to the .env file but you can follow these steps to generate them yourself.

Step 1: Navigate to the Private and Public Keys Generation Site, and click the “Generate New Keys” button to generate the keys.

Step 2: Copy the generated private key and navigate to the Base64 Encoding website to convert it to Base64.

Step 3: Copy the base64 encoded key and add it to the .env file as ACCESS_TOKEN_PRIVATE_KEY .

Step 4: Navigate back to the Private and Public Keys Generation Site and copy the corresponding public key.

Step 5: Navigate back to the Base64 Encoding website to encode the public key in base64 and add it to the .env file as ACCESS_TOKEN_PUBLIC_KEY.

Step 6: Repeat the above steps for the refresh token private and public keys.

In the end, the .env should look like this:

.env


DATABASE_PORT=6500
POSTGRES_PASSWORD=password123
POSTGRES_USER=postgres
POSTGRES_DB=grpc-node-prisma
POSTGRES_HOST=postgres
POSTGRES_HOSTNAME=127.0.0.1

DATABASE_URL="postgresql://postgres:password123@localhost:6500/grpc-node-prisma?schema=public"

ACCESS_TOKEN_PRIVATE_KEY=LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlCT1FJQkFBSkFVTWhaQjNucFJ6OEdrc0tneVZJcEZHMkJqZldHdElMWGNLUVFGMHZGbVZvOVVFcDhyOEVmCnI5T204azVTaXgrSi8rbXc0d08xVUlGb25rQTJFWnl6THdJREFRQUJBa0FDcVViOWp3K1hVRVU0S244L2dweGwKMXVHd3VvandnMnJ6aEFRZnNGaFhIKzlyQ1NWTmxNaEk0UWh4bWt3bHI2Y0NhUnFMUGg0Vk5lN3hKRDloWU5XcApBaUVBbXJ4TENiQXJJWDIvYkFETU1JdXljWFZKMnAwUk91S3FQOVBVeTB6ZG0zc0NJUUNGcGs5VDJKQ3NUVEhWCjErMWFVbk9JOFE3eUdNK1VQVGt6a200emNHcE8zUUloQUloOEU3Z2M4ejVjVzQ5WmVNSk5SbjI3VmdTRnpKL2oKTlFhTnc4SDdML0duQWlCTS9lUFJEMzg0WXpnRVV1SGZHSVNLTFNSSS8xWUZ0Y2RRR0ZqM3RSam8yUUlnS2t6ZwpVWFkwWjJRR1dqblFTdzdJRThaSDZuTHcydFUrci9LR0NZRzVKN3M9Ci0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0t
ACCESS_TOKEN_PUBLIC_KEY=LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZzd0RRWUpLb1pJaHZjTkFRRUJCUUFEU2dBd1J3SkFVTWhaQjNucFJ6OEdrc0tneVZJcEZHMkJqZldHdElMWApjS1FRRjB2Rm1WbzlVRXA4cjhFZnI5T204azVTaXgrSi8rbXc0d08xVUlGb25rQTJFWnl6THdJREFRQUIKLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0t

REFRESH_TOKEN_PRIVATE_KEY=LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlCT1FJQkFBSkFZOHRTUEZXMTk3bWgwcitCWUdLVTA4OFRPcDkrT2FObVNWQ1lMMTFhb05ZeEY1TSs1d0NSCnNDTnAxVEdHNW5zb215NW9QRitLajFsOGhjbmtUSUU2SndJREFRQUJBa0FVN2dLc1ZzbVlVQjJKWnRMS2xVSmoKZmUycGdPUG5VTWJXSDRvYmZQZlIvWGNteTdONkQyVXVQcnJ0MkdQVUpnNVJ4SG5NbVFpaDJkNHUwY3pqRDhpcApBaUVBcDFNaUtvY1BEWDJDU0lGN3c5SzVGWHlqMjIzQXJQcVJoUzNtL1dkVzVlVUNJUUNZcmxyeXRJOFkvODIzCkQ1ZTFHVExnbDlTcXN1UWdvaGF4ZCtKaXludGZHd0lnQ2xlK0xlakpTbWt1cTNLdGhzNDR1SlpLdnA2TElXWWYKcHA3T3YyMHExdTBDSVFDSy9lYWpuZ1hLLzB3NXcwTWJSUVpRK1VkTDRqRFZHRm5LVTFYUEUzOStVd0lnSEdLWgpjcDd2K3VyeG5kU05GK25MVEpZRG9abkMrKytteXRMaCtSUmU4dVU9Ci0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0t
REFRESH_TOKEN_PUBLIC_KEY=LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZzd0RRWUpLb1pJaHZjTkFRRUJCUUFEU2dBd1J3SkFZOHRTUEZXMTk3bWgwcitCWUdLVTA4OFRPcDkrT2FObQpTVkNZTDExYW9OWXhGNU0rNXdDUnNDTnAxVEdHNW5zb215NW9QRitLajFsOGhjbmtUSUU2SndJREFRQUIKLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0t

Next, let’s create a server/config/default.ts file to load the environment variables. Also, this file will contain the TypeScript types of the environment variables.


yarn add dotenv

server/config/default.ts


import path from 'path';
require('dotenv').config({ path: path.join(__dirname, '../../.env') });

const customConfig: {
  port: number;
  accessTokenExpiresIn: number;
  refreshTokenExpiresIn: number;
  dbUri: string;
  accessTokenPrivateKey: string;
  accessTokenPublicKey: string;
  refreshTokenPrivateKey: string;
  refreshTokenPublicKey: string;
  redisCacheExpiresIn: number;
} = {
  port: 8000,
  accessTokenExpiresIn: 15,
  refreshTokenExpiresIn: 60,
  redisCacheExpiresIn: 60,

  dbUri: process.env.DATABASE_URL as string,
  accessTokenPrivateKey: process.env.ACCESS_TOKEN_PRIVATE_KEY as string,
  accessTokenPublicKey: process.env.ACCESS_TOKEN_PUBLIC_KEY as string,
  refreshTokenPrivateKey: process.env.REFRESH_TOKEN_PRIVATE_KEY as string,
  refreshTokenPublicKey: process.env.REFRESH_TOKEN_PUBLIC_KEY as string,
};

export default customConfig;

Utility Function to Sign and Verify JWTs

With that out of the way, let’s create a server/utils/jwt.ts file and add these two utility functions to sign and verify the JWTs.


yarn add jsonwebtoken && yarn add -D @types/jsonwebtoken

Function to Sign the Access and Refresh Tokens

server/utils/jwt.ts


import jwt, { SignOptions } from 'jsonwebtoken';
import customConfig from '../config/default';

export const signJwt = (
  payload: Object,
  key: 'accessTokenPrivateKey' | 'refreshTokenPrivateKey',
  options: SignOptions = {}
) => {
  const privateKey = Buffer.from(customConfig[key], 'base64').toString('ascii');
  return jwt.sign(payload, privateKey, {
    ...(options && options),
    algorithm: 'RS256',
  });
};

Function to Verify the JWT Tokens

server/utils/jwt.ts


export const verifyJwt = <T>(
  token: string,
  key: 'accessTokenPublicKey' | 'refreshTokenPublicKey'
): T | null => {
  try {
    const publicKey = Buffer.from(customConfig[key], 'base64').toString(
      'ascii'
    );
    return jwt.verify(token, publicKey) as T;
  } catch (error) {
    console.log(error);
    return null;
  }
};

Defining the Database Models with Prisma

At the time of writing this article, Prisma supports databases like:

PostgreSQL
MySQL
SQLite
SQL Server
MongoDB
CockroachDB

In the nutshell, you can easily adapt the code in this tutorial to work with any of the Prisma-supported databases.

Install the following dependencies:


yarn add -D prisma && yarn add @prisma/client

Prisma provides an init command that we can use to initialize the Prisma project. By default the init command uses the PostgreSQL database, however, you can pass a --datasource-provider flag to change the database type.


npx prisma init --datasource-provider postgresql

The above command will create a server/prisma folder having a schema.prisma file.

The server/prisma/schema.prisma file will contain the settings to connect to the database and the models required to generate the SQL tables.

Now let’s create a User model in the server/prisma/schema.prisma file:


generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}


model User{
  @@map(name: "users")

  id String  @id @default(uuid())
  name String  @db.VarChar(255)
  email String @unique
  photo String? @default("default.png")
  verified Boolean? @default(false) 
  
  password String
  role RoleEnumType? @default(user)

  created_at DateTime @default(now())
  updated_at DateTime @updatedAt

  provider String?
}

enum RoleEnumType {
  user
  admin
}

Database Migration with Prisma

Before you can run the Prisma migration command, you need to make sure the PostgreSQL Docker container is running.

Now add these scripts to the package.json file:


{
"scripts": {
        "db:migrate": "npx prisma migrate dev --name user-entity --create-only --schema ./server/prisma/schema.prisma && yarn prisma generate --schema ./server/prisma/schema.prisma",
    "db:push": "npx prisma db push --schema ./server/prisma/schema.prisma"
  },
}

--name – this flag specifies the migration name.
--schema – this flag specifies the path to the schema.prisma file.
--create-only – this command tells Prisma to only create the migration file without applying it.
db:migrate – this script will execute the Prisma migrate and generate commands.
The migrate command will create a new migration file, whereas the generate command generates the TypeScript types based on the models defined in the schema.prisma file.
db:push – this script will run the Prisma db command to push the changes to the database and keep the database in sync with the Prisma schema.

If you are comfortable with pgAdmin, you can sign in with the database credentials we specified in the .env file to see the SQL table added by Prisma.

checking the prisma model attributes in postgresql using pgadmin

Connecting to the PostgreSQL and Redis Servers

Connecting to the PostgreSQL Docker Container

server/utils/prisma.ts


import { PrismaClient } from '@prisma/client';

declare global {
  var prisma: PrismaClient | undefined;
}

export const prisma = global.prisma || new PrismaClient();

if (process.env.NODE_ENV !== 'production') {
  global.prisma = prisma;
}

async function connectDB() {
  try {
    await prisma.$connect();
    console.log('? Database connected successfully');
  } catch (error) {
    console.log(error);
    process.exit(1);
  } finally {
    await prisma.$disconnect();
  }
}

export default connectDB;

Connecting to the Redis Docker Container


yarn add redis

server/utils/connectRedis.ts


import { createClient } from 'redis';

const redisUrl = `redis://localhost:6379`;
const redisClient = createClient({
  url: redisUrl,
});

const connectRedis = async () => {
  try {
    await redisClient.connect();
    console.log('? Redis client connected...');
    redisClient.set(
      'tRPC',
      '??Welcome to tRPC with React.js, Express and Typescript!'
    );
  } catch (err: any) {
    console.log(err.message);
    process.exit(1);
  }
};

connectRedis();

redisClient.on('error', (err) => console.log(err));

export default redisClient;

Creating the Prisma Services

server/services/user.service.ts


import { Prisma, User } from '@prisma/client';
import customConfig from '../config/default';
import redisClient from '../utils/connectRedis';
import { signJwt } from '../utils/jwt';
import { prisma } from '../utils/prisma';

export const createUser = async (input: Prisma.UserCreateInput) => {
  return (await prisma.user.create({
    data: input,
  })) as User;
};

export const findUser = async (
  where: Partial<Prisma.UserCreateInput>,
  select?: Prisma.UserSelect
) => {
  return (await prisma.user.findFirst({
    where,
    select,
  })) as User;
};

export const findUniqueUser = async (
  where: Prisma.UserWhereUniqueInput,
  select?: Prisma.UserSelect
) => {
  return (await prisma.user.findUnique({
    where,
    select,
  })) as User;
};

export const updateUser = async (
  where: Partial<Prisma.UserWhereUniqueInput>,
  data: Prisma.UserUpdateInput,
  select?: Prisma.UserSelect
) => {
  return (await prisma.user.update({ where, data, select })) as User;
};

export const signTokens = async (user: Prisma.UserCreateInput) => {
  // 1. Create Session
  redisClient.set(`${user.id}`, JSON.stringify(user), {
    EX: customConfig.redisCacheExpiresIn * 60,
  });

  // 2. Create Access and Refresh tokens
  const access_token = signJwt({ sub: user.id }, 'accessTokenPrivateKey', {
    expiresIn: `${customConfig.accessTokenExpiresIn}m`,
  });

  const refresh_token = signJwt({ sub: user.id }, 'refreshTokenPrivateKey', {
    expiresIn: `${customConfig.refreshTokenExpiresIn}m`,
  });

  return { access_token, refresh_token };
};

Creating the Authentication Controllers

Since we have the services already defined, let’s create the authentication controllers to:

validate and register a new user
authenticate and sign in the registered user
authenticate and refresh the expired access token

Before that install the Bcrypt package to hash the plain-text password provided by the user.


yarn add bcryptjs && yarn add -D @types/bcryptjs

Now create a server/controllers/auth.controller.ts file with the following imports.