SANDCASTLE-AUTH: Authentication for Testing and education.

Introduction

Sandcastle Auth is an authentication server designed for testing, debugging, and educational purposes. It provides a Spring Boot-based JWT authentication solution that allows developers to experiment with, learn about, and test authentication flows in a controlled environment. This project is explicitly not intended for production use but instead offers a transparent sandbox for understanding JWT concepts and testing authentication implementations.

The project is dual-licensed under both the Apache License 2.0 and the MIT License, giving users the flexibility to choose whichever license better suits their needs.

See my github for full source https://github.com/robdeas/sandcastle-auth

Origin and Purpose

Sandcastle Auth originated as a practical testing tool to address a specific challenge: debugging authentication issues in complex containerized environments. When working with multiple containers in Kubernetes deployments, tracing authentication flows and diagnosing JWT-related problems can be particularly difficult.

During the initial design phase, it became apparent that the same qualities that made it valuable for testing—transparency, configurability, and simplicity—also made it an excellent educational resource. This led to a dual focus on both testing and educational aspects.

Primary Use Cases

1. Testing Authentication Flows
   • Integration testing of microservices with JWT authentication
   • Debugging authentication issues in containerized environments
   • Validating token handling in client applications
   • Simulating various token states (valid, expired, revoked)
2. Educational Tool
   • Learning JWT concepts and implementation details
   • Teaching authentication and authorization principles
   • Demonstrating token-based security patterns
   • Understanding the security implications of different JWT configurations
3. System Testing
   • Debugging authentication issues in Kubernetes environments
   • Validating API security implementations
   • Testing client-side token handling

Features

Core Functionality

• Basic username/password authentication
• Domain-based user segregation
• Simple role-based access control
• JWT token generation & validation
• H2 in-memory database support (for quick demos)
• Extensive logging for visibility into authentication flows

Testing-Focused Features

• Lightweight service that can be deployed alongside application containers
• Configurable token properties for testing different scenarios
• Simple API for token issuance and validation
• Easy integration with testing frameworks
• Support for test automation in CI/CD pipelines

Educational Features

• Transparent JWT creation and validation
• Detailed logging of each authentication step
• Clear code structure prioritizing readability
• Simplified model for understanding token-based authentication
• Well-documented design decisions and trade-offs

Planned Enhancements

• Configurable token expiration for different domains, roles, and users
• Token revocation capabilities at multiple levels (user, role, domain)
• Database flexibility with both local H2 and remote PostgreSQL options
• Role synchronization from central repositories

Installation

1. Clone the Repository: bash Copy git clone https://github.com/robdeas/sandcastle-auth.git cd sandcastle-auth
2. Build the Project: bash Copy ./gradlew build
3. Check the Config Directory:
   • config/ folder should contain jwt-key.txt (the secret key file)
   • application.properties or application.yml for basic settings

Configuration

application.properties Highlights

properties
Copy
# Server port configuration
server.port=8080

# Path to your base64-encoded secret key
jwt.key.file=config/jwt-key.txt

# JWT validity in seconds
jwt.token.validity=86400  # 1 day

# Enable/disable H2 console for database inspection
spring.h2.console.enabled=true

Domain & Role Configuration

yaml
Copy
security:
  domains:
    - name: "example.com"
      displayName: "Example Domain"
  roles:
    - name: "ADMIN"
      domain: "example.com"
    - name: "USER"
      domain: "example.com"
  users:
    - username: "testuser"
      password: "testpass"
      domain: "example.com"
      roles: ["USER"]

Running the Server

bash
Copy
java -jar build/libs/sandcastle-auth-1.0.0.jar

Verifying Start-Up

• Logs should show messages about domain creation, user creation, role assignment, etc.
• If H2 console is enabled, you can access it at http://localhost:8080/h2-console
  • Default JDBC URL: jdbc:h2:mem:testdb

API Endpoints

Authentication

POST /authenticate

• Purpose: Validates user credentials, issues a JWT token
• Request Body: json Copy { "username": "testuser", "password": "testpass", "domain": "example.com" }
• Success Response (200 OK): json Copy { "token": "eyJhbGciOi..." }
• Error Response: 401 Unauthorized if credentials fail

Validation

GET /api/isUserValid

• Purpose: Checks if the current user’s JWT is valid
• Headers: Authorization: Bearer <jwt-token>
• Success Response: json Copy { "isValid": true, "username": "testuser", "message": "User is authenticated and valid.", "version": "1", "usernameFromToken": "testuser", "domain": "example.com", "role1": "ADMIN" }

GET /api/isLocalAdmin

• Purpose: Tests if the user is a local authentication domain admin
• Headers: Authorization: Bearer <jwt-token>
• Responses:
  • 200 OK if user is an admin in the specified domain
  • 403 Forbidden or 401 Unauthorized otherwise

