Authentication service

• Supports HTTP/2 and gRPC protocols.
• PostgreSQL database with sqlc for type-safe queries.
• Redis queue for background tasks.

🔗 Table of Contents

• 📍 Overview
• 👾 Features
• 📁 Project Structure
  • 📂 Project Index
• 🚀 Getting Started
  • ☑️ Prerequisites
  • ⚙️ Installation
  • 🤖 Usage
  • 🧪 Testing
• 📌 Project Roadmap
• 🔰 Contributing
• 🎗 License
• 🙌 Acknowledgments

---

📍 Overview

A Golang authentication service API, supporting both HTTP/2 and gRPC protocols. The service is designed to provide user authentication and authorization features, including user registration, login, and email verification. The service is built using a PostgreSQL database with sqlc for type-safe queries and a Redis queue for background tasks.

---

👾 Features

• User Registration: Register a new user with a unique email, username, and password.
• Email Verification: Sends a verification email to a user's email address. User creation will rollback if verification email fails to send (using transactional queries with callbacks)
• User Login: Authenticate a user with a valid email and password.
• User Update: Update a user's profile information, including their email, username, and password.

---

📁 Project Structure

└── auth/
    ├── db
    │   ├── migration
    │   ├── query
    │   └── sqlc
    ├── doc
    │   ├── db.dbml
    │   ├── statik
    │   └── swagger
    ├── gapi
    │   ├── authorization.go
    │   ├── converter.go
    │   ├── error.go
    │   ├── logger.go
    │   ├── metadata.go
    │   ├── rpc_create_user.go
    │   ├── rpc_login_user.go
    │   ├── rpc_update_user.go
    │   ├── rpc_verify_email.go
    │   └── server.go
    ├── go.mod
    ├── go.sum
    ├── main.go
    ├── makefile
    ├── pb
    │   ├── rpc_create_user.pb.go
    │   ├── rpc_login_user.pb.go
    │   ├── rpc_update_user.pb.go
    │   ├── rpc_verify_email.pb.go
    │   ├── service_auth.pb.go
    │   ├── service_auth.pb.gw.go
    │   ├── service_auth_grpc.pb.go
    │   └── user.pb.go
    ├── proto
    │   ├── google
    │   ├── protoc-gen-openapiv2
    │   ├── rpc_create_user.proto
    │   ├── rpc_login_user.proto
    │   ├── rpc_update_user.proto
    │   ├── rpc_verify_email.proto
    │   ├── service_auth.proto
    │   └── user.proto
    ├── sqlc.yaml
    ├── token
    │   ├── jwt_maker.go
    │   ├── maker.go
    │   ├── paseto_asym_maker.go
    │   ├── paseto_maker.go
    │   ├── payload.go
    │   ├── jwt_maker_test.go
    │   ├── paseto_asym_maker_test.go
    │   └── paseto_test.go
    ├── util
    │   ├── config.go
    │   ├── password.go
    │   └── random.go
    ├── val
    │   └── validator.go
    └── worker
        ├── distributor.go
        ├── logger.go
        ├── processor.go
        └── task_send_verify_email.go

📂 Project Index

AUTH/

__root__

makefile	❯ makefile with commands for local development
main.go	❯ Main entry point for API service
go.mod	❯ Go mod file
go.sum	❯ Go sum file
sqlc.yaml	❯ Sqlc V2 configuration file

worker

processor.go	❯ Task processor for Redis queue - picks up tasks from the queue to process and run them
task_send_verify_email.go	❯ Redis queue task for sending out the verification email to new users
logger.go	❯ Logger for the Redis queue
distributor.go	❯ Redis task distributor interface - distributes the tasks into appropriate queues

proto

user.proto	❯ proto buff specification for `User` object serialization
rpc_update_user.proto	❯ proto buff specification for `Update user` request / response serialization
rpc_create_user.proto	❯ proto buff specification for `Create user` request / response serialization
service_auth.proto	❯ proto buff specification for API service
rpc_verify_email.proto	❯ proto buff specification for `Verify email` request / response serialization
rpc_login_user.proto	❯ proto buff specification for `Login user` request / response serialization

protoc-gen-openapiv2

options

openapiv2.proto	❯ REPLACE-ME
annotations.proto	❯ REPLACE-ME

google

api

httpbody.proto	❯ REPLACE-ME
field_behavior.proto	❯ REPLACE-ME
http.proto	❯ REPLACE-ME
annotations.proto	❯ REPLACE-ME

doc

db.dbml

❯ Database markup version of the database schema

statik

statik.go

❯ Serves static swagger specification page

swagger

swagger-initializer.js	❯ cloned from swagger-ui
swagger-ui-standalone-preset.js	❯ cloned from swagger-ui
auth.swagger.json	❯ cloned from swagger-ui
swagger-ui-es-bundle.js	❯ cloned from swagger-ui
swagger-ui-bundle.js	❯ cloned from swagger-ui
index.css	❯ cloned from swagger-ui
swagger-ui-es-bundle-core.js	❯ cloned from swagger-ui
swagger-ui.js	❯ cloned from swagger-ui
swagger-ui.css	❯ cloned from swagger-ui
index.html	❯ cloned from swagger-ui
oauth2-redirect.html	❯ cloned from swagger-ui

gapi

