Skip to content

Development Mode Setup Guide

Overview

The API server includes a development mode that allows developers to bypass OAuth2-Proxy authentication for local development and testing.

⚠️ SECURITY WARNING: Development mode should ONLY be enabled in local development environments. NEVER enable this in production!

How It Works

In production, the API server expects authentication headers (X-User, X-Roles, X-Email, X-Name) to be set by OAuth2-Proxy. When these headers are missing: - Production mode (default): User is treated as "guest" with limited access - Development mode: User is assigned configurable default credentials with full access

Configuration

Edit config/tlinqapi.properties to enable development mode:

# Enable development mode (NEVER enable in production!)
dev-mode=true

# Configure the default development user
dev-user-id=dev-admin
dev-user-email=developer@localhost
dev-user-name=Development Admin
dev-user-roles=admin,agent

Default Configuration

The following default values are used if not specified:

  • dev-mode: false (disabled by default for safety)
  • dev-user-id: dev-admin
  • dev-user-email: developer@localhost
  • dev-user-name: Development Admin
  • dev-user-roles: admin,agent

Usage

  1. Enable dev-mode in config/tlinqapi.properties: 

    dev-mode=true

  2. Restart the API server

  3. Access APIs without authentication headers:

  4. All API requests without X-User/X-Roles headers will use the configured dev user

  5. The dev user has admin and agent roles, providing full API access

  6. Check logs for security warnings: 

    **********************************************************************
*** SECURITY WARNING: Development mode is ENABLED!
*** Authentication bypass is active!
*** This should NEVER be enabled in production environments!
**********************************************************************

Security Considerations

  • ✅ Development mode is disabled by default
  • ✅ Clear security warnings are logged when enabled
  • ✅ Configuration is explicit and visible in properties file
  • ⚠️ Never commit dev-mode=true to version control for production configs
  • ⚠️ Always disable before deploying to staging or production

Testing

With dev-mode enabled, you can test APIs directly without OAuth2-Proxy:

# Example: Call an API endpoint without authentication headers
curl http://localhost:11080/tlinq-api/customer/search?query=test

# The request will be processed as dev-admin with admin,agent roles

Disabling Dev Mode

To disable development mode:

  1. Set dev-mode=false in config/tlinqapi.properties
  2. Restart the API server
  3. Verify that unauthenticated requests are denied or treated as guest

Troubleshooting

Problem: APIs still deny access even with dev-mode enabled

Solution: Check that: - dev-mode=true is set in the correct properties file - The API server was restarted after changing the configuration - The dev-user-roles include the required roles for the API (see config/api-roles.properties) - Server logs show the dev-mode warning messages

Problem: Production environment accidentally has dev-mode enabled

Solution: 1. Immediately set dev-mode=false 2. Restart the API server 3. Review access logs for unauthorized access 4. Update deployment procedures to prevent this in the future