ngauth

Lightweight OAuth 2.0 & OpenID Connect Server

Perfect for testing and development environments

ngauth is a fast, lightweight OAuth 2.0 authorization server and OpenID Connect provider designed specifically for integration testing, development, and CI/CD pipelines. Perfect for testing OAuth clients, OIDC flows, and JWT authentication without the overhead of production-grade identity providers like Keycloak or Auth0.

Keywords: oauth testing, oauth server, oidc testing, oauth2 testcontainers, oauth integration testing, jwt testing, oauth mock server, oauth development server, openid connect testing, oauth ci cd

🚀 Quick Start

Get ngauth running in seconds with Docker:

# Pull and run the container
docker run -d -p 3000:3000 ngauth/server

# Or use Docker Compose
docker-compose up -d

That's it! Your OAuth 2.0 server is now running at http://localhost:3000

For testing with Testcontainers (recommended for integration tests):

// Node.js example
const { GenericContainer } = require('testcontainers');

const container = await new GenericContainer('ngauth/server')
  .withExposedPorts(3000)
  .start();

const serverUrl = `http://${container.getHost()}:${container.getMappedPort(3000)}`;
// Start testing!

📖 See full Testcontainers guide

💡 Why ngauth?

ngauth is designed specifically for development and testing environments where you need a real OAuth 2.0/OIDC server without the complexity of production-grade solutions.

Key Benefits

✅ Zero Configuration - Works out of the box with sensible defaults
✅ Lightweight - Docker image < 100MB, starts in seconds
✅ Standards Compliant - Implements OAuth 2.0 (RFC 6749) and OpenID Connect Core
✅ Test-Friendly - Built for Testcontainers and automated testing
✅ No External Dependencies - Fully self-contained, no database required
✅ Predictable Data - Pre-seeded with test users and clients
✅ Developer Experience - Simple API, clear documentation, easy debugging

Comparison

Feature	ngauth	Keycloak	WireMock
Purpose	OAuth testing	Production IAM	HTTP mocking
Startup Time	< 3 seconds	30-60 seconds	< 1 second
Memory Usage	~50 MB	~1 GB	~100 MB
Configuration	Zero config	Complex	Manual setup
OAuth 2.0 Support	✅ Full	✅ Full	⚠️ Manual mocks
OIDC Support	✅ Full	✅ Full	⚠️ Manual mocks
Docker Image Size	~80 MB	~600 MB	~150 MB
Testcontainers	✅ Optimized	✅ Slow	❌ Not designed
Learning Curve	Minimal	Steep	Medium
Best For	Testing/Dev	Production	Generic mocking

🎯 Use Cases

Integration Testing

Perfect for testing applications that integrate with OAuth providers:

Verify OAuth flows (authorization code, client credentials, etc.)
Test token validation and JWT verification
Validate error handling and edge cases
No need for external services or API keys

CI/CD Pipelines

Ideal for automated testing in CI environments:

Fast startup times don't slow down builds
Deterministic behavior ensures reliable tests
No external dependencies or rate limits
Works offline once image is cached

Local Development

Great for developing OAuth-integrated applications:

No internet connection required
Consistent test data across team members
Easy debugging with predictable responses
Faster than hitting real OAuth providers

Training & Education

Excellent for learning OAuth 2.0 and OIDC:

See real OAuth flows in action
Experiment without production concerns
Clear, understandable codebase
Standard-compliant implementation

📚 Documentation

Quick Start Guide (OIDC) - Get started with OpenID Connect
OpenID Connect Details - Complete OIDC implementation guide
Testcontainers Usage - Integration testing examples
Branding Guidelines - Logo and visual assets
Sample Applications - Example implementations

🐳 Docker Usage

Pull from Docker Hub

docker pull ngauth/server:latest

Run with Custom Configuration

docker run -d \
  -p 3000:3000 \
  -e NODE_ENV=production \
  -v $(pwd)/data:/app/data \
  ngauth/server

Docker Compose

version: '3.8'
services:
  ngauth:
    image: ngauth/server:latest
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    volumes:
      - ./data:/app/data

🎭 Provider Presets

ngauth can mimic popular OAuth providers for realistic testing! Test your application against different OAuth server behaviors without running the actual services.

Available Presets

# Mimic Auth0
docker run -e NGAUTH_PRESET=auth0 -p 3000:3000 ngauth/server

# Mimic Okta  
docker run -e NGAUTH_PRESET=okta -p 3000:3000 ngauth/server

# Mimic Azure AD B2C
docker run -e NGAUTH_PRESET=azureb2c -p 3000:3000 ngauth/server

# Mimic Microsoft Entra ID
docker run -e NGAUTH_PRESET=entraid -p 3000:3000 ngauth/server

# Mimic Keycloak
docker run -e NGAUTH_PRESET=keycloak -p 3000:3000 ngauth/server

# Mimic Duende IdentityServer
docker run -e NGAUTH_PRESET=identityserver -p 3000:3000 ngauth/server

# Mimic Google Identity Platform
docker run -e NGAUTH_PRESET=google -p 3000:3000 ngauth/server