metadata.go	❯ Helper to capture metadata of gRPC gateway requests
logger.go	❯ Logger file for gRPC & HTTP requests
authorization.go	❯ Validates token format for incoming authorized calls
rpc_update_user.go	❯ Function that is called to update a user record when the api endpoint is invoked
rpc_verify_email.go	❯ Function that is called to verify a new users email when the api endpoint is invoked
error.go	❯ Helper to handle generic errors (invalid request params, unauthorized calls)
rpc_login_user.go	❯ Function that is called to log a user into their account when the api endpoint is invoked
converter.go	❯ Helper to sanitize User database objects from sensitive data (like password)
rpc_create_user.go	❯ Function that is called to create a new user account when the api endpoint is invoked
server.go	❯ Initializes a new Server to run

val

validator.go

❯ Helper to validate string format for email, names, passwords, etc...

pb

user.pb.go	❯ Code generated by protoc-gen-go
service_auth_grpc.pb.go	❯ Code generated by protoc-gen-go
rpc_login_user.pb.go	❯ Code generated by protoc-gen-go
rpc_update_user.pb.go	❯ Code generated by protoc-gen-go
rpc_create_user.pb.go	❯ Code generated by protoc-gen-go
service_auth.pb.go	❯ Code generated by protoc-gen-go
service_auth.pb.gw.go	❯ Code generated by protoc-gen-go
rpc_verify_email.pb.go	❯ Code generated by protoc-gen-go

util

password.go	❯ Helper to hash & compare passwords
config.go	❯ Server configs read from app.env
random.go	❯ Random generator utility

db

sqlc

models.go	❯ Code generated by sqlc
db.go	❯ Code generated by sqlc
verify_email.sql.go	❯ Code generated by sqlc
user.sql.go	❯ Code generated by sqlc
querier.go	❯ Code generated by sqlc
tx_verify_email.go	❯ Transactional write to the database to update user records across tables when email is verified
store.go	❯ SQLStore provides all functions to execute db queries and transactions. Also used to Mock DB for tests
tx_create_user.go	❯ Transactional write that creates a user in the database. This transaction has a callback that executes only when the database write is successful. We use this call back to send out the verification email upon sign up
sessions.sql.go	❯ Code generated by sqlc

query

user.sql	❯ Queries & annotations pertaining to users for sqlc to generate application database code
sessions.sql	❯ Queries & annotations pertaining to sessions for sqlc to generate application database code
verify_email.sql	❯ Queries & annotations pertaining to verifying emails for sqlc to generate application database code

migration

000001_init_schema.up.sql	❯ Initial database schema for migrate up to use
000001_init_schema.down.sql	❯ Initial drop database schema for migrate down to use

---

🚀 Getting Started

☑️ Prerequisites

Before getting started with auth, ensure your runtime environment meets the following requirements:

• Programming Language: Go
• Package Manager: Go modules
• Containerization: Docker

⚙️ Installation

Install auth using the following methods:

1. Clone the auth repository:

❯ git clone https://github.com/fsobh/auth

2. Navigate to the project directory:

❯ cd auth

3. Install the project dependencies:

Using go modules  

❯ go mod tidy

🤖 Usage

Steps 1 and 2 are essential for the service to run

1. Update app.env with your environment variables

   Name	Description
   PASETO_PRIVATE_KEY	private key (Paseto V2)
   PASETO_PUBLIC_KEY	public key (Paseto V2)
   SES_FROM_EMAIL	Verified AWS SES email address

2. Update the .env file with your AWS account credentials

   Name	Description
   AWS_ACCESS_KEY_ID	AWS IAM access key
   AWS_SECRET_ACCESS_KEY	AWS IAM secret key
   AWS_DEFAULT_REGION	AWS region

3. Run the following command to start the service:

❯ docker compose up  

---

📌 Project Roadmap

• Task 1: Authentication + sessions.
• Task 2: Add unit tests.
• Task 3: Upgrade db driver from lib/pq to pgx/v5.
• Task 4: Add RBAC.
• Task 5: Add OAuth2 support.
• Task 6: Add Github actions to auto deploy.

---

🔰 Contributing

• 💬 Join the Discussions: Share your insights, provide feedback, or ask questions.
• 🐛 Report Issues: Submit bugs found or log feature requests for the auth project.
• 💡 Submit Pull Requests: Review open PRs, and submit your own PRs.

Contributing Guidelines

1. Fork the Repository: Start by forking the project repository to your github account.
2. Clone Locally: Clone the forked repository to your local machine using a git client.

   git clone https://github.com/fsobh/auth

3. Create a New Branch: Always work on a new branch, giving it a descriptive name.

   git checkout -b new-feature-x

4. Make Your Changes: Develop and test your changes locally.
5. Commit Your Changes: Commit with a clear message describing your updates.

   git commit -m 'Implemented new feature x.'

6. Push to github: Push the changes to your forked repository.

   git push origin new-feature-x

7. Submit a Pull Request: Create a PR against the original project repository. Clearly describe the changes and their motivations.
8. Review: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!

Contributor Graph

---

🎗 License

• This project is licensed under the MIT License. See the LICENSE file for details.

---

🙌 Acknowledgments

• Zero log
• sqlc
• proto buf
• mockdb
• statik
• asynq

---