authws

PDAccess main authentication service based on OAuth2 with realm-based login.

Technology Stack

• Backend: Go 1.26.1
• Frontend: Vue.js 3 with TypeScript
• Database: PostgreSQL with pgx
• Architecture: Hexagonal (Ports & Adapters)
• Testing: Ginkgo (BDD), standard Go testing
• Auth: OAuth2, LDAP, Username/Password, MFA

Supported Authentication Methods

• Username/Password based
• LDAP based authentication
• OAuth2
• MFA (Multi-Factor Authentication)

Project Structure

cmd/               # Main application entry points
  main.go         # CLI entry
  apps/           # Command implementations (server, init-system, test-client)
  config/         # Configuration handling

internal/
  core/
    domain/       # Entities (User, Realm, Token, Client, MFA, etc.)
    ports/        # Interfaces for services and adapters
    service/      # Business logic (auth, token, client, user, mfa, realm)
  
  handlers/       # External request handlers
    web/          # HTTP handlers
    oauth/        # OAuth2 endpoints
    grpc/         # gRPC handlers
    pb/           # Protobuf generated code
  
  server/         # HTTP/gRPC server setup
  repositories/   # Adapter implementations
    pg/           # PostgreSQL
    auth/         # LDAP, username/password
    session/      # Session store
    token/        # Token management
    pdaws/        # PD AWS integration
    vault/        # Vault integration

ui/               # Vue.js frontend
  src/            # Vue components, views, api

cicd/tests/       # BDD integration tests (ginkgo)

resources/        # OpenAPI specs, proto files

Getting Started

Prerequisites

• Go 1.26.1+
• Docker (for integration tests)
• Node.js (for UI development)

Installation

go mod download
cd ui && npm install

Development

This project uses hexagonal architecture. See Hexagonal Architecture in Go for background.

Commands

Command	Description
make format	Run gofmt, gofix, vet, tidy
make build	Docker build
make unit-tests	Run unit tests with mocks
make cicd-tests	Run integration tests (requires Docker)
make generate	Generate OpenAPI/Proto/TypeScript code
make local	Run server locally
make serve	Run Vue UI dev server
make codecheck	Run security vulnerability scan

Testing

Unit Tests

Run unit tests using mock objects:

make unit-tests

Integration Tests

Run acceptance/CICD tests (creates servers and database in containers):

make cicd-tests

Manual Test

curl -XPOST "https://app.pdaccess.com/oauth/realm/default/protocol/test/authorize?client_id=222222&client_secret=22222222&scope=read&redirect_uri=http://localhost&response_type=code&state=bp67zPXTYWDw5r-W"

Configuration

Server expects config file (default /etc/server.json). Run with --debug and --console flags for development.

Key Files

• cmd/main.go - Entry point with CLI commands
• cmd/apps/server.go - Main server implementation
• internal/core/ports/service.go - Core service interfaces
• internal/handlers/oauth/api_auth.go - OAuth endpoint handlers
• internal/repositories/auth/ - Auth adapters (LDAP, username/password)
• resources/authws-api.yaml - OpenAPI specification

Database

Uses PostgreSQL with schema in internal/repositories/pg/schema.go. Key tables:

• realms, users, clients, tokens, mfa_attempts, sessions, auth_attempts

External Dependencies

• pdaccess/commons - Shared utilities (private)
• pdaccess/pvault - Vault integration (private)
• go-oauth2/oauth2 - OAuth2 implementation
• go-ldap/ldap - LDAP authentication
• jackc/pgx - PostgreSQL driver