Authentication Configuration

Overview

Hub uses Auth0 for authentication and authorization. The backend validates JWT tokens issued by Auth0 and extracts user permissions for role-based access control.

The Hub platform implements OAuth 2.0 with JWT bearer tokens for stateless authentication.

Prerequisites

Before configuring authentication, you need:

An Auth0 account
An Auth0 API configured for your application
Auth0 Application (SPA or Regular Web App) for your frontend

Auth0 Setup

Create Auth0 API

Log in to your Auth0 dashboard
Navigate to Applications > APIs
Click Create API
Set a name (e.g., “Hub API”) and identifier (e.g., https://api.padelhub.com)
Keep the signing algorithm as RS256

Configure permissions

In your Auth0 API, define permissions for different user roles:

read:venues - View venue information
write:venues - Create and update venues
read:bookings - View own bookings
write:bookings - Create bookings
admin:all - Full administrative access

Create Auth0 Application

Go to Applications > Applications
Click Create Application
Choose Single Page Web Applications (for React/Vue frontends)
Configure the following:
- Allowed Callback URLs: http://localhost:3000/callback, https://app.padelhub.com/callback
- Allowed Logout URLs: http://localhost:3000, https://app.padelhub.com
- Allowed Web Origins: http://localhost:3000, https://app.padelhub.com

Get configuration values

From your Auth0 dashboard, collect:

Domain: Found in your API settings (e.g., padelhub.eu.auth0.com)
Audience: Your API identifier (e.g., https://api.padelhub.com)

Environment Configuration

Set the following environment variables:

AUTH0_ISSUER

string

required

Auth0 issuer URI for JWT validationFormat: https://YOUR_DOMAIN.auth0.com/Example: https://padelhub.eu.auth0.com/

Must include the trailing slash /

AUTH0_AUDIENCE

string

required

Auth0 API audience identifierExample: https://api.padelhub.comThis must exactly match the identifier you set when creating the Auth0 API.

AUTH0_ISSUER=https://padelhub.eu.auth0.com/
AUTH0_AUDIENCE=https://api.padelhub.com

JWT Token Structure

The backend expects JWT tokens with the following claims:

JWT Token Claims

{
  "iss": "https://padelhub.eu.auth0.com/",
  "sub": "auth0|6479e1234567890abcdef",
  "aud": "https://api.padelhub.com",
  "iat": 1678901234,
  "exp": 1678987634,
  "scope": "openid profile email",
  "permissions": [
    "read:venues",
    "write:bookings",
    "read:bookings"
  ]
}

Key Claims

iss (Issuer): Auth0 domain, validated against AUTH0_ISSUER
aud (Audience): API identifier, validated against AUTH0_AUDIENCE
sub (Subject): Unique user identifier (Auth0 user ID)
permissions: Array of user permissions for authorization
scope: OAuth 2.0 scopes

Authorization Flow

User requests authentication

Frontend redirects user to Auth0 login page with your application’s client ID.

User authenticates

User logs in via Auth0 (username/password, social login, etc.).

Auth0 issues tokens

Auth0 returns an access token (JWT) and optional refresh token.

Frontend includes token

Frontend includes the JWT in the Authorization header:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Backend validates token

The backend:

Verifies the JWT signature using Auth0’s public keys
Validates the issuer matches AUTH0_ISSUER
Validates the audience matches AUTH0_AUDIENCE
Checks token expiration
Extracts permissions for authorization

User synchronized

The EnsureLocalUserFilter ensures a local user record exists in the database, creating one if necessary.

Security Configuration

The application implements several security measures:

CORS Configuration

Allowed origins are configured based on APP_FRONTEND_URL:

SecurityConfig.java

config.setAllowedOrigins(List.of(
  "http://localhost:3000",
  "http://127.0.0.1:3000",
  "http://localhost:5173",
  "http://127.0.0.1:5173",
  frontendUrl  // From APP_FRONTEND_URL
));

Update APP_FRONTEND_URL to match your production frontend URL.

HTTP Security Headers

Content Security Policy: default-src 'self'; frame-ancestors 'none'
HSTS: Enabled with 1-year max age and includeSubDomains
Session Management: Stateless (no server-side sessions)

Public Endpoints

The following endpoints do not require authentication:

/actuator/health - Health check
/v3/api-docs/** - OpenAPI documentation (disable in production)
/swagger-ui/** - Swagger UI (disable in production)

Permission-Based Authorization

Protect endpoints using Spring Security’s method security:

@PreAuthorize("hasAuthority('PERM_write:venues')")
public VenueDto createVenue(CreateVenueRequest request) {
    // Only users with 'write:venues' permission can access
}

Permissions from the JWT are prefixed with PERM_ by the JwtAuthenticationConverter.

Testing Authentication

Get a Test Token

Use Auth0’s test feature or implement a login flow in your frontend:

cURL Example

curl -X POST https://padelhub.eu.auth0.com/oauth/token \
  -H 'content-type: application/json' \
  -d '{
    "client_id":"YOUR_CLIENT_ID",
    "client_secret":"YOUR_CLIENT_SECRET",
    "audience":"https://api.padelhub.com",
    "grant_type":"client_credentials"
  }'

Make Authenticated Request

Authenticated API Call

curl -X GET http://localhost:8080/api/venues \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Expected Responses

Success (200 OK):

{
  "venues": [...]
}

Unauthorized (401):

{
  "error": "unauthorized",
  "error_description": "Full authentication is required to access this resource"
}

Forbidden (403):

{
  "error": "access_denied",
  "error_description": "Insufficient permissions"
}

Troubleshooting

Token Validation Failures

Invalid issuer

Error: The iss claim is not validSolution: Verify AUTH0_ISSUER matches your Auth0 domain exactly, including the trailing slash.

Invalid audience

Error: The aud claim is not validSolution: Ensure AUTH0_AUDIENCE matches the API identifier in Auth0 exactly.

Token expired

Error: Jwt expired at...Solution: Tokens have a limited lifetime (typically 24 hours). Request a new token or implement token refresh.

Missing permissions

Error: Access Denied (403)Solution: Check that the user has the required permissions in Auth0. Permissions must be added to the JWT token.

Debugging Tips

Enable debug logging:

logging:
  level:
    org.springframework.security: DEBUG

Decode JWT tokens: Use jwt.io to inspect token contents
Check Auth0 logs: Review authentication logs in the Auth0 dashboard
Verify public keys: Ensure the backend can access https://YOUR_DOMAIN.auth0.com/.well-known/jwks.json

Next Steps

Database Configuration

Set up PostgreSQL database

User Management

Manage users via API

Frontend Development

Frontend Auth0 integration

Environment Variables

Configure Auth0 environment

Get Started

Core Features

User Guides

Configuration

Authentication Configuration

Overview

Prerequisites

Auth0 Setup

Environment Configuration

JWT Token Structure

Key Claims

Authorization Flow

Security Configuration

CORS Configuration

HTTP Security Headers

Public Endpoints

Permission-Based Authorization

Testing Authentication

Get a Test Token

Make Authenticated Request

Expected Responses

Troubleshooting

Token Validation Failures

Debugging Tips

Next Steps

Database Configuration

User Management

Frontend Development

Environment Variables

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

Configuration

Documentation Index

​Overview

​Prerequisites

​Auth0 Setup

​Environment Configuration

​JWT Token Structure

​Key Claims

​Authorization Flow

​Security Configuration

​CORS Configuration

​HTTP Security Headers

​Public Endpoints

​Permission-Based Authorization

​Testing Authentication

​Get a Test Token

​Make Authenticated Request

​Expected Responses

​Troubleshooting

​Token Validation Failures

​Debugging Tips

​Next Steps

Database Configuration

User Management

Frontend Development

Environment Variables

Build docs developers (and LLMs) love

Overview

Prerequisites

Auth0 Setup

Environment Configuration

JWT Token Structure

Key Claims

Authorization Flow

Security Configuration

CORS Configuration

HTTP Security Headers

Public Endpoints

Permission-Based Authorization

Testing Authentication

Get a Test Token

Make Authenticated Request

Expected Responses

Troubleshooting

Token Validation Failures

Debugging Tips

Next Steps