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
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__
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
protoc-gen-openapiv2
options
google
api
doc
| db.dbml |
❯ Database markup version of the database schema |
statik
| statik.go |
❯ Serves static swagger specification page |
swagger
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
util
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
🚀 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:
- Clone the auth repository:
❯ git clone https://github.com/fsobh/auth
- Navigate to the project directory:
❯ cd auth
- Install the project dependencies:
Using go modules 
❯ go mod tidy
🤖 Usage
Steps 1 and 2 are essential for the service to run
-
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 |
-
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 |
-
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
Contributing Guidelines
- Fork the Repository: Start by forking the project repository to your github account.
- Clone Locally: Clone the forked repository to your local machine using a git client.
git clone https://github.com/fsobh/auth
- Create a New Branch: Always work on a new branch, giving it a descriptive name.
git checkout -b new-feature-x
- Make Your Changes: Develop and test your changes locally.
- Commit Your Changes: Commit with a clear message describing your updates.
git commit -m 'Implemented new feature x.'
- Push to github: Push the changes to your forked repository.
git push origin new-feature-x
- Submit a Pull Request: Create a PR against the original project repository. Clearly describe the changes and their motivations.
- 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
README
¶
Documentation
¶
Source Files
Directories