Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fsobh/auth
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/fsobh/auth
- Owner: fsobh
- Created: 2024-12-11T04:52:28.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2024-12-16T06:42:43.000Z (about 1 month ago)
- Last Synced: 2024-12-16T07:37:44.423Z (about 1 month ago)
- Language: Go
- Size: 2.11 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.MD
Awesome Lists containing this project
README
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](#-overview)
- [👾 Features](#-features)
- [📁 Project Structure](#-project-structure)
- [📂 Project Index](#-project-index)
- [🚀 Getting Started](#-getting-started)
- [☑️ Prerequisites](#-prerequisites)
- [⚙️ Installation](#-installation)
- [🤖 Usage](#🤖-usage)
- [🧪 Testing](#🧪-testing)
- [📌 Project Roadmap](#-project-roadmap)
- [🔰 Contributing](#-contributing)
- [🎗 License](#-license)
- [🙌 Acknowledgments](#-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
```sh
└── 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
├── 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:
```sh
❯ git clone https://github.com/fsobh/auth
```
2. Navigate to the project directory:
```sh
❯ cd auth
```
3. Install the project dependencies:
**Using `go modules`** [
](https://golang.org/)
```sh
❯ 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 | Hexadecimal private key (Paseto V2)
| PASETO_PUBLIC_KEY | Hexadecimal 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:
```sh
❯ docker compose up
```
[//]: # (### 🧪 Testing)
[//]: # (Run the test suite using the following command:)
[//]: # (**Using `go modules`** [](https://golang.org/))
[//]: # ()
[//]: # (```sh)
[//]: # (❯ go test ./...)
[//]: # (```)
---
## 📌 Project Roadmap
- [X] **`Task 1`**: Authentication + sessions.
- [ ] **`Task 2`**: Add RBAC.
- [ ] **`Task 3`**: Add OAuth2 support.
- [ ] **`Task 4`**: Add unit tests.
- [ ] **`Task 5`**: Add Github actions to auto deploy.
---
## 🔰 Contributing
- **💬 [Join the Discussions](https://github.com/fsobh/auth/discussions)**: Share your insights, provide feedback, or ask questions.
- **🐛 [Report Issues](https://github.com/fsobh/auth/issues)**: Submit bugs found or log feature requests for the `auth` project.
- **💡 [Submit Pull Requests](https://github.com/fsobh/auth/blob/main/CONTRIBUTING.md)**: 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.
```sh
git clone https://github.com/fsobh/auth
```
3. **Create a New Branch**: Always work on a new branch, giving it a descriptive name.
```sh
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.
```sh
git commit -m 'Implemented new feature x.'
```
6. **Push to github**: Push the changes to your forked repository.
```sh
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](./LICENSE) file for details.
---
## 🙌 Acknowledgments
- [Zero log](https://github.com/rs/zerolog)
- [sqlc](https://github.com/sqlc-dev/sqlc-gen-go)
- [proto buf](https://github.com/golang/protobuf)
- [mockdb](https://pkg.go.dev/github.com/tmaiaroto/discfg/storage/mockdb)
- [statik](https://github.com/rakyll/statik)
- [asynq](https://github.com/hibiken/asynq)
---