YY Central Auth Service

Microservice responsible for user authentication, registration, and access token generation.

Overview

The YY Central Auth Service is a standalone spring microservice that handles all authentication and authorization concerns for the YY platform. It issues JWT access tokens upon successful login and provides token validation/invalidation capabilities for other microservices.

Installation

1. Clone the repository:

git clone https://gitlab.blackruby.hu/yys/yy-central-auth-service.git
cd yy-central-auth-service

2. Build:

# Maven
mvn clean install

# Gradle
./gradlew build

3. Run:

java -jar target/<executable>.jar

The service will be available at http://localhost:8080

Prerequisites

• Environment variable for setting the JWT signing secret AUTH_TOKEN_SECRET

How it works

1. The client calls a protected endpoint with header:
   • Authorization: Bearer <access-token>
2. Caddy calls this service to authenticate the token:
   • GET /api/auth/authenticate
3. If the token is valid, this service responds with user identity headers.
4. Caddy forwards the original request to the protected upstream endpoint and injects these identity headers.

Gateway-injected identity headers (contract)

All protected endpoints are expected to be called through the Caddy gateway. These headers are set by Caddy for protected routes and are trusted by upstream services:

Header name	Type	Meaning
X-User-Id	int	Authenticated user’s id
X-User-Username	string	Authenticated user’s username
X-User-Role	string	Authenticated user’s role (e.g. ADMIN)
X-Token-Type	string	Token type (e.g. ACCESS_TOKEN)

Note: Clients should not manually supply these X-* identity headers. They are internal/trusted headers between Caddy and backend services.

API Documentation

Endpoint	Method	Auth Required	Description	Request Headers	Request Body	Response on success
/api/auth/login	POST	No	Authenticate and receive an access token	None	JSON { "username": string, "password": string }	201 Created, { "accessToken": string }
/api/auth/register	POST	No	Register a new user with an invite token	None	JSON { "username": string, "password": string, "inviteToken": string }	201 Created
/api/auth/authenticate	GET	Yes, Bearer token (used by gateway)	Authenticate token and return user identity headers	Authorization: Bearer <token>	None	200 OK, identity in response headers (see table below)
/api/auth/invite-token	POST	Yes (via gateway; injects identity)	Create a new invite token	X-User-Id (provided by gateway)	None	200 OK, { "inviteToken": string }
/api/auth/invite-token	GET	Yes (via gateway; injects identity)	Retrieve existing invite token	X-User-Id (provided by gateway)	None	200 OK, { "inviteToken": string }
/api/auth/invalidate	POST	Yes, (via gateway; injects identity)	Invalidate a token (prevent future use)	Authorization: Bearer <admin>	JSON { "subjectId": int, "invalidationExpirationDate": ISO-8601 timestamp string }	201 Created

/api/auth/authenticate response headers

On success (200 OK), the endpoint returns no body and includes:

Header name	Example
X-User-Id	1
X-User-Username	exampleUsername
X-User-Role	ADMIN
X-Token-Type	ACCESS_TOKEN

Example usage

Login Request

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "exampleUsername",
    "password": "examplePassword"
  }'

Response (201 Created) with body

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Register Request

curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{ 
    "username": "newUser", 
    "password": "securePassword123", 
    "inviteToken": "abc123-invite-token-string" 
    }'

Response (201 Created)

Create Invite Token Request

curl -X POST http://localhost:8080/api/auth/invite-token \
  -H "Authorization: Bearer <access-token>" \
  -H "X-User-Id: 1"

Response (201 Created) with body:

{ 
  "inviteToken": "generated-invite-token-string"
}

Retrieve Invite Token Request

curl -X GET http://localhost:8080/api/auth/invite-token \
  -H "Authorization: Bearer <access-token>" \
  -H "X-User-Id: 1

Reponse (200 OK) with body:

{ 
  "inviteToken": "existing-invite-token-string"
}

Validate Token Request

To be used by the central gateway to validate access token before attaching the user specific headers and forwarding the request to the microservices.

curl -X GET http://localhost:8080/api/auth/validate \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{ 
    "subjectId": 123, 
    "tokenIssueDate": "2026-02-01T10:30:00Z" 
    }'

Response (200 OK) with response body:

{ "tokenIsInvalid": false }

Invalidate Token Request

curl -X POST http://localhost:8080/api/auth/invalidate \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectId": 123,
    "invalidationExpirationDate": "2026-02-01T10:30:00Z"
    }'

Response (201 Created)