Additional Endpoints

Depending on your configuration, you might also have:

• /api/admin/** for admin-only routes
• /api/rest/users/**, /api/rest/roles/**, and so on

Using Sandcastle Auth for Testing

Testing Scenarios

1. Authentication Flow Testing
   • Verify credentials validation
   • Test token issuance with different parameters
   • Validate error handling for invalid credentials
2. Token Validation Testing
   • Verify that valid tokens are accepted
   • Confirm that expired tokens are rejected
   • Test handling of tokens with incorrect signatures
3. Authorization Testing
   • Test role-based access control
   • Verify domain-based restrictions
   • Validate proper handling of insufficient permissions
4. JWT Lifecycle Testing
   • Test token expiration handling
   • Verify token renewal processes
   • Validate token revocation mechanisms

Testing with cURL

Authenticate and get a token:

bash
Copy
curl -X POST -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"testpass","domain":"example.com"}' \
  http://localhost:8080/authenticate

Use the token:

bash
Copy
TOKEN=<paste JWT here>
curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/isUserValid

Integration with Testing Frameworks

Example with REST Assured:

java
Copy
@Test
public void testSecuredEndpoint() {
    // Get token from Sandcastle Auth
    String token = RestAssured.given()
        .contentType("application/json")
        .body("{\"username\":\"testuser\",\"password\":\"password123\",\"domain\":\"test-domain\"}")
        .when()
        .post("http://localhost:18081/authenticate")
        .then()
        .extract()
        .path("token");
    
    // Use token to access secured endpoint
    RestAssured.given()
        .header("Authorization", "Bearer " + token)
        .when()
        .get("/api/secured-resource")
        .then()
        .statusCode(200);
}

Testing in Containerized Environments

Sandcastle Auth can be deployed as a container alongside your application services:

yaml
Copy
# Docker Compose example
services:
  auth-service:
    image: sandcastle-auth:latest
    ports:
      - "18081:8080"
    volumes:
      - ./config:/app/config
    
  app-service:
    image: your-application:latest
    environment:
      - AUTH_SERVICE_URL=http://auth-service:8080
    depends_on:
      - auth-service

Educational Use of Sandcastle Auth

Learning Path

1. Basic JWT Flow
   • Understand token issuance and validation
   • Explore the structure of JWT tokens
   • Learn about token-based authentication principles
2. Token Inspection
   • Decode and inspect JWT contents
   • Understand the purpose of different claims
   • Learn about token security features
3. Token Validation
   • Explore the validation process
   • Understand security implications of proper validation
   • Learn about common validation pitfalls
4. Authorization Models
   • Learn how claims can be used for authorization
   • Understand role-based access control
   • Explore domain-based segregation
5. Token Lifecycle Management
   • Learn about token expiration
   • Understand token renewal strategies
   • Explore token revocation mechanisms

Educational Features

1. Transparent Implementation
   • Clear, readable code that explains JWT concepts
   • Well-documented classes and methods
   • Simple architecture that’s easy to understand
2. Extensive Logging
   • Detailed logs that explain each step of the authentication process
   • Clear error messages that indicate what went wrong
   • Information about token creation, validation, and usage
3. Debuggable Design
   • Run in debug mode to step through the authentication flow
   • Set breakpoints to examine token creation and validation
   • Inspect data structures at each step

Educational Resources

(Links to relevant articles, courses, or documentation about JWT concepts)

Technical Design Decisions

Sandcastle Auth deliberately makes certain design choices that prioritize learning and testing over production readiness. These decisions create an ideal environment for education and testing but would need to be reconsidered for production use.

Authentication Mechanisms

Symmetric Key Encryption (HS512)

• Value for Testing/Education: Simple to set up and inspect; allows easy token validation using tools like jwt.io
• Production Concern: Requires the same secret to be shared between authentication and resource servers, creating a single point of compromise
• Better Practice: Use asymmetric keys (RS256, ES256) where auth servers sign with private keys and resource servers verify with public keys

PIN-Based Password Augmentation

• Value for Testing/Education: Avoids hardcoded passwords while still providing a simple, predictable pattern
• Production Concern: Predictable pattern makes it vulnerable to attack; same PIN is even allowed shared across a domain, or fixed in the initial config file.
• Better Practice: Use strong, unique passwords with proper hashing (bcrypt, Argon2) and salting

Visible Credentials

• Value for Testing/Education: PINs are logged or visible in debug mode to help understand authentication flow
• Production Concern: Credentials should never be logged or visible in any environment
• Better Practice: Log only authentication attempts and results, never the credentials themselves

Token Management

Simple Token Structure

• Value for Testing/Education: Straightforward claims make token content easy to understand
• Production Concern: May lack necessary security claims (nbf, jti) and audience validation
• Better Practice: Include comprehensive claims and validation checks

File-Based Secret Storage

• Value for Testing/Education: Easy to inspect and modify for learning purposes
• Production Concern: Insecure storage of sensitive cryptographic material
• Better Practice: Use secure key vaults, HSMs, or secret management services

System Design

Simplified Architecture

• Value for Testing/Education: Single-component design makes it easy to follow authentication flow
• Production Concern: Lacks separation of concerns and proper security boundaries
• Better Practice: Implement proper separation between authentication, authorization, and resource servers

In-Memory Storage

• Value for Testing/Education: Simplifies setup and makes state changes visible
• Production Concern: No persistence, poor scaling, vulnerable to memory attacks
• Better Practice: Use secure, dedicated databases with proper data protection

How Sandcastle Auth Fills a Gap

Sandcastle Auth addresses a gap in the ecosystem of authentication tools:

1. Full-featured authentication servers (like Keycloak, Auth0) are:
   • Comprehensive but complex to set up
   • Rich in features but lacking in transparency
   • Optimized for security rather than learning
2. Simple JWT libraries provide:
   • Basic token operations but little visibility
   • No integrated testing capabilities
   • Limited educational value
3. Educational examples often:
   • Lack practical testing utility
   • Oversimplify important concepts
   • Don’t integrate with real applications

Sandcastle Auth bridges these gaps by providing a tool that is:

• Lightweight enough for testing
• Transparent enough for learning
• Practical enough for real debugging scenarios
• Flexible enough for various authentication needs

Limitations & Disclaimers

• Not Production-Ready:
  • Minimal validation and security checks
  • No robust scaling or high availability features
  • Simplified security model for clarity
• No Hierarchical Roles:
  • Roles are simple flags; no nested structures
• Limited Security Controls:
  • Minimal protection against brute force attacks
  • Basic validation rules focused on education
  • Limited token security features

For production systems, consider established authentication services like Keycloak, Auth0, or Okta, which have addressed these concerns through years of security-focused development.

FAQ

1. Q: Can I integrate this with my production system?
   A: It’s only meant for demos and testing, please do not rely on it for production security. Even the name is a clue, a sandcastle isn’t a fortress.
2. Q: Where is the user data stored?
   A: By default, in an H2 in-memory DB. You can switch to other DB engines with standard Spring configurations.
3. Q: How do I add more roles/domains/users?
   A: Configure them in application.yml or application.properties, or via an external config file. The server initializes them at startup and they can then be temporaraly modified by the spring rest API.
4. Q: Why am I getting a 401 with my token?
   A: Check if the token is expired, or if you used the correct Bearer scheme in the Authorization header.

Contributing

Contributions that enhance the educational value and testing capabilities of Sandcastle Auth are welcome. Please consider:

• Adding clear comments that explain the “why” behind implementation choices
• Enhancing logging to make the authentication flow more visible
• Creating additional examples that demonstrate specific JWT concepts
• Expanding documentation with learning resources
• Adding new testing utilities and scenarios

Sandcastle Auth

Introduction

Sandcastle Auth is an authentication server designed for testing, debugging, and educational purposes. It provides a Spring Boot-based JWT authentication solution that allows developers to experiment with, learn about, and test authentication flows in a controlled environment. This project is explicitly not intended for production use but instead offers a transparent sandbox for understanding JWT concepts and testing authentication implementations.

The project is dual-licensed under both the Apache License 2.0 and the MIT License, giving users the flexibility to choose whichever license better suits their needs.

Origin and Purpose

Sandcastle Auth originated as a practical testing tool to address a specific challenge: debugging authentication issues in complex containerized environments. When working with multiple containers in Kubernetes deployments, tracing authentication flows and diagnosing JWT-related problems can be particularly difficult.

During the initial design phase, it became apparent that the same qualities that made it valuable for testing—transparency, configurability, and simplicity—also made it an excellent educational resource. This led to a dual focus on both testing and educational aspects.

Primary Use Cases

1. Testing Authentication Flows
   • Integration testing of microservices with JWT authentication
   • Debugging authentication issues in containerized environments
   • Validating token handling in client applications
   • Simulating various token states (valid, expired, revoked)
2. Educational Tool
   • Learning JWT concepts and implementation details
   • Teaching authentication and authorization principles
   • Demonstrating token-based security patterns
   • Understanding the security implications of different JWT configurations
3. System Testing
   • Debugging authentication issues in Kubernetes environments
   • Validating API security implementations
   • Testing client-side token handling

Features

Core Functionality

• Basic username/password authentication
• Domain-based user segregation
• Simple role-based access control
• JWT token generation & validation
• H2 in-memory database support (for quick demos)
• Extensive logging for visibility into authentication flows

Testing-Focused Features

• Lightweight service that can be deployed alongside application containers
• Configurable token properties for testing different scenarios
• Simple API for token issuance and validation
• Easy integration with testing frameworks
• Support for test automation in CI/CD pipelines

Educational Features

• Transparent JWT creation and validation
• Detailed logging of each authentication step
• Clear code structure prioritizing readability
• Simplified model for understanding token-based authentication
• Well-documented design decisions and trade-offs

Planned Enhancements

• Configurable token expiration for different domains, roles, and users
• Token revocation capabilities at multiple levels (user, role, domain)
• Database flexibility with both local H2 and remote PostgreSQL options
• Role synchronization from central repositories

Installation

1. Clone the Repository: bash Copy git clone https://github.com/robdeas/sandcastle-auth.git cd sandcastle-auth
2. Build the Project: bash Copy ./gradlew build
3. Check the Config Directory:
   • config/ folder should contain jwt-key.txt (the secret key file)
   • application.properties or application.yml for basic settings

Configuration

application.properties Highlights

properties
Copy
# Server port configuration
server.port=8080

# Path to your base64-encoded secret key
jwt.key.file=config/jwt-key.txt

# JWT validity in seconds
jwt.token.validity=86400  # 1 day

# Enable/disable H2 console for database inspection
spring.h2.console.enabled=true

Domain & Role Configuration

yaml
Copy
security:
  domains:
    - name: "example.com"
      displayName: "Example Domain"
  roles:
    - name: "ADMIN"
      domain: "example.com"
    - name: "USER"
      domain: "example.com"
  users:
    - username: "testuser"
      password: "testpass"
      domain: "example.com"
      roles: ["USER"]

Running the Server

bash
Copy
java -jar build/libs/sandcastle-auth-1.0.0.jar

Verifying Start-Up

• Logs should show messages about domain creation, user creation, role assignment, etc.
• If H2 console is enabled, you can access it at http://localhost:8080/h2-console
  • Default JDBC URL: jdbc:h2:mem:testdb

API Endpoints

Authentication

POST /authenticate

• Purpose: Validates user credentials, issues a JWT token
• Request Body: json Copy { "username": "testuser", "password": "testpass", "domain": "example.com" }
• Success Response (200 OK): json Copy { "token": "eyJhbGciOi..." }
• Error Response: 401 Unauthorized if credentials fail

Validation

GET /api/isUserValid

• Purpose: Checks if the current user’s JWT is valid
• Headers: Authorization: Bearer <jwt-token>
• Success Response: json Copy { "isValid": true, "username": "testuser", "message": "User is authenticated and valid.", "version": "1", "usernameFromToken": "testuser", "domain": "example.com", "role1": "ADMIN" }

GET /api/isLocalAdmin

• Purpose: Tests if the user is a local authentication domain admin
• Headers: Authorization: Bearer <jwt-token>
• Responses:
  • 200 OK if user is an admin in the specified domain
  • 403 Forbidden or 401 Unauthorized otherwise

Additional Endpoints

Depending on your configuration, you might also have:

• /api/admin/** for admin-only routes
• /api/rest/users/**, /api/rest/roles/**, and so on

Using Sandcastle Auth for Testing

Testing Scenarios

1. Authentication Flow Testing
   • Verify credentials validation
   • Test token issuance with different parameters
   • Validate error handling for invalid credentials
2. Token Validation Testing
   • Verify that valid tokens are accepted
   • Confirm that expired tokens are rejected
   • Test handling of tokens with incorrect signatures
3. Authorization Testing
   • Test role-based access control
   • Verify domain-based restrictions
   • Validate proper handling of insufficient permissions
4. JWT Lifecycle Testing
   • Test token expiration handling
   • Verify token renewal processes
   • Validate token revocation mechanisms

Testing with cURL

Authenticate and get a token:

bash
Copy
curl -X POST -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"testpass","domain":"example.com"}' \
  http://localhost:8080/authenticate

Use the token:

bash
Copy
TOKEN=<paste JWT here>
curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/isUserValid

Integration with Testing Frameworks

Example with REST Assured:

java
Copy
@Test
public void testSecuredEndpoint() {
    // Get token from Sandcastle Auth
    String token = RestAssured.given()
        .contentType("application/json")
        .body("{\"username\":\"testuser\",\"password\":\"password123\",\"domain\":\"test-domain\"}")
        .when()
        .post("http://localhost:18081/authenticate")
        .then()
        .extract()
        .path("token");
    
    // Use token to access secured endpoint
    RestAssured.given()
        .header("Authorization", "Bearer " + token)
        .when()
        .get("/api/secured-resource")
        .then()
        .statusCode(200);
}

Testing in Containerized Environments

Sandcastle Auth can be deployed as a container alongside your application services:

yaml
Copy
# Docker Compose example
services:
  auth-service:
    image: sandcastle-auth:latest
    ports:
      - "18081:8080"
    volumes:
      - ./config:/app/config
    
  app-service:
    image: your-application:latest
    environment:
      - AUTH_SERVICE_URL=http://auth-service:8080
    depends_on:
      - auth-service

Educational Use of Sandcastle Auth

Learning Path

1. Basic JWT Flow
   • Understand token issuance and validation
   • Explore the structure of JWT tokens
   • Learn about token-based authentication principles
2. Token Inspection
   • Decode and inspect JWT contents
   • Understand the purpose of different claims
   • Learn about token security features
3. Token Validation
   • Explore the validation process
   • Understand security implications of proper validation
   • Learn about common validation pitfalls
4. Authorization Models
   • Learn how claims can be used for authorization
   • Understand role-based access control
   • Explore domain-based segregation
5. Token Lifecycle Management
   • Learn about token expiration
   • Understand token renewal strategies
   • Explore token revocation mechanisms

Educational Features

1. Transparent Implementation
   • Clear, readable code that explains JWT concepts
   • Well-documented classes and methods
   • Simple architecture that’s easy to understand
2. Extensive Logging
   • Detailed logs that explain each step of the authentication process
   • Clear error messages that indicate what went wrong
   • Information about token creation, validation, and usage
3. Debuggable Design
   • Run in debug mode to step through the authentication flow
   • Set breakpoints to examine token creation and validation
   • Inspect data structures at each step

Educational Resources

(Links to relevant articles, courses, or documentation about JWT concepts)

Technical Design Decisions

Sandcastle Auth deliberately makes certain design choices that prioritize learning and testing over production readiness. These decisions create an ideal environment for education and testing but would need to be reconsidered for production use.

Authentication Mechanisms

Symmetric Key Encryption (HS512)

• Value for Testing/Education: Simple to set up and inspect; allows easy token validation using tools like jwt.io
• Production Concern: Requires the same secret to be shared between authentication and resource servers, creating a single point of compromise
• Better Practice: Use asymmetric keys (RS256, ES256) where auth servers sign with private keys and resource servers verify with public keys

PIN-Based Password Augmentation

• Value for Testing/Education: Avoids hardcoded passwords while still providing a simple, predictable pattern
• Production Concern: Predictable pattern makes it vulnerable to attack; same PIN is even allowed shared across a domain, or fixed in the initial config file.
• Better Practice: Use strong, unique passwords with proper hashing (bcrypt, Argon2) and salting

Visible Credentials

• Value for Testing/Education: PINs are logged or visible in debug mode to help understand authentication flow
• Production Concern: Credentials should never be logged or visible in any environment
• Better Practice: Log only authentication attempts and results, never the credentials themselves

Token Management

Simple Token Structure

• Value for Testing/Education: Straightforward claims make token content easy to understand
• Production Concern: May lack necessary security claims (nbf, jti) and audience validation
• Better Practice: Include comprehensive claims and validation checks

File-Based Secret Storage

• Value for Testing/Education: Easy to inspect and modify for learning purposes
• Production Concern: Insecure storage of sensitive cryptographic material
• Better Practice: Use secure key vaults, HSMs, or secret management services

System Design

Simplified Architecture

• Value for Testing/Education: Single-component design makes it easy to follow authentication flow
• Production Concern: Lacks separation of concerns and proper security boundaries
• Better Practice: Implement proper separation between authentication, authorization, and resource servers

In-Memory Storage

• Value for Testing/Education: Simplifies setup and makes state changes visible
• Production Concern: No persistence, poor scaling, vulnerable to memory attacks
• Better Practice: Use secure, dedicated databases with proper data protection

How Sandcastle Auth Fills a Gap

Sandcastle Auth addresses a gap in the ecosystem of authentication tools:

1. Full-featured authentication servers (like Keycloak, Auth0) are:
   • Comprehensive but complex to set up
   • Rich in features but lacking in transparency
   • Optimized for security rather than learning
2. Simple JWT libraries provide:
   • Basic token operations but little visibility
   • No integrated testing capabilities
   • Limited educational value
3. Educational examples often:
   • Lack practical testing utility
   • Oversimplify important concepts
   • Don’t integrate with real applications

Sandcastle Auth bridges these gaps by providing a tool that is:

• Lightweight enough for testing
• Transparent enough for learning
• Practical enough for real debugging scenarios
• Flexible enough for various authentication needs

Limitations & Disclaimers

• Not Production-Ready:
  • Minimal validation and security checks
  • No robust scaling or high availability features
  • Simplified security model for clarity
• No Hierarchical Roles:
  • Roles are simple flags; no nested structures
• Limited Security Controls:
  • Minimal protection against brute force attacks
  • Basic validation rules focused on education
  • Limited token security features

For production systems, consider established authentication services like Keycloak, Auth0, or Okta, which have addressed these concerns through years of security-focused development.

FAQ

1. Q: Can I integrate this with my production system?
   A: It’s only meant for demos and testing, please do not rely on it for production security. Even the name is a clue, a sandcastle isn’t a fortress.
2. Q: Where is the user data stored?
   A: By default, in an H2 in-memory DB. You can switch to other DB engines with standard Spring configurations.
3. Q: How do I add more roles/domains/users?
   A: Configure them in application.yml or application.properties, or via an external config file. The server initializes them at startup and they can then be temporaraly modified by the spring rest API.
4. Q: Why am I getting a 401 with my token?
   A: Check if the token is expired, or if you used the correct Bearer scheme in the Authorization header.

Contributing

Contributions that enhance the educational value and testing capabilities of Sandcastle Auth are welcome. Please consider:

• Adding clear comments that explain the “why” behind implementation choices
• Enhancing logging to make the authentication flow more visible
• Creating additional examples that demonstrate specific JWT concepts
• Expanding documentation with learning resources
• Adding new testing utilities and scenarios

Sandcastle Auth

Introduction

Sandcastle Auth is an authentication server designed for testing, debugging, and educational purposes. It provides a Spring Boot-based JWT authentication solution that allows developers to experiment with, learn about, and test authentication flows in a controlled environment. This project is explicitly not intended for production use but instead offers a transparent sandbox for understanding JWT concepts and testing authentication implementations.

The project is dual-licensed under both the Apache License 2.0 and the MIT License, giving users the flexibility to choose whichever license better suits their needs.

Origin and Purpose

Sandcastle Auth originated as a practical testing tool to address a specific challenge: debugging authentication issues in complex containerized environments. When working with multiple containers in Kubernetes deployments, tracing authentication flows and diagnosing JWT-related problems can be particularly difficult.

During the initial design phase, it became apparent that the same qualities that made it valuable for testing—transparency, configurability, and simplicity—also made it an excellent educational resource. This led to a dual focus on both testing and educational aspects.

Primary Use Cases

1. Testing Authentication Flows
   • Integration testing of microservices with JWT authentication
   • Debugging authentication issues in containerized environments
   • Validating token handling in client applications
   • Simulating various token states (valid, expired, revoked)
2. Educational Tool
   • Learning JWT concepts and implementation details
   • Teaching authentication and authorization principles
   • Demonstrating token-based security patterns
   • Understanding the security implications of different JWT configurations
3. System Testing
   • Debugging authentication issues in Kubernetes environments
   • Validating API security implementations
   • Testing client-side token handling

Features

Core Functionality

• Basic username/password authentication
• Domain-based user segregation
• Simple role-based access control
• JWT token generation & validation
• H2 in-memory database support (for quick demos)
• Extensive logging for visibility into authentication flows

Testing-Focused Features

• Lightweight service that can be deployed alongside application containers
• Configurable token properties for testing different scenarios
• Simple API for token issuance and validation
• Easy integration with testing frameworks
• Support for test automation in CI/CD pipelines

Educational Features

• Transparent JWT creation and validation
• Detailed logging of each authentication step
• Clear code structure prioritizing readability
• Simplified model for understanding token-based authentication
• Well-documented design decisions and trade-offs

Planned Enhancements

• Configurable token expiration for different domains, roles, and users
• Token revocation capabilities at multiple levels (user, role, domain)
• Database flexibility with both local H2 and remote PostgreSQL options
• Role synchronization from central repositories

Installation

1. Clone the Repository: bash Copy git clone https://github.com/robdeas/sandcastle-auth.git cd sandcastle-auth
2. Build the Project: bash Copy ./gradlew build
3. Check the Config Directory:
   • config/ folder should contain jwt-key.txt (the secret key file)
   • application.properties or application.yml for basic settings

Configuration

application.properties Highlights

properties
Copy
# Server port configuration
server.port=8080

# Path to your base64-encoded secret key
jwt.key.file=config/jwt-key.txt

# JWT validity in seconds
jwt.token.validity=86400  # 1 day

# Enable/disable H2 console for database inspection
spring.h2.console.enabled=true

Domain & Role Configuration

yaml
Copy
security:
  domains:
    - name: "example.com"
      displayName: "Example Domain"
  roles:
    - name: "ADMIN"
      domain: "example.com"
    - name: "USER"
      domain: "example.com"
  users:
    - username: "testuser"
      password: "testpass"
      domain: "example.com"
      roles: ["USER"]

Running the Server

bash
Copy
java -jar build/libs/sandcastle-auth-1.0.0.jar

Verifying Start-Up

• Logs should show messages about domain creation, user creation, role assignment, etc.
• If H2 console is enabled, you can access it at http://localhost:8080/h2-console
  • Default JDBC URL: jdbc:h2:mem:testdb

API Endpoints

Authentication

POST /authenticate

• Purpose: Validates user credentials, issues a JWT token
• Request Body: json Copy { "username": "testuser", "password": "testpass", "domain": "example.com" }
• Success Response (200 OK): json Copy { "token": "eyJhbGciOi..." }
• Error Response: 401 Unauthorized if credentials fail

Validation

GET /api/isUserValid

• Purpose: Checks if the current user’s JWT is valid
• Headers: Authorization: Bearer <jwt-token>
• Success Response: json Copy { "isValid": true, "username": "testuser", "message": "User is authenticated and valid.", "version": "1", "usernameFromToken": "testuser", "domain": "example.com", "role1": "ADMIN" }

GET /api/isLocalAdmin

• Purpose: Tests if the user is a local authentication domain admin
• Headers: Authorization: Bearer <jwt-token>
• Responses:
  • 200 OK if user is an admin in the specified domain
  • 403 Forbidden or 401 Unauthorized otherwise

Additional Endpoints

Depending on your configuration, you might also have:

• /api/admin/** for admin-only routes
• /api/rest/users/**, /api/rest/roles/**, and so on

Using Sandcastle Auth for Testing

Testing Scenarios

1. Authentication Flow Testing
   • Verify credentials validation
   • Test token issuance with different parameters
   • Validate error handling for invalid credentials
2. Token Validation Testing
   • Verify that valid tokens are accepted
   • Confirm that expired tokens are rejected
   • Test handling of tokens with incorrect signatures
3. Authorization Testing
   • Test role-based access control
   • Verify domain-based restrictions
   • Validate proper handling of insufficient permissions
4. JWT Lifecycle Testing
   • Test token expiration handling
   • Verify token renewal processes
   • Validate token revocation mechanisms

Testing with cURL

Authenticate and get a token:

bash
Copy
curl -X POST -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"testpass","domain":"example.com"}' \
  http://localhost:8080/authenticate

Use the token:

bash
Copy
TOKEN=<paste JWT here>
curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/isUserValid

Integration with Testing Frameworks

Example with REST Assured:

java
Copy
@Test
public void testSecuredEndpoint() {
    // Get token from Sandcastle Auth
    String token = RestAssured.given()
        .contentType("application/json")
        .body("{\"username\":\"testuser\",\"password\":\"password123\",\"domain\":\"test-domain\"}")
        .when()
        .post("http://localhost:18081/authenticate")
        .then()
        .extract()
        .path("token");
    
    // Use token to access secured endpoint
    RestAssured.given()
        .header("Authorization", "Bearer " + token)
        .when()
        .get("/api/secured-resource")
        .then()
        .statusCode(200);
}

Testing in Containerized Environments

Sandcastle Auth can be deployed as a container alongside your application services:

yaml
Copy
# Docker Compose example
services:
  auth-service:
    image: sandcastle-auth:latest
    ports:
      - "18081:8080"
    volumes:
      - ./config:/app/config
    
  app-service:
    image: your-application:latest
    environment:
      - AUTH_SERVICE_URL=http://auth-service:8080
    depends_on:
      - auth-service

Educational Use of Sandcastle Auth

Learning Path

1. Basic JWT Flow
   • Understand token issuance and validation
   • Explore the structure of JWT tokens
   • Learn about token-based authentication principles
2. Token Inspection
   • Decode and inspect JWT contents
   • Understand the purpose of different claims
   • Learn about token security features
3. Token Validation
   • Explore the validation process
   • Understand security implications of proper validation
   • Learn about common validation pitfalls
4. Authorization Models
   • Learn how claims can be used for authorization
   • Understand role-based access control
   • Explore domain-based segregation
5. Token Lifecycle Management
   • Learn about token expiration
   • Understand token renewal strategies
   • Explore token revocation mechanisms

Educational Features

1. Transparent Implementation
   • Clear, readable code that explains JWT concepts
   • Well-documented classes and methods
   • Simple architecture that’s easy to understand
2. Extensive Logging
   • Detailed logs that explain each step of the authentication process
   • Clear error messages that indicate what went wrong
   • Information about token creation, validation, and usage
3. Debuggable Design
   • Run in debug mode to step through the authentication flow
   • Set breakpoints to examine token creation and validation
   • Inspect data structures at each step

Educational Resources

(Links to relevant articles, courses, or documentation about JWT concepts)

Technical Design Decisions

Sandcastle Auth deliberately makes certain design choices that prioritize learning and testing over production readiness. These decisions create an ideal environment for education and testing but would need to be reconsidered for production use.

Authentication Mechanisms

Symmetric Key Encryption (HS512)

• Value for Testing/Education: Simple to set up and inspect; allows easy token validation using tools like jwt.io
• Production Concern: Requires the same secret to be shared between authentication and resource servers, creating a single point of compromise
• Better Practice: Use asymmetric keys (RS256, ES256) where auth servers sign with private keys and resource servers verify with public keys

PIN-Based Password Augmentation

• Value for Testing/Education: Avoids hardcoded passwords while still providing a simple, predictable pattern
• Production Concern: Predictable pattern makes it vulnerable to attack; same PIN is even allowed shared across a domain, or fixed in the initial config file.
• Better Practice: Use strong, unique passwords with proper hashing (bcrypt, Argon2) and salting

Visible Credentials

• Value for Testing/Education: PINs are logged or visible in debug mode to help understand authentication flow
• Production Concern: Credentials should never be logged or visible in any environment
• Better Practice: Log only authentication attempts and results, never the credentials themselves

Token Management

Simple Token Structure

• Value for Testing/Education: Straightforward claims make token content easy to understand
• Production Concern: May lack necessary security claims (nbf, jti) and audience validation
• Better Practice: Include comprehensive claims and validation checks

File-Based Secret Storage

• Value for Testing/Education: Easy to inspect and modify for learning purposes
• Production Concern: Insecure storage of sensitive cryptographic material
• Better Practice: Use secure key vaults, HSMs, or secret management services

System Design

Simplified Architecture

• Value for Testing/Education: Single-component design makes it easy to follow authentication flow
• Production Concern: Lacks separation of concerns and proper security boundaries
• Better Practice: Implement proper separation between authentication, authorization, and resource servers

In-Memory Storage

• Value for Testing/Education: Simplifies setup and makes state changes visible
• Production Concern: No persistence, poor scaling, vulnerable to memory attacks
• Better Practice: Use secure, dedicated databases with proper data protection

How Sandcastle Auth Fills a Gap

Sandcastle Auth addresses a gap in the ecosystem of authentication tools:

1. Full-featured authentication servers (like Keycloak, Auth0) are:
   • Comprehensive but complex to set up
   • Rich in features but lacking in transparency
   • Optimized for security rather than learning
2. Simple JWT libraries provide:
   • Basic token operations but little visibility
   • No integrated testing capabilities
   • Limited educational value
3. Educational examples often:
   • Lack practical testing utility
   • Oversimplify important concepts
   • Don’t integrate with real applications

Sandcastle Auth bridges these gaps by providing a tool that is:

• Lightweight enough for testing
• Transparent enough for learning
• Practical enough for real debugging scenarios
• Flexible enough for various authentication needs

Limitations & Disclaimers

• Not Production-Ready:
  • Minimal validation and security checks
  • No robust scaling or high availability features
  • Simplified security model for clarity
• No Hierarchical Roles:
  • Roles are simple flags; no nested structures
• Limited Security Controls:
  • Minimal protection against brute force attacks
  • Basic validation rules focused on education
  • Limited token security features

For production systems, consider established authentication services like Keycloak, Auth0, or Okta, which have addressed these concerns through years of security-focused development.

FAQ

1. Q: Can I integrate this with my production system?
   A: It’s only meant for demos and testing, please do not rely on it for production security. Even the name is a clue, a sandcastle isn’t a fortress.
2. Q: Where is the user data stored?
   A: By default, in an H2 in-memory DB. You can switch to other DB engines with standard Spring configurations.
3. Q: How do I add more roles/domains/users?
   A: Configure them in application.yml or application.properties, or via an external config file. The server initializes them at startup and they can then be temporaraly modified by the spring rest API.
4. Q: Why am I getting a 401 with my token?
   A: Check if the token is expired, or if you used the correct Bearer scheme in the Authorization header.

Contributing

Contributions that enhance the educational value and testing capabilities of Sandcastle Auth are welcome. Please consider:

• Adding clear comments that explain the “why” behind implementation choices
• Enhancing logging to make the authentication flow more visible
• Creating additional examples that demonstrate specific JWT concepts
• Expanding documentation with learning resources
• Adding new testing utilities and scenarios

See my github for full source https://github.com/robdeas/sandcastle-auth

License

Sandcastle Auth is dual-licensed under MIT and Apache 2.0 licenses to maximize flexibility for educational and testing use..