Play Secure Rest Template

A REST API built with the Play Framework featuring JWT authentication and Swagger documentation, including smart authentication bypass for Swagger UI requests.

---

Features

• JWT Authentication: Secure API endpoints using token-based authentication
• Role-Based Access Control: Support for role-based authorization (e.g., ADMIN role)
• Swagger Integration: Interactive API documentation with Swagger UI
• Smart Authentication Bypass: Automatic authentication bypass for requests originating from Swagger UI
• Code Formatting: Integrated Scalafmt for consistent code formatting
• Comprehensive Testing: Unit tests for all major functionality

---

Prerequisites

• Java: JDK 11, 17, or 21

  Note: Java 23 is not officially supported by Play Framework

• SBT: Scala Build Tool (latest version)
• Scala: 2.13.18 (managed by SBT)

---

Project Structure

play-secure-rest-template/
├── app/
│   ├── auth/                    # Authentication components
│   │   ├── JwtAuthAction.scala  # JWT authentication action with Swagger bypass
│   │   ├── RoleAction.scala     # Role-based authorization
│   │   └── AuthenticatedRequest.scala
│   ├── controllers/             # API controllers
│   │   ├── UserController.scala # User management endpoints
│   │   ├── HomeController.scala # Home page
│   │   └── ApiHelpController.scala
│   ├── models/                  # Data models
│   ├── utils/                   # Utility classes
│   └── views/                   # HTML templates
├── conf/
│   ├── routes                   # URL routing configuration
│   ├── application.conf         # Application configuration
│   └── openapi.yaml            # OpenAPI specification
├── public/swagger-ui/           # Swagger UI static files
├── test/                        # Test files
└── .scalafmt.conf              # Code formatting configuration

Getting Started

1. Install Dependencies

sbt update

2. Install Dependencies

sbt compile

3. Run Tests

sbt test

4. Start the Application

sbt run

The application will start on http://localhost:9000

API Endpoints

Public Endpoints

• GET / - Home page
• GET /openapi.yaml - OpenAPI specification
• GET /docs/* - Swagger UI documentation

Protected Endpoints

• POST /users - Create a new user (requires JWT or Swagger bypass)
• GET /admin - Admin-only endpoint (requires ADMIN role or Swagger bypass)

Authentication

JWT Token Format

{
  "userId": "user123",
  "roles": ["USER", "ADMIN"]
}

Using JWT Authentication

Include the JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Swagger Authentication Bypass

The application automatically bypasses authentication for requests coming from Swagger UI through multiple detection methods:

1. Query Parameter: ?from_swagger=true
2. Referer Header: Contains /docs/ or swagger-ui
3. User-Agent: Contains "swagger"
4. Origin Header: Contains /docs
5. Request Path: Starts with /docs/

Development Commands

Format Code

sbt scalafmt

Check Code Formatting

sbt scalafmtCheck

Run in Development Mode

sbt run

Run Tests with Coverage

sbt test

Clean Build

sbt clean compile

Configuration

Application Settings

Edit conf/application.conf to modify:

• Database connections
• Security filters
• Logging levels
• Swagger API metadata

Security Filters

The following security filters are disabled for easier development:

• CSRF Filter
• Security Headers Filter
• Allowed Hosts Filter

Swagger UI

Access the interactive API documentation at:

http://localhost:9000/docs/index.html

The Swagger UI automatically bypasses authentication, allowing you to test all endpoints without providing JWT tokens.

Testing

Running All Tests

sbt test

Test Coverage

The project includes comprehensive tests for:

• Authentication bypass functionality
• Swagger request detection
• Controller endpoints
• JWT token validation

Troubleshooting

Common Issues

1. Java Version Warning: If you see warnings about Java 23, consider switching to Java 11, 17, or 21 for full compatibility.

2. Port Already in Use: If port 9000 is busy, stop other Play applications or use a different port:

   sbt "run -Dhttp.port=9001"

3. Authentication Issues: Ensure JWT tokens are properly formatted and include required fields (userId and roles).