193 lines
4.9 KiB
Markdown
193 lines
4.9 KiB
Markdown
|
|
# 🛡️ AccessHandler
|
|
|
|
A lightweight **Golang authentication and access management module** built with **Gin**, **GORM**, and **JWT**.
|
|
It provides ready-to-use user authentication (login, refresh, logout, user info) with secure cookies and SQLite persistence.
|
|
|
|
---
|
|
|
|
## 🚀 Features
|
|
|
|
- 🔐 **JWT-based authentication** (access + refresh tokens)
|
|
- 🍪 **Secure HTTP-only cookies**
|
|
- 🧩 **Modular handler design** (AccessHandler, DBHandler)
|
|
- 🗃️ **SQLite via GORM**
|
|
- 🪵 **Structured logging**
|
|
- ⚙️ **Plug-and-play Gin integration**
|
|
|
|
---
|
|
|
|
## 📂 Project Structure
|
|
|
|
```
|
|
AccessHandler/
|
|
├── handlers/
|
|
│ ├── access_handler.go # AccessHandler initialization
|
|
│ ├── db_handler.go # Database handler using GORM
|
|
│ ├── login.go # Login, Refresh, Me, Logout handlers
|
|
│ ├── middleware.go # middleware authentification
|
|
| ├── role.go # database handling for roles
|
|
| ├── user.go # database users for roles
|
|
|
|
|
├── models/
|
|
│ ├── jsonResponse.go # Json responses model
|
|
│ ├── permission.go # Permission model
|
|
│ ├── role.go # Role model + validation
|
|
│ ├── settings.go # Settings model
|
|
│ ├── user.go # User model + validation
|
|
│
|
|
├── utils/
|
|
│ ├── hash.go # Password hashing and verification
|
|
│
|
|
├── main.go # Gin server entry point (example)
|
|
└── go.mod # Go module file
|
|
```
|
|
|
|
---
|
|
|
|
## ⚙️ Installation
|
|
|
|
```bash
|
|
git clone https://gitea.tecamino.com/paadi/AccessHandler.git
|
|
cd AccessHandler
|
|
go mod tidy
|
|
```
|
|
|
|
---
|
|
|
|
## 🧱 Dependencies
|
|
|
|
This project uses:
|
|
|
|
- [Gin Web Framework](https://github.com/gin-gonic/gin)
|
|
- [GORM ORM](https://gorm.io)
|
|
- [SQLite Driver for GORM](https://github.com/glebarez/sqlite)
|
|
- [Golang JWT v5](https://github.com/golang-jwt/jwt)
|
|
- [Tecamino Logger (custom)](https://gitea.tecamino.com/paadi/tecamino-logger/logging)
|
|
|
|
Install manually (if needed):
|
|
|
|
```bash
|
|
go get github.com/gin-gonic/gin
|
|
go get github.com/glebarez/sqlite
|
|
go get gorm.io/gorm
|
|
go get github.com/golang-jwt/jwt/v5
|
|
go get https://gitea.tecamino.com/paadi/tecamino-logger/logging
|
|
```
|
|
|
|
---
|
|
|
|
## 🔑 Authentication Constants
|
|
|
|
In `handlers/login.go`:
|
|
|
|
```go
|
|
// -----------------------------
|
|
// 🔐 AUTHENTICATION CONSTANTS
|
|
// -----------------------------
|
|
var DOMAIN = "localhost"
|
|
var ACCESS_TOKEN_TIME = 15 * time.Minute
|
|
var REFRESH_TOKEN_TIME = 72 * time.Hour
|
|
|
|
var ACCESS_SECRET = []byte("*") // replace "*" with strong random bytes
|
|
var REFRESH_SECRET = []byte("*")
|
|
```
|
|
|
|
> 💡 In production, **never hardcode secrets** — use environment variables instead:
|
|
>
|
|
> ```go
|
|
> var ACCESS_SECRET = []byte(os.Getenv("ACCESS_SECRET"))
|
|
> var REFRESH_SECRET = []byte(os.Getenv("REFRESH_SECRET"))
|
|
> ```
|
|
|
|
---
|
|
|
|
## 🧠 API Endpoints
|
|
|
|
| Method | Endpoint | Description | Auth Required |
|
|
|--------|------------------|--------------------------------------|----------------|
|
|
| `POST` | `/login` | Authenticate user, set JWT cookies | ❌ No |
|
|
| `GET` | `/refresh` | Refresh access token using cookie | ✅ Yes (refresh token) |
|
|
| `GET` | `/me` | Get current logged-in user info | ✅ Yes (access token) |
|
|
| `POST` | `/logout` | Clear cookies and logout | ✅ Yes |
|
|
|
|
---
|
|
|
|
## 🧪 Example `main.go`
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"AccessHandler/handlers"
|
|
"gitea.tecamino.com/paadi/tecamino-logger/logging"
|
|
"github.com/gin-gonic/gin"
|
|
"log"
|
|
)
|
|
|
|
func main() {
|
|
logger, _ := logging.NewLogger("server.log", nil)
|
|
accessHandler, err := handlers.NewAccessHandler("access.db", logger)
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
|
|
r := gin.Default()
|
|
|
|
// Auth routes
|
|
r.POST("/login", accessHandler.Login)
|
|
r.GET("/refresh", accessHandler.Refresh)
|
|
r.GET("/me", accessHandler.Me)
|
|
r.POST("/logout", accessHandler.Logout)
|
|
|
|
logger.Info("Server", "running on http://localhost:8080")
|
|
r.Run(":8080")
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🔍 Example Request
|
|
|
|
**Login**
|
|
```bash
|
|
curl -X POST http://localhost:8080/login -H "Content-Type: application/json" -d '{"user_name": "admin", "password": "1234"}'
|
|
```
|
|
|
|
**Response**
|
|
```json
|
|
{
|
|
"message": "login successful",
|
|
"id": 1,
|
|
"user": "admin",
|
|
"role": "admin",
|
|
"settings": "{}"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🧹 Database
|
|
|
|
SQLite database is automatically created and migrated via:
|
|
|
|
```go
|
|
gorm.Open(sqlite.Open("access.db"), &gorm.Config{})
|
|
```
|
|
|
|
You can easily switch to another database by changing the driver.
|
|
|
|
---
|
|
|
|
## 🪵 Logging
|
|
|
|
All actions are logged through the `tecamino-logger` package for full observability of access and errors.
|
|
|
|
---
|
|
|
|
## 🧰 Future Enhancements
|
|
|
|
- ✅ Environment variable support for secrets
|
|
- ✅ Role-based authorization middleware
|
|
- ✅ Token revocation & blacklist
|
|
- ✅ Unit tests for authentication flow |