https://github.com/linuxfoundation/lfx-v2-access-check
LFX v2 Platform Access Check
https://github.com/linuxfoundation/lfx-v2-access-check
Last synced: 3 months ago
JSON representation
LFX v2 Platform Access Check
- Host: GitHub
- URL: https://github.com/linuxfoundation/lfx-v2-access-check
- Owner: linuxfoundation
- License: mit
- Created: 2025-07-22T18:50:13.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-02-02T23:32:58.000Z (4 months ago)
- Last Synced: 2026-02-03T12:37:00.376Z (4 months ago)
- Language: Go
- Homepage:
- Size: 151 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# LFX v2 Access Check Service
A access check service for the LFX v2 platform, providing centralized authorization and permission management across LFX services.
## ✨ Key Features
- **🚀 Bulk Access Checks**: Process multiple resource-action permission checks in a single HTTP request
- **🔐 JWT Authentication**: Secure authentication using Heimdall-issued JWT tokens
- **🔄 Real-time Processing**: Asynchronous message processing via NATS queue
- **🚢 Cloud Native**: Kubernetes-ready with Helm charts for easy deployment
## 🏗️ Architecture Overview
```mermaid
graph TB
subgraph "LFX v2 Platform Gateway"
T[Traefik
API Gateway]
H[Heimdall
Access Decision Service]
end
subgraph "Access Check Service"
AC[HTTP Server
:8080]
AS[Access Service
Core Logic]
HE[Health Endpoints
/livez /readyz]
end
subgraph "Platform Infrastructure"
N[NATS
Message Queue]
end
T --> H
H --> AC
AC --> AS
AC --> HE
AS <-->|bulk access checks
access-check subject| N
```
## 🔄 Access Check Flow
```mermaid
sequenceDiagram
participant Client as API Consumer
participant Traefik as Traefik Gateway
participant Heimdall as Heimdall Access Decision
participant AccessCheck as Access Check Service
participant NATS as NATS Queue
Client->>Traefik: POST /access-check
Bearer: JWT + resource list
Traefik->>Heimdall: Validate JWT & authorize
Heimdall-->>Traefik: Auth success
Traefik->>AccessCheck: Forward authenticated request
AccessCheck->>AccessCheck: Extract principal from JWT
AccessCheck->>AccessCheck: Build resource-action pairs
AccessCheck->>NATS: Publish bulk access check
Subject: access-check
NATS-->>AccessCheck: Return authorization results
AccessCheck-->>Traefik: JSON response with decisions
Traefik-->>Client: Access check results
Note over AccessCheck: Optimized for bulk operations
with comprehensive logging
```
## 🚀 Quick Start
### Prerequisites
- **Go**: 1.24.0
- **Docker**: For containerized deployment
- **NATS**: Message queue for service communication
- **Heimdall**: JWT authentication provider
### Local Development
1. **Clone the repository**
```bash
git clone https://github.com/linuxfoundation/lfx-v2-access-check.git
cd lfx-v2-access-check
```
2. **Install dependencies**
```bash
make deps
```
3. **Generate API code** (if needed)
```bash
make apigen
```
4. **Build the service**
```bash
make build
```
5. **Run tests**
```bash
make test
```
6. **Start the service**
```bash
./bin/lfx-access-check
```
### Configuration
The service is configured via environment variables:
| Variable | Description | Default |
|----------|-------------|---------|
| `HOST` | Server host address | `0.0.0.0` |
| `PORT` | Server port | `8080` |
| `DEBUG` | Enable debug logging | `false` |
| `JWKS_URL` | Heimdall JWKS endpoint | `http://heimdall:4457/.well-known/jwks` |
| `AUDIENCE` | JWT audience | `lfx-v2-access-check` |
| `ISSUER` | JWT issuer | `heimdall` |
| `NATS_URL` | NATS server URL | `nats://nats:4222` |
### Docker Deployment
```bash
# Build image
make docker-build
# Run container
docker run -p 8080:8080 \
-e JWKS_URL=http://heimdall:4457/.well-known/jwks \
-e NATS_URL=nats://nats:4222 \
linuxfoundation/lfx-access-check:latest
```
### Health Endpoints
- **Liveness**: `GET /livez` - Basic service health
- **Readiness**: `GET /readyz` - Service + dependencies health
## 🏛️ Architecture Details
### Core Components
1. **HTTP Server** (`cmd/lfx-access-check/`)
- Goa-based REST API server
- JWT authentication middleware
- Request ID tracking
- Structured logging
2. **Access Service** (`internal/service/`)
- Core business logic
- JWT token validation
- NATS message publishing
- Response aggregation
3. **Infrastructure Layer** (`internal/infrastructure/`)
- **Auth Repository**: Heimdall JWT validation
- **Messaging Repository**: NATS communication
- **Config**: Environment-based configuration
4. **Domain Contracts** (`internal/domain/contracts/`)
- Shared data structures
- JWT claims modeling
- Service interfaces
### Project Structure
```
├── cmd/lfx-access-check/ # Application entry point
├── design/ # Goa API design definitions
├── gen/ # Generated API code (Goa)
├── internal/
│ ├── container/ # Dependency injection
│ ├── domain/contracts/ # Domain models & interfaces
│ ├── infrastructure/ # External service adapters
│ ├── middleware/ # HTTP middleware
│ ├── service/ # Core business logic
│ └── mocks/ # Test mocks
├── pkg/
│ ├── constants/ # Application constants
│ └── log/ # Structured logging utilities
├── test/integration/ # Integration tests
└── charts/ # Helm deployment charts
```
## 🚢 Deployment
### Kubernetes with Helm
```bash
# Install/upgrade with Helm
helm upgrade --install lfx-v2-access-check ./charts/lfx-v2-access-check \
--set image.tag=latest \
--set config.jwksUrl=http://heimdall:4457/.well-known/jwks \
--set config.natsUrl=nats://nats:4222
```
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.