Be Digital Auth

Be Digital Auth is a reusable authentication microservice designed for multi-client backend architectures.

It provides secure JWT-based authentication for distributed systems and exposes both REST and gRPC interfaces, allowing seamless integration with frontend applications and internal microservices.

The service implements a layered authentication model supporting:

• client authentication
• user authentication
• refresh token rotation
• OAuth login providers
• stateless session validation

---

Architecture Overview

The service is designed to act as a centralized authentication gateway inside a microservices ecosystem.

It supports two communication layers:

REST API → browser and frontend integrations
gRPC → internal service-to-service communication

Authentication flow:

Client Token → identifies the application
Access Token → authenticates user requests
Refresh Token → renews sessions securely

This layered token model enables secure multi-client platform architectures such as SaaS systems or distributed backend environments.

---

Tech Stack

Golang
gRPC
REST API
MySQL
Docker
JWT
OAuth2 (Google / Facebook)
Protocol Buffers
Makefile automation

---

Features

• Dual interface: REST + gRPC support
• Multi-layer authentication model
• Stateless JWT validation
• Refresh token flow
• Client credential authentication
• OAuth login with Google and Facebook
• Environment-based configuration
• Docker deployment support
• Protocol Buffers contract definition

---

Use Cases

This service is designed for:

• microservice architectures
• SaaS platforms with multiple client applications
• mobile + web authentication gateways
• centralized authentication services
• distributed backend systems requiring stateless auth

---

Running the Project

⚠ Make sure environment variables are configured before running the service.

Install dependencies:

go mod tidy

Run locally (development mode):

make dev

Run with Docker (production-like environment):

make docker

---

Environment Variables

Copy the example configuration file and rename it:

.env.local.example → .env.local

or

.env.docker.example → .env.docker

Then configure the required values.

Required

• MYSQL_PORT
• MYSQL_HOST
• MYSQL_ROOT_PASSWORD
• MYSQL_DATABASE
• MYSQL_USER
• MYSQL_PASSWORD
• HOST
• GRPC_PORT
• API_PORT
• CLIENT_ACCESS_TOKEN_JWT_KEY
• CLIENT_ACCESS_TOKEN_EXP
• USER_ACCESS_TOKEN_JWT_KEY
• USER_ACCESS_TOKEN_EXP
• USER_REFRESH_TOKEN_JWT_KEY
• USER_REFRESH_TOKEN_EXP
• SUPERADMIN_KEY
• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• FACEBOOK_CLIENT_ID
• FACEBOOK_CLIENT_SECRET

Optional

• APP_ENV (used in docker-compose.yml)
• DEBUG

---

Protocol Buffers (gRPC Contracts)

To modify gRPC request and response contracts, edit:

proto/auth.proto

Then regenerate the Go bindings:

make proto

or manually:

protoc --go_out=. --go-grpc_out=. proto/auth.proto

---

REST API Usage

Authentication requires cookies depending on the endpoint being called.

Supported authentication cookies:

• x-client-token
• x-access-token
• x-refresh-token

---

gRPC Usage Example (Golang)

Example connection and request flow:

import (
	pb "be-digital-auth/proto"
	"context"
	"fmt"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"
	"google.golang.org/grpc/metadata"
)

// gRPC connection
conn, err := grpc.NewClient(
	fmt.Sprintf("%s:%s", envs.HOST, envs.GRPC_PORT),
	grpc.WithTransportCredentials(insecure.NewCredentials()),
)
if err != nil {
	log.Fatalf("Failed to connect: %v", err)
}
defer conn.Close()

// gRPC service
client := pb.NewAuthServiceClient(conn)

// auth metadata
clientToken := "{{ client_token }}"
refreshToken := "{{ refresh_token }}"

ctx := metadata.AppendToOutgoingContext(
	context.Background(),
	string(envs.X_CLIENT_TOKEN),
	"Bearer "+clientToken,
)

ctx = metadata.AppendToOutgoingContext(
	ctx,
	string(envs.AUTHORIZATION),
	"Bearer "+refreshToken,
)

// call gRPC method example
resp, err := client.Refresh(ctx, &pb.EmptyRequest{})
if err != nil {
	log.Fatalf("Error calling Refresh: %v", err)
}

---

Releases

Release 1.0.0

Initial version including core authentication handlers.

---

General Handlers

Refresh (API / gRPC)

Returns a new access token Requires client authentication Requires user authentication via refresh token

GetEmail (API)

Returns the authenticated user's email Requires client authentication Requires user authentication via access token

---

Credential Handlers

SignIn (API / gRPC)

Authenticates user credentials (email + password) Returns access token + refresh token Requires client authentication

SignUp (API / gRPC)

Creates a new user account Requires client authentication

SignInClient (API)

Authenticates client credentials Returns client access token

SignUpClient (API)

Creates a new client Requires superadmin key

---

OAuth Providers

GoogleSignIn (API)

Authenticates users using Google OAuth Returns access token + refresh token Requires client authentication

FacebookSignIn (API)

Authenticates users using Facebook OAuth Returns access token + refresh token Requires client authentication