BulwarkAuthAdmin

A Go microservice for managing user accounts and authentication. Provides REST API endpoints for account lifecycle operations, social provider management, and role-based access control (RBAC). Built with Echo web framework and MongoDB.

Version: v0.2.0
Go Version: 1.24.0+
Module: github.com/latebit-io/bulwarkauthadmin

Table of Contents

• Installation
• Running the Service
• Environment Variables
• API Documentation
• Architecture
• API Endpoints
• Development
• Testing

Installation

Prerequisites

• Go 1.24.0 or later - Download Go
• MongoDB 4.0+ - For database backend
• Docker (optional) - For containerized MongoDB

Clone the Repository

git clone https://github.com/latebit-io/bulwarkauthadmin.git
cd bulwarkauthadmin

Install Dependencies

go mod download
go mod verify

Build the Binary

go build -o bulwarkauthadmin cmd/bulwarkauthadmin/main.go

Running the Service

Setup MongoDB

Option 1: Using Docker Compose (Recommended for Development)

# Start MongoDB
docker-compose -f docker-compose.test.yml up -d

# Verify MongoDB is running
docker-compose -f docker-compose.test.yml logs mongodb

# Stop MongoDB
docker-compose -f docker-compose.test.yml down

# Remove volumes (clean slate)
docker-compose -f docker-compose.test.yml down -v

Option 2: Using Local MongoDB

Ensure MongoDB is running on localhost:27017 (or configure DB_CONNECTION accordingly).

Configure Environment Variables

Create a .env file in cmd/bulwarkauthadmin/ or set environment variables. See Environment Variables for details.

# Copy the default .env file
cp cmd/bulwarkauthadmin/.env cmd/bulwarkauthadmin/.env.local

# Edit configuration as needed
# nano cmd/bulwarkauthadmin/.env.local

Start the Service

Option 1: Using Go Run (Development)

go run cmd/bulwarkauthadmin/main.go

Option 2: Using the Built Binary

./bulwarkauthadmin

The service will start and output:

⇨ http server started on [::]:8081

By default, the service runs on http://localhost:8081.

Verify the Service

# Health check
curl http://localhost:8081/api/v1/health

Environment Variables

Configure the service behavior using the following environment variables:

Core Configuration

Variable	Type	Default	Description
PORT	int	8081	Server port to listen on
BULWARK_AUTH_URL	string	http://localhost:8080	BulwarkAuth service URL

Database Configuration

Variable	Type	Default	Description
DB_CONNECTION	string	mongodb://localhost:27017/?connect=direct	MongoDB connection string
DB_NAME_SEED	string	`` (empty)	Optional database name suffix (e.g., test creates bulwarkauthtest)

CORS Configuration

Variable	Type	Default	Description
CORS_ENABLED	bool	false	Enable Cross-Origin Resource Sharing
ALLOWED_WEB_ORIGINS	string	http://localhost:5173	Comma-separated list of allowed origins (e.g., http://localhost:5173,https://example.com)

Initial Admin Account Setup

⚠️ SECURITY WARNING: These variables are intended only for initial provisioning. After the first successful startup (once the admin account is created or linked), immediately remove ADMIN_ACCOUNT and ADMIN_ACCOUNT_PASSWORD from the environment and any configuration files or deployment manifests.

Variable	Type	Default	Description
ADMIN_ACCOUNT	string	`` (empty)	Email address for the initial admin account
ADMIN_ACCOUNT_PASSWORD	string	`` (empty)	Password for the initial admin account

Email Templates

Variable	Type	Default	Description
EMAIL_TEMPLATES_DIR	string	`` (empty)	Directory path containing email templates. When empty (the default), templates are loaded from the current working directory. If a custom path is provided, it must include a trailing slash (e.g., /path/to/templates/). In Docker deployments, templates are pre-installed at /app/, so this variable typically does not need to be set.

Example .env File

# Server
PORT=8081
BULWARK_AUTH_URL=http://localhost:8080

# Database
DB_CONNECTION=mongodb://localhost:27017/?connect=direct
DB_NAME_SEED=

# CORS
CORS_ENABLED=false
ALLOWED_WEB_ORIGINS=http://localhost:5173,http://localhost:3000

# Initial Admin (REMOVE AFTER FIRST STARTUP)
ADMIN_ACCOUNT=admin@example.com
ADMIN_ACCOUNT_PASSWORD=SecurePassword123!

# Email Templates
EMAIL_TEMPLATES_DIR=/path/to/email/templates/

Setting Environment Variables

Using .env File

Place a .env file in the working directory when running the service:

go run cmd/bulwarkauthadmin/main.go

Using Shell Environment

export PORT=8080
export DB_CONNECTION=mongodb://mongodb.example.com:27017/?connect=direct
export CORS_ENABLED=true
go run cmd/bulwarkauthadmin/main.go

Using Command Line

PORT=8080 DB_CONNECTION=mongodb://localhost:27017 go run cmd/bulwarkauthadmin/main.go

API Documentation

OpenAPI Specification

The complete REST API is documented in OpenAPI 3.0 format:

• Specification file: openapi.yaml
• Quick start guide: API.md - Common workflows and examples

View the API Spec

Online viewers (copy-paste the spec):

• Swagger UI Editor - Paste contents of openapi.yaml
• ReDoc - Upload openapi.yaml

Local viewers:

• Visual Studio Code with OpenAPI extension
• Postman - Import openapi.yaml
• Insomnia - Import openapi.yaml

API Quick Reference

# Health check (no auth required)
curl http://localhost:8081/api/v1/health

# List tenants (requires system admin token)
curl -H "Authorization: Bearer <token>" \
  http://localhost:8081/api/v1/admin/tenants

# List accounts in tenant (requires tenant admin token)
curl -H "Authorization: Bearer <token>" \
  http://localhost:8081/api/v1/tenant/{tenantId}/accounts

See API.md for detailed workflows and examples.

Architecture

This service follows a layered architecture with clear separation of concerns:

HTTP Layer (api/)
    ↓
Service Layer (internal/*/accounts.go - business logic)
    ↓
Repository Layer (internal/*/mongodb_*_repository.go - data access)
    ↓
MongoDB Database

Important: Shared Database with BulwarkAuth

BulwarkAuthAdmin and BulwarkAuth share the same MongoDB database. This is a critical architectural decision:

• Accounts are stored in the shared database with roles and permissions fields
• JWT tokens issued by BulwarkAuth include roles from the account document in the shared database
• Role assignments made by BulwarkAuthAdmin are immediately reflected in accounts, affecting future JWT issuance
• Current JWTs won't update - only NEW authentications get updated JWTs

Key Design Principles

• Anemic Models: Data structures are separate from business logic
• Service Layer: Business-oriented method names (RegisterAccount, GrantPermissionsToRole)
• Repository Layer: Technical CRUD terms (Create, Read, Update, Delete)
• Natural Keys for RBAC: Roles and Permissions use names as primary keys (immutable)
• Soft Deletes: Accounts use soft delete flag by default

API Endpoints

All routes are under /api/v1/ prefix.

Account Management

Base: /api/v1/tenant/:tenantid/accounts

• POST /accounts - Register new account
• GET /accounts - List accounts (paginated)
• GET /accounts/:id - Get account details
• PUT /accounts/email - Change email
• PUT /accounts/disable - Disable account
• PUT /accounts/enable - Enable account
• PUT /accounts/deactivate - Soft delete account
• PUT /accounts/unlink - Unlink social provider

API Key Management

Base: /api/v1/tenant/:tenantid/accounts/:id/apikeys

• POST /accounts/:id/apikeys - Generate new API key (returns plaintext key once)
• GET /accounts/:id/apikeys - List all API keys for account
• GET /accounts/:id/apikeys/:apiKeyID - Get API key details
• PUT /accounts/:id/apikeys/:apiKeyID/suspend - Suspend API key
• PUT /accounts/:id/apikeys/:apiKeyID/enable - Enable API key
• DELETE /accounts/:id/apikeys/:apiKeyID - Revoke (delete) API key

RBAC Management

Base: /api/v1/tenant/:tenantid/rbac

• POST /roles - Create role
• GET /roles - List roles
• GET /roles/:name - Get role details
• PUT /roles/:name - Update role
• DELETE /roles/:name - Delete role
• POST /permissions - Create permission
• GET /permissions - List permissions
• DELETE /permissions/:name - Delete permission

Tenant Management

Base: /api/v1/admin/tenants (requires system admin role)

• POST /tenants - Create tenant
• GET /tenants - List tenants
• GET /tenants/:id - Get tenant details
• PUT /tenants/:id - Update tenant
• DELETE /tenants/:id - Delete tenant

Health Check

• GET /health - Health check endpoint

Development

Project Structure

api/                          # HTTP handlers and routes
  accounts/                   # Account management endpoints
    apikey/                   # API key management endpoints
  health/                     # Health check endpoint
  problem/                    # RFC 7807 problem details (errors)
  rbac/                       # RBAC endpoints
  tenants/                    # Tenant management endpoints

internal/                     # Business logic and data access
  accounts/                   # Account domain
    apikey/                   # API key domain
  rbac/                       # RBAC domain
  tenants/                    # Tenant domain
  email/                      # Email template management
  shared/                     # Common utilities
  utils/                      # Test utilities
  version/                    # Version info
  middleware/                 # JWT and tenant middleware

cmd/bulwarkauthadmin/         # Application entry point
  main.go                     # Service initialization
  config.go                   # Configuration management
  .env                        # Default environment variables

tests/integration/            # Integration tests

Testing

Unit Tests

Run all unit tests (no external dependencies):

go test -v ./internal/...
go test -v -cover ./internal/...

Integration Tests

Integration tests require MongoDB, BulwarkAuth, and MailHog running. The easiest way is with the provided script:

# Run all integration tests (starts services, runs tests, cleans up)
./run-integration-tests.sh

# Run specific domain tests
go test -v -tags=integration ./tests/integration/accounts
go test -v -tags=integration ./tests/integration/rbac
go test -v -tags=integration ./tests/integration/tenants

# Run specific test
go test -v -tags=integration -run TestAccountHandler_RegisterAccount ./tests/integration/accounts

See tests/integration/README.md for manual setup and troubleshooting.

Linting

golangci-lint run

Build and Release

Build Binary

go build -o bulwarkauthadmin cmd/bulwarkauthadmin/main.go

Build with GoReleaser

Requires Docker:

goreleaser release --snapshot --clean

Contributing

See the project's CLAUDE.md for architectural guidelines and coding conventions.

License

Proprietary - Bulwark Auth Admin