# Mimic AWS Cognito
docker run -e NGAUTH_PRESET=cognito -p 3000:3000 ngauth/server

What Each Preset Configures

Each preset automatically sets up:

✅ Endpoint paths - Match the exact URLs of the real provider
✅ Claim structure - Use provider-specific claim names and formats
✅ Token lifetimes - Realistic TTL values
✅ Scopes and roles - Provider-specific claim patterns

Preset	Scope Claim	Format	Roles/Groups	Special Features
auth0	`scope`	String	`permissions` array	Namespaced claims
okta	`scp`	Array	`groups` array	No separate roles
azureb2c	`scp`	String	`roles` array	Azure-style GUIDs
entraid	`scp`	String	`roles`/`groups` array	Microsoft identity platform v2.0
keycloak	`scope`	String	`realm_access.roles`	Hierarchical roles
identityserver	`scope`	String	`role` array	Clean claim names
google	`scope`	String	None	Minimal claims
cognito	`scope`	String	`cognito:groups`	AWS-prefixed claims

Example: Test Your App with Multiple Providers

// Test that your app works with different OAuth providers
const providers = ['auth0', 'okta', 'azureb2c', 'keycloak'];

describe.each(providers)('OAuth Provider: %s', (preset) => {
  let container;
  
  beforeAll(async () => {
    container = await new GenericContainer('ngauth/server')
      .withExposedPorts(3000)
      .withEnvironment('NGAUTH_PRESET', preset)
      .start();
  });
  
  it('should authenticate successfully', async () => {
    // Your test code - works with all providers!
  });
});

Fine-Tune with Environment Variables

Override specific settings while using a preset:

# Use Auth0 preset but with custom token TTL
docker run \
  -e NGAUTH_PRESET=auth0 \
  -e NGAUTH_ACCESS_TOKEN_TTL=7200 \
  -p 3000:3000 \
  ngauth/server

Advanced Configuration: See Configuration Reference for all available environment variables.

🧪 Testing with Testcontainers

ngauth is optimized for use with Testcontainers, making it perfect for integration testing in any language.

Supported Languages:

✅ Node.js / JavaScript / TypeScript
✅ Java / Kotlin
✅ Python
✅ Go
✅ .NET / C#

See the Testcontainers Guide for complete examples.

🔧 Features

OAuth 2.0 Support

Authorization Code Flow
Client Credentials Flow
Implicit Flow (legacy support)
Token refresh
Token revocation

OpenID Connect Support

ID Tokens with JWT
UserInfo endpoint
Discovery endpoint (/.well-known/openid-configuration)
JWKS endpoint for public key distribution
Standard claims (sub, email, name, etc.)

Security Features

JWT token signing (RS256)
Token validation
Client authentication
Rate limiting
CSRF protection
Audit logging

Developer Features

Health check endpoint
Pre-seeded test data
Clear error messages
Request/response logging
Configurable token lifetimes

📦 Installation

Option 1: Docker (Recommended)

docker pull ngauth/server:latest
docker run -p 3000:3000 ngauth/server

Option 2: From Source

git clone https://github.com/ngauth/server.git
cd server
npm install
npm start

�️ Configuration

ngauth works with zero configuration but can be customized via environment variables.

Quick Configuration with Presets

Use NGAUTH_PRESET to instantly configure ngauth to match popular OAuth providers:

NGAUTH_PRESET=auth0        # Auth0
NGAUTH_PRESET=okta         # Okta
NGAUTH_PRESET=azureb2c     # Azure AD B2C
NGAUTH_PRESET=keycloak     # Keycloak
NGAUTH_PRESET=identityserver  # Duende IdentityServer
NGAUTH_PRESET=google       # Google
NGAUTH_PRESET=cognito      # AWS Cognito
NGAUTH_PRESET=custom       # Manual configuration (default)

Advanced Environment Variables

Override preset settings or configure manually:

General Settings

PORT=3000                          # Server port
NGAUTH_ISSUER=http://localhost:3000  # OAuth issuer URL
NGAUTH_DATA=/app/data              # Data directory

Endpoint Paths

NGAUTH_AUTHORIZE_PATH=/authorize
NGAUTH_TOKEN_PATH=/token
NGAUTH_JWKS_PATH=/.well-known/jwks.json
NGAUTH_OIDC_PATH=/.well-known/openid-configuration
NGAUTH_USERINFO_PATH=/userinfo
NGAUTH_INTROSPECT_PATH=/introspect
NGAUTH_REVOKE_PATH=/revoke
NGAUTH_LOGOUT_PATH=/logout

Claim Configuration

NGAUTH_SCOPE_CLAIM_NAME=scope      # Claim name for scopes
NGAUTH_SCOPE_FORMAT=string         # "string" or "array"
NGAUTH_ROLES_CLAIM_NAME=roles      # Claim name for roles
NGAUTH_GROUPS_CLAIM_NAME=groups    # Claim name for groups
NGAUTH_PERMISSIONS_CLAIM_NAME=permissions  # Claim name for permissions
NGAUTH_REQUIRE_NAMESPACED_CLAIMS=false     # Auth0-style namespacing
NGAUTH_NAMESPACE_PREFIX=https://myapp.com  # Namespace prefix

Token Settings

NGAUTH_ACCESS_TOKEN_TTL=3600       # Access token lifetime (seconds)
NGAUTH_ID_TOKEN_TTL=3600           # ID token lifetime (seconds)
NGAUTH_REFRESH_TOKEN_TTL=86400     # Refresh token lifetime (seconds)
NGAUTH_TOKEN_SIGNING_ALG=RS256     # Signing algorithm

Feature Flags

NGAUTH_SUPPORT_PKCE=true           # Enable PKCE support
NGAUTH_SUPPORT_REFRESH_TOKENS=true # Enable refresh tokens
NGAUTH_SUPPORT_OFFLINE_ACCESS=true # Enable offline_access scope

Example Configurations

Docker Compose with Auth0 Preset

version: '3.8'
services:
  oauth:
    image: ngauth/server:latest
    ports:
      - "3000:3000"
    environment:
      NGAUTH_PRESET: auth0
      NGAUTH_ACCESS_TOKEN_TTL: 7200

Testcontainers with Keycloak Preset

const container = await new GenericContainer('ngauth/server')
  .withExposedPorts(3000)
  .withEnvironment('NGAUTH_PRESET', 'keycloak')
  .withEnvironment('NGAUTH_ACCESS_TOKEN_TTL', '300')
  .start();

Custom Configuration (No Preset)

docker run \
  -e NGAUTH_PRESET=custom \
  -e NGAUTH_AUTHORIZE_PATH=/custom/authorize \
  -e NGAUTH_TOKEN_PATH=/custom/token \
  -e NGAUTH_SCOPE_CLAIM_NAME=custom_scope \
  -e NGAUTH_SCOPE_FORMAT=array \
  -p 3000:3000 \
  ngauth/server

�🔑 Pre-configured Test Data

ngauth comes with pre-seeded data for immediate testing:

Test Users

Username: testuser / Password: password123
Username: alice / Password: alice123
Username: bob / Password: bob123

Test Clients

Client ID: test-client
Client Secret: test-secret
Redirect URI: http://localhost:3000/callback

🛠️ Configuration

ngauth works with zero configuration but can be customized:

Environment Variables

PORT=3000                    # Server port
NODE_ENV=development         # Environment mode
JWT_EXPIRATION=3600          # Access token lifetime (seconds)
REFRESH_EXPIRATION=86400     # Refresh token lifetime (seconds)

Data Persistence

By default, data is stored in JSON files in /app/data:

users.json - User accounts
clients.json - OAuth clients
codes.json - Authorization codes (temporary)

Mount a volume to persist data:

docker run -v ./my-data:/app/data ngauth/server

📖 API Endpoints

OAuth 2.0 / OIDC Endpoints

Endpoint	Description
`GET /authorize`	Authorization endpoint
`POST /token`	Token endpoint
`GET /userinfo`	UserInfo endpoint (OIDC)
`GET /.well-known/openid-configuration`	OIDC Discovery
`GET /.well-known/jwks.json`	JWKS public keys

Management Endpoints

Endpoint	Description
`GET /health`	Health check
`POST /users`	Create user (testing only)
`POST /register`	Register OAuth client

See full API documentation for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Star History

If you find ngauth useful, please consider giving it a star on GitHub!

📞 Support

Built for developers, by developers 🚀

GitHub • Docker Hub • Testcontainers

Name		Name	Last commit message	Last commit date
Latest commit History 51 Commits
.devcontainer		.devcontainer
.github		.github
docs		docs
src		src
test		test
.dockerignore		.dockerignore
.gitignore		.gitignore
.mailmap		.mailmap
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
SECURITY_AUDIT.md		SECURITY_AUDIT.md
package-lock.json		package-lock.json
package.json		package.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

ngauth

🚀 Quick Start

💡 Why ngauth?

Key Benefits

Comparison

🎯 Use Cases

Integration Testing

CI/CD Pipelines

Local Development

Training & Education

📚 Documentation

🐳 Docker Usage

Pull from Docker Hub

Run with Custom Configuration

Docker Compose

🎭 Provider Presets

Available Presets

What Each Preset Configures

Example: Test Your App with Multiple Providers

Fine-Tune with Environment Variables

🧪 Testing with Testcontainers

🔧 Features

OAuth 2.0 Support

OpenID Connect Support

Security Features

Developer Features

📦 Installation

Option 1: Docker (Recommended)

Option 2: From Source

�️ Configuration

Quick Configuration with Presets

Advanced Environment Variables

General Settings

Endpoint Paths

Claim Configuration

Token Settings

Feature Flags

Example Configurations

Docker Compose with Auth0 Preset

Testcontainers with Keycloak Preset

Custom Configuration (No Preset)

�🔑 Pre-configured Test Data

Test Users

Test Clients

🛠️ Configuration

Environment Variables

Data Persistence

📖 API Endpoints

OAuth 2.0 / OIDC Endpoints

Management Endpoints

🤝 Contributing

📄 License

🌟 Star History

📞 Support

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages