MAD Auth Service -- User Manual

Version 2.0.0 | Port 8900 | content.madnet.gr/auth/

---

What Is This?

MAD Auth is the "front door" for all MAD TV online tools. Before you can use the Dashboard, Music Scheduler, Radio Ratings, Playout, or any other service at content.madnet.gr, you need to sign in.

Once signed in, you get a secure cookie that lasts 12 hours. The web server checks this cookie on every request and verifies you have access to the specific service you're visiting.

---

Signing In

URL: https://content.madnet.gr/auth/login

Option 1: Magic Link (recommended)

1. Enter your email address and click Send Sign-In Link.
2. Check your email for a message from MAD TV.
3. Click the link in the email. You are signed in and redirected to the Dashboard.

The link expires after 15 minutes and can only be used once. If it expires, request a new one.

Option 2: Password (fallback)

1. Click the Password tab on the sign-in page.
2. Enter your username and password, click Sign In.

If your account was created without a password (magic-link only), the password tab will not work. Ask the admin to set one if needed.

---

Signing Out

Individual services include their own logout buttons. Signing out clears your cookie and revokes your session immediately.

---

User Roles

Role	What it means
admin	Full access to everything. Can manage users, view sessions, and see the audit log at /auth/admin.
editor	Can access only the services assigned to their account. Cannot manage other users.

---

Per-Service Access Control

Each user has a list of allowed services. The web server checks this on every request — not just on the dashboard. If you try to visit a service you don't have access to (even by typing the URL directly), you will be redirected to the sign-in page.

The full list of services is managed by admins at /auth/admin. The service registry is defined in data/services.json on the server.

---

For Admins

Admin Panel

URL: https://content.madnet.gr/auth/admin

The admin panel has four tabs:

• Users -- Create, edit, delete users. Assign roles and services. Set passwords. Send magic links. Revoke sessions.
• Sessions -- View all active sessions. Revoke individual sessions or all sessions for a user.
• Audit Log -- Every login (success or failure), permission change, session revocation, and access denial is logged with timestamp, IP, and actor.
• Services -- Read-only view of the service registry (edit data/services.json on the server to modify).

Creating a User (Magic Link Only)

In the admin panel, click Add User. Enter a username and email. Leave the password blank — the user will sign in via magic link. Select the services they need.

Creating a User (With Password)

Same as above, but also enter a password. The user can sign in with either method.

API Endpoints

Method	Path	Auth	What it does
GET	/auth/login	No	Sign-in page
POST	/auth/login	No	Password login
POST	/auth/magic-link/request	No	Send magic link email
GET	/auth/magic-link/verify	No	Consume magic link, create session
POST	/auth/logout	Cookie	Sign out, revoke session
GET	/auth/validate	Cookie	Returns current user info
GET	/auth/check-service	Cookie	Per-service access check (used by Caddy)
GET	/auth/api/users	Admin	List all users
POST	/auth/api/users	Admin	Create a user
PUT	/auth/api/users/:id	Admin	Update a user
DELETE	/auth/api/users/:id	Admin	Delete a user
POST	/auth/api/users/:id/revoke-all	Admin	Revoke all sessions for a user
GET	/auth/api/sessions	Admin	List active sessions
POST	/auth/api/sessions/:id/revoke	Admin	Revoke a session
GET	/auth/api/audit	Admin	Query audit log
GET	/auth/api/services	Cookie	List service registry
GET	/auth/admin	Admin	Admin panel UI
GET	/auth/health	No	Health check

---

How the Cookie Works

• Name: mad_session
• Type: HttpOnly, Secure, SameSite=Lax
• Domain: content.madnet.gr
• Expires: 12 hours after sign-in
• Contents: A signed JWT token containing your user ID, session ID, username, role, display name, and allowed services

There is also a mad_services cookie readable by JavaScript for UI filtering.

---

Security

• Passwords hashed with scrypt (64-byte hash, 16-byte salt).
• JWT signed with HMAC-SHA256, timing-safe verification.
• Magic links are single-use, expire in 15 minutes, rate-limited to 3 per email per 15 minutes.
• Sessions are tracked in SQLite. Revoking a session invalidates it immediately.
• Changing a user's permissions invalidates all their existing sessions (forces re-login).
• All auth events logged to audit_log table.
• Per-service enforcement via Caddy forward_auth — every request is checked, not just the dashboard.

---

Troubleshooting

Problem	Solution
"Invalid username or password"	Check caps lock. Ask admin to verify your account is active.
Magic link not arriving	Check spam folder. Verify your email is set in the admin panel. Max 3 links per 15 minutes.
"This sign-in link has expired"	Links expire after 15 minutes. Request a new one.
Keeps redirecting to login	Cookie expired (12h) or session was revoked by admin. Sign in again.
Can sign in but can't access a service	You don't have that service in your allowed list. Ask admin at /auth/admin.

---

MAD Auth Service v2.0.0 | content.madnet.gr/auth/