Como criar uma API segura com gRPC

Uma chamada de procedimento remoto do Google (gRPC) é a versão de código aberto do Google do framework de chamada de procedimento remoto (RPC). Trata-se de um protocolo de comunicação que utiliza HTTP/2 e a tecnologia Protocol Buffers (protobuf). O gRPC permite que um cliente ou servidor remoto se comunique com outro servidor simplesmente chamando uma função do servidor de destino como se ela fosse local. Isso facilita muito a comunicação e a transferência de grandes conjuntos de dados entre cliente e servidor em sistemas distribuídos.

Assim como outros sistemas RPC, o gRPC define um serviço. Ele especifica seus métodos e tipos de retorno usando protobuf — um protocolo do Google para serialização e desserialização —, o que facilita a definição de serviços e a geração automática de bibliotecas de cliente. O gRPC usa esse protocolo, atualmente na versão 3, como linguagem de definição de interface e conjunto de ferramentas de serialização.

Para a maioria das aplicações modernas, o gRPC é uma excelente opção por oferecer suporte excepcional a todos os tipos de dados. Ele é mais indicado para grandes volumes de dados, como os transmitidos por streaming, e pode ser excessivo para aplicações simples nas quais a transferência de grandes volumes não é uma preocupação.

Este artigo demonstra como usar gRPC para estabelecer uma comunicação entre cliente e servidor em duas aplicações Node.js. Também destacamos algumas medidas de segurança ao usar gRPC como mecanismo de comunicação nos seus serviços.

Pré-requisitos do tutorial

Para acompanhar este tutorial, você precisa ter o OpenSSL e o Node.js (versão 4.0 ou posterior) instalados no seu computador. É essencial ter conhecimentos básicos de Node.js e JavaScript. Você também precisa garantir que seu ambiente de trabalho tenha privilégios administrativos.

Configurando o projeto Node.js

Para começar, crie uma pasta chamada event-app-node-grpc para definir a estrutura de diretórios da aplicação e inicialize um projeto Node.js com npm executando os seguintes comandos:

1#bash
2$ mkdir event-app-node-grpc
3$ cd event-app-node-grpc
4$ npm init -y

Depois de inicializar a aplicação, crie a seguinte estrutura de diretórios. Você pode acessar no GitHub o código completo usado neste tutorial:

1Event-app-node-grpc
2client
3app.js
4index.js
5server
6index.js
7scripts
8generate-certs.sh
9events.proto
10README.md

Instalando os pacotes

No terminal, acesse o diretório raiz da aplicação. Instale os pacotes a seguir usando o comando npm install, conforme mostrado no trecho de código:

1#bash
2$ npm install express @grpc/grpc-js @grpc/proto-loader

Veja o que fazem os pacotes instalados no trecho de código acima:

• Express é o servidor HTTP da sua aplicação.

• @grpc/grpc-js é uma biblioteca gRPC para Node.js. Ela permite criar um serviço gRPC no ambiente de execução Node.js.

• @grpc/proto-loader é um pacote necessário para carregar arquivos protobuf e usá-los com gRPC. Ele usa o pacote versão 3 do protobuf.js.

Depois de instalar os pacotes acima, abra o arquivo package.json e adicione as configurações extras a seguir às tags scripts, como mostrado no trecho de código:

1#package.json
2
3"scripts": {
4   "start": "node server/index.js",
5   "generate:certs": "./scripts/generate-certs.sh"
6 },

As configurações adicionais mostradas no trecho de código acima definem o ambiente de execução da aplicação e a geração do certificado SSL. Depois de adicioná-las, seu arquivo package.json atualizado ficará parecido com o trecho de código abaixo:

1#package.json(updated)
2
3{
4 "name": "event-app-node-grpc",
5 "version": "1.0.0",
6 "description": "A CRUD application to demonstrate the use of gRPC with NodeJS",
7 "main": "server/index.js",
8 "scripts": {
9   "start": "node server/index.js",
10   "generate:certs": "./scripts/generate-certs.sh"
11 },
12 "author": "(author name here)",
13 "license": "ISC",
14 "dependencies": {
15   "@grpc/proto-loader": "^0.6.12",
16   "express": "^4.18.1",
17   "@grpc/grpc-js": "^1.6.12
18 }
19}

O trecho de código acima mostra o arquivo package.json atualizado, com os comandos de configuração do ambiente de execução da aplicação e de geração do certificado SSL adicionados à tag scripts.

Definindo o Protocol Buffer

Este tutorial mostra como usar gRPC em uma aplicação simples de rastreamento de eventos. A aplicação de demonstração recebe detalhes de eventos e os salva em um banco de dados em memória, permitindo atualizar, buscar e excluir os dados dos eventos.

Em aplicações gRPC, a interface do serviço e os payloads necessários ficam em um arquivo protobuf para permitir a comunicação entre diferentes aplicações. Os arquivos protobuf têm a extensão .proto, como mostra o esquema de configuração do nosso projeto.

Agora, crie um arquivo events.proto no diretório raiz da aplicação e adicione o código a seguir. Para consultar a estrutura do projeto, use como referência o esquema que definimos anteriormente.

1#events.proto
2
3syntax = "proto3";
4
5service EventService {
6   rpc GetAllEvents (Empty) returns (EventList) {}
7   rpc GetEvent (EventId) returns (Event) {}
8   rpc CreateEvent (Event) returns (Event) {}
9   rpc UpdateEvent (Event) returns (Event) {}
10   rpc DeleteEvent (EventId) returns (Empty) {}
11}
12
13message Empty {}
14
15message Event {
16   string id = 1;
17   string name = 2;
18   string description = 3;
19   string location = 4;
20   string duration = 5;
21   int32 lucky_number = 6;
22   string status = 7;
23}
24
25message EventList {
26   repeated Event events = 1;
27}
28
29message EventId {
30   string id = 1;
31}

Nos trechos de código acima, que definem o proto, primeiro especificamos a versão do Protocol Buffer com a declaração syntax = "proto3" e, em seguida, definimos o serviço do protocolo.

Em seguida, na descrição do serviço de eventos do protocolo, criamos um serviço chamado EventService. Depois, criamos funções rpc nesse serviço, com os parâmetros necessários e os valores de retorno esperados. Você pode definir quantos serviços sua aplicação precisar, mas, para simplificar, vamos definir apenas um.

Também definimos os tipos de dados da função rpc na definição de EventService e os valores de retorno usando o sistema exclusivo de numeração de campos do gRPC. Ele especifica o número de bytes usados durante a codificação. Saiba mais na documentação oficial do protobuf.

Criando o servidor gRPC

Seguindo a estrutura de diretórios acima, crie uma pasta server no diretório raiz da aplicação e, dentro dela, crie um arquivo index.js. Cole o trecho de código a seguir no arquivo recém-criado server/index.js:

1#server/index.js
2
3const PROTO_PATH = "./events.proto";
4
5let grpc = require("@grpc/grpc-js");
6let protoLoader = require("@grpc/proto-loader");
7
8let packageDefinition = protoLoader.loadSync(PROTO_PATH, {
9   keepCase: true,
10   longs: String,
11   enums: String,
12   arrays: true
13});
14
15let eventsProto = grpc.loadPackageDefinition(packageDefinition);

No trecho de código acima, importamos o arquivo events.proto, definido anteriormente, para a variável PROTO_PATH e o carregamos usando o método loadSync da biblioteca protoLoader. Em seguida, salvamos as definições do proto na variável eventsProto, que armazena todas elas.

Em seguida, adicione o trecho de código a seguir logo depois da variável eventsProto no arquivo server/index.js definido anteriormente.

1const { randomUUID } = require("node:crypto");
2
3const events = [
4   {
5       id: "34415c7c-f82d-4e44-88ca-ae2a1aaa92b7",
6       name: "Birthday Party",
7       description: "27th Birthday in Paris",
8       location: "Paris France",
9       duration: "All Day",
10       lucky_number: 27,
11       status: "Pending"
12   },
13];
14
15const server = new grpc.Server();

No trecho de código acima, importamos o pacote node:crypto e sua função randomUUID, usada para gerar strings exclusivas aleatórias para os IDs dos eventos. Como usamos um banco de dados em memória neste tutorial, vamos defini-lo como um array para armazenar a lista de eventos e, em seguida, configurar a instância do servidor chamando um novo método grpc.Server.

Em seguida, vamos registrar os serviços da aplicação. Para isso, adicione o trecho de código a seguir logo depois da variável server no trecho de código acima:

1server.addService(eventsProto.EventService.service, {
2
3   getAllEvents: (_, callback) => {
4       callback(null, { events });
5   },
6
7   getEvent: (call, callback) => {
8       let event = events.find(n => n.id == call.request.id);
9
10       if (event) {
11           callback(null, event);
12       } else {
13           callback({
14               code: grpc.status.NOT_FOUND,
15               details: "Event Not found"
16           });
17       }
18   },
19
20   createEvent: (call, callback) => {
21       let event = call.request;
22
23       event.id = randomUUID();
24       events.push(event);
25       callback(null, event);
26   },
27
28   updateEvent: (call, callback) => {
29       let existingEvent = events.find(n => n.id == call.request.id);
30
31       if (existingEvent) {
32           existingEvent.name = call.request.name;
33           existingEvent.description = call.request.description;
34           existingEvent.location = call.request.location;
35           existingEvent.duration = call.request.duration;
36           existingEvent.lucky_number = call.request.lucky_number;
37           existingEvent.status = call.request.status;
38           callback(null, existingEvent);
39       } else {
40           callback({
41               code: grpc.status.NOT_FOUND,
42               details: "Event Not found"
43           });
44       }
45   },
46
47   deleteEvent: (call, callback) => {
48       let existingEventIndex = events.findIndex(
49           n => n.id == call.request.id
50       );
51
52       if (existingEventIndex != -1) {
53           events.splice(existingEventIndex, 1);
54           callback(null, {});
55       } else {
56           callback({
57               code: grpc.status.NOT_FOUND,
58               details: "Event Not found"
59           });
60       }
61   }
62});

No trecho de código acima, chamamos o método addService na instância do servidor gRPC para registrar os serviços da aplicação, que basicamente realizam operações de criação, leitura e atualização dos eventos.

Para iniciar o servidor da aplicação, cole o trecho de código a seguir logo depois do método addService mostrado no trecho de código acima.

1server.bindAsync("127.0.0.1:50051", grpc.ServerCredentials.createInsecure(), (error, port) => {
2console.log(`Server listening at http://127.0.0.1:${port}`);
3server.start();
4});

Criando o cliente gRPC

Seguindo a estrutura de diretórios acima, crie uma pasta client no diretório raiz da aplicação e, dentro dela, crie dois arquivos: index.js e app.js. Cole o trecho de código a seguir no arquivo client/app.js.

1#client/app.js
2
3const PROTO_PATH = "../events.proto";
4const grpc = require("@grpc/grpc-js");
5const protoLoader = require("@grpc/proto-loader");
6
7let packageDefinition = protoLoader.loadSync(PROTO_PATH, {
8   keepCase: true,
9   longs: String,
10   enums: String,
11   arrays: true
12});
13
14const EventService = grpc.loadPackageDefinition(packageDefinition).EventService;
15const client = new EventService("127.0.0.1:50051", grpc.credentials.createInsecure());
16module.exports = client;

No trecho de código acima, importamos as definições do proto criadas anteriormente, carregamos o arquivo com protoLoader, conectamos o cliente grpc ao endereço IP da aplicação do servidor e exportamos o serviço de eventos com o nome de variável client. Também associamos um certificado SSL ao cliente para autenticar e criptografar as comunicações entre cliente e servidor.

Em seguida, cole o trecho de código a seguir no arquivo client/index.js:

1#client/index.js
2
3const client = require("./app");
4
5const express = require("express");
6const app = express();
7app.disable('x-powered-by');
8app.use(express.json());
9app.use(express.urlencoded());
10
11app.get("/", (req, res) => {
12   client.getAllEvents(null, (err, data) => {
13       if (!err) {
14           res.status(200).send({
15               data
16           });
17       }
18   });
19});
20
21app.post("/createEvent", (req, res) => {
22
23   let newEvent = {
24       name: req.body.name,
25       description: req.body.age,
26       location: req.body.address,
27       duration: req.body.address,
28       lucky_number: req.body.address,
29       status: req.body.status
30   };
31
32   client.insert(newEvent, (err, data) => {
33       if (err) throw err;
34       res.status(200).send({
35           data,
36           message: 'Event created successfully'
37       });
38   });
39});
40
41app.post("/updateEvent", (req, res) => {
42   let updateEvent = {
43       name: req.body.name,
44       description: req.body.age,
45       location: req.body.address,
46       duration: req.body.address,
47       lucky_number: req.body.address,
48       status: req.body.status
49   };
50
51   client.update(updateEvent, (err, data) => {
52       if (err) throw err;
53
54       res.status(200).send({
55           data,
56           message: 'Event updated successfully'
57       });
58   });
59});
60
61app.delete("/deleteEvent", (req, res) => {
62   client.remove({ id: req.body.eventId }, (err, _) => {
63       if (err) throw err;
64
65       res.status(200).send({
66           message: 'Event deleted successfully'
67       });
68   });
69});
70
71const PORT = process.env.PORT || 50050;
72app.listen(PORT, () => {
73   console.log("Client Server listening to port %d", PORT);
74});

No trecho de código acima, importamos event-service do arquivo client/app.js. Depois, configuramos um servidor Express com endpoints simples para gerenciar a creation, a update, a fetch e a delete de eventos, chamando remotamente a aplicação do servidor com gRPC.

Testando as aplicações do servidor e do cliente

Agora podemos testar o que fizemos para confirmar que está tudo certo.

O servidor

No terminal, acesse o diretório raiz do projeto e execute os seguintes comandos:

1$bash
2$ npm run start

O servidor da aplicação deverá estar disponível em http://localhost:50051:

1% npm run start
2> event-app-node-grpc@1.0.0 start
3> node server/index.js
4
5Server listening at https://127.0.0.1:50051

O cliente

Abra uma nova janela do terminal, acesse a pasta client a partir do diretório raiz da aplicação e execute os seguintes comandos:

1$bash
2$ node index

A aplicação deverá estar disponível em http://localhost:50050:

1$ event-app-node-grpc  cd client
2$ event-app-node-grpc/client node index.js
3
4Client Server listening to port 50050

Para testar, acesse localhost:50050 no navegador ou use uma ferramenta de teste de API, como o Postman. Você deverá ver o evento padrão que adicionamos inicialmente ao array de eventos. A resposta deverá ser igual à captura de tela abaixo:

Autenticando e protegendo a API gRPC

O protocolo gRPC oferece suporte a vários mecanismos de autenticação, o que facilita sua adaptação a sistemas novos e existentes. Podemos implementar a autenticação nas comunicações entre cliente e servidor gRPC usando mecanismos recomendados, como SSL e TLS, com ou sem autenticação baseada em tokens do Google. Também podemos criar uma autenticação personalizada estendendo a função de autenticação integrada ao gRPC.

Por padrão, o gRPC inclui os seguintes mecanismos de autenticação:

• SSL e TLS para autenticar o servidor e criptografar os dados trocados entre cliente e servidor

• ALTS (um protocolo mútuo de transporte e autenticação desenvolvido pelo Google) para proteger as comunicações RPC de aplicações executadas na Google Cloud Platform (GCP)

• Mecanismo genérico de autenticação baseada em tokens para incluir credenciais baseadas em metadados nas solicitações e respostas

Como mencionamos na introdução do tutorial, vamos implementar a autenticação usando SSL e, em seguida, modificar os arquivos client/app.js e server/index.js para incorporar essa mudança.

Gerando um certificado SSL com OpenSSL

Primeiro, vamos gerar um certificado SSL usando o OpenSSL. Para isso, você precisa ter o OpenSSL instalado e permissão para executar scripts bash. Esses requisitos são essenciais para evitar erros de permissão.

Na estrutura de diretórios do projeto, crie uma pasta scripts e, dentro dela, um arquivo chamado generate-certs.sh. Cole o trecho de código a seguir nesse arquivo:

1#scripts/generate-certs.sh
2
3echo "Creating certs folder ..."
4mkdir certs && cd certs
5
6echo "Generating certificates ..."
7
8openssl genrsa -passout pass:1111 -des3 -out ca.key 4096
9
10openssl req -passin pass:1111 -new -x509 -days 365 -key ca.key -out ca.crt -subj  "/C=CL/ST=RM/L=Santiago/O=Test/OU=Test/CN=localhost"
11
12openssl genrsa -passout pass:1111 -des3 -out server.key 4096
13
14openssl req -passin pass:1111 -new -key server.key -out server.csr -subj  "/C=CL/ST=RM/L=Santiago/O=Test/OU=Server/CN=localhost"
15
16openssl x509 -req -passin pass:1111 -days 365 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server.crt
17
18openssl rsa -passin pass:1111 -in server.key -out server.key
19
20openssl genrsa -passout pass:1111 -des3 -out client.key 4096
21
22openssl req -passin pass:1111 -new -key client.key -out client.csr -subj  "/C=CL/ST=RM/L=Santiago/O=Test/OU=Client/CN=localhost"
23
24openssl x509 -passin pass:1111 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out client.crt
25
26openssl rsa -passin pass:1111 -in client.key -out client.key

O código acima gera os certificados SSL necessários para estabelecer uma conexão segura e criptografada entre as aplicações do servidor e do cliente. Quando executado, ele cria uma pasta certs, gera os certificados SSL do servidor e do cliente com o OpenSSL e os salva na pasta certs. Para saber mais sobre essas configurações e sua finalidade, acesse o site do OpenSSL.

Gerando um certificado SSL para a aplicação com npm

Agora, use o script para gerar um certificado SSL para a aplicação. No terminal, acesse o diretório raiz da aplicação e execute os seguintes comandos.

1$bash
2$ npm run generate:certs

Isso cria uma pasta certs com os certificados SSL gerados.

Atenção: são necessários alguns privilégios administrativos. Se ocorrer um erro de permissões ao executar o script, use os comandos a seguir para conceder permissão de execução e tente novamente.

1$bash
2$ cd scripts
3$ chmod u+r+x generate-certs.sh
4$ ./generate-certs.sh

O terminal deverá exibir a seguinte saída:

1> event-app-node-grpc@1.0.0 generate:certs
2> ./scripts/generate-certs.sh
3
4Creating certs folder…
5Generating certificates…
6Generating RSA private key, 4096 bit long modulus
7………………………………………………..++
8……………..++
9
10e is 65537 (0x10001)
11Generating RSA private key, 4096 bit long modulus
12…………………++
13………………………………………….….….….….….………..…………..++
14e is 65537 (0x10001)
15Signature ok
16subject=/C=CL/ST=RM/L=Santiago/0=Test/OU=Server/CN=localhost
17Getting CA Private Key
18writing RSA key
19Generating RSA private key, 4096 bit long modulus
20………………………………………………..….….….…………..++
21.…………..++
22e is 65537 (0x10001)
23Signature ok
24subject=/C=CL/ST=RM/L=Santiago/0=Test/OU=Client/ON=localhost
25Getting CA Private Key
26writing RSA key

Atualizando os arquivos client/app.js e server/index.js

Até agora, geramos os certificados SSL necessários para autenticar nossas APIs gRPC. Agora, vamos modificar os arquivos client/index.js e server/index.js para usar os certificados gerados.

No arquivo client/app.js atualizado, mostrado abaixo, adicionamos o módulo fs para ler os certificados gerados e usamos esses certificados para criar credenciais SSL do gRPC. Por fim, aplicamos essas credenciais ao serviço gRPC.

1#client/app.js(updated)
2
3const PROTO_PATH = "../events.proto";
4const fs = require('fs');
5const grpc = require("@grpc/grpc-js");
6const protoLoader = require("@grpc/proto-loader");
7
8let packageDefinition = protoLoader.loadSync(PROTO_PATH, {
9   keepCase: true,
10   longs: String,
11   enums: String,
12   arrays: true
13});
14
15const credentials = grpc.credentials.createSsl(
16   fs.readFileSync('../certs/ca.crt'),
17   fs.readFileSync('../certs/client.key'),
18   fs.readFileSync('../certs/client.crt')
19);
20
21const EventService = grpc.loadPackageDefinition(packageDefinition).EventService;
22const client = new EventService("localhost:50051",credentials);
23module.exports = client;

Também adicionamos o módulo fs ao arquivo server/index.js atualizado, mostrado abaixo, para ler os certificados gerados. Em seguida, usamos esses certificados para criar credenciais SSL do gRPC e aplicá-las ao servidor.

1#server/index.js(updated)
2
3const PROTO_PATH = "./events.proto";
4const fs = require('fs');
5
6let grpc = require("@grpc/grpc-js");
7let protoLoader = require("@grpc/proto-loader");
8
9let packageDefinition = protoLoader.loadSync(PROTO_PATH, {
10   keepCase: true,
11   longs: String,
12   enums: String,
13   arrays: true
14});
15
16let eventsProto = grpc.loadPackageDefinition(packageDefinition);
17
18const server = new grpc.Server();
19
20let credentials = grpc.ServerCredentials.createSsl(
21   fs.readFileSync('./certs/ca.crt'), [{
22   cert_chain: fs.readFileSync('./certs/server.crt'),
23   private_key: fs.readFileSync('./certs/server.key')
24}], true);
25
26----------
27
28----------
29
30server.bindAsync("0.0.0.0:50051", credentials, (error, port) => {
31console.log(`Server listening at http://0.0.0.0:${port}`);
32server.start();
33});

Executando as aplicações do servidor e do cliente

Implementamos com sucesso uma solução de gerenciamento de eventos usando as especificações gRPC. Para testar os endpoints, inicie a aplicação pelo terminal seguindo as etapas abaixo.

O servidor

No terminal, acesse o diretório raiz do projeto e execute os seguintes comandos:

1$bash
2$ npm run start

Depois de executar os comandos, o servidor deverá estar disponível em http://0.0.0.0:50051:

1event-app-node-grpc % npm run start
2
3> event-app-node-grpc@1.0.0 start
4> node server/index.js
5
6Server listening at http://0.0.0.0:50051

O cliente

Abra uma nova janela do terminal, acesse a pasta do cliente a partir do diretório raiz da aplicação e execute os seguintes comandos:

1$bash
2$ node index

Depois de executar os comandos, a aplicação cliente deverá estar disponível em http://localhost:50050:

1> event-app-node-grpc % cd client
2> client % node index
3Client Server listening to port 50050

Para testar a aplicação, acesse localhost:50050 no navegador ou use uma ferramenta de teste de API, como o Postman. Você verá o evento padrão que adicionamos inicialmente ao nosso array de eventos. A resposta deverá ser igual à captura de tela abaixo:

Você pode testar outros endpoints adicionados à aplicação para garantir que tudo funcione como esperado.

Você criou uma API segura com gRPC!

Neste tutorial, criamos uma API simples com gRPC usando Node.js e apresentamos seus conceitos de funcionamento e suas diversas vantagens, como o uso de HTTP/2 e SSL/TLS para autenticação e criptografia de ponta a ponta, que aumentam a segurança da API.

Apesar dessas vantagens, o gRPC também tem pontos fracos, como o suporte limitado nos navegadores, o formato de dados não legível por humanos, a curva de aprendizado íngreme e o suporte precário ao cache na borda. Ainda assim, o gRPC é a melhor opção para a comunicação entre microsserviços internos, graças ao desempenho incomparável e ao suporte a várias linguagens. O protocolo gRPC é impressionante e, desde seu lançamento, em agosto de 2016, vem sendo amplamente adotado no setor. Essa adoção deve continuar crescendo.

Há muitas outras possibilidades com o gRPC. O exemplo deste tutorial é apenas a ponta do iceberg. Consulte a documentação para aprofundar seus conhecimentos sobre gRPC, aprimorar os processos de comunicação da sua aplicação e conhecer estratégias para manter a segurança do gRPC.

Mais recursos sobre APIs:

• Criando uma API GraphQL segura com Node.js

• Conteinerizando aplicações Go com Docker