adam/Piwigo
1
0 Fork 0
mirror of https://github.com/Piwigo/Piwigo.git synced 2026-11-02 23:12:23 +01:00
Code Issues 657 Packages Projects Releases Wiki Activity

[auth] support multiple authentication strategies (classic, api key, modern header) #2045

New Issue
Closed
opened 2026-10-05 01:04:38 +02:00 by adam · 0 comments
adam commented 2026-10-05 01:04:38 +02:00
Owner
Copy link
Copy source

To better structure and evolve the authentication system in Piwigo, here is a breakdown of the current and future authentication workflows. This summary aims to guide implementation decisions and ensure compatibility across various clients (web, legacy, modern CLI/mobile).

1. Classic Authentication (session via cookies, current workflow)

Usage: Piwigo web interface or API calls with login/password

  • POST /ws.php?method=pwg.session.login
  • Data: username, password
  • Creates a PHP session
  • Returns a PHPSESSID cookie
  • Following requests must include this cookie

Limitations:

  • Depends on a browser or client that handles cookies
  • Doesn’t work if 2FA is enabled and not supported by the client

2. Alternative Authentication via API Key (keyID + keySecret as login/pass)

Usage: For compatibility with legacy clients (e.g. Piwigo Lightroom plugin, etc.)

The client uses:

  • username = key_id (e.g., pkid-20250414-qGNVUrtbHIHIVUrttbBoN)
  • password = key_secret (e.g., dH8HQlo8oQsZcfaKeKEYELRx7EFY01J04RMyb)

Advantage: Zero client modification, bypasses 2FA
But: Not secure if poorly handled on the server side — the server must differentiate between a real login/password and a key_id/key_secret pair.
Unlike a password, the key_secret is randomly and uniquely generated by Piwigo. Therefore, it is much more secure than a traditional password and can safely bypass 2FA.

3. Modern Authentication via Authorization: <key_id:key_secret>

Usage: Modern clients, mobile apps, CLI tools

The app calls:

GET /ws.php?method=some.method  
Authorization: <key_id:key_secret>
  • A hook or middleware detects this header and checks the key in the database
  • A pwg_token is automatically added to prevent CSRF

If valid:

  • The key is associated with a user_id
  • A temporary session is created for the duration of the request, similar to uploadAsync when providing a username and password
To better structure and evolve the authentication system in Piwigo, here is a breakdown of the current and future authentication workflows. This summary aims to guide implementation decisions and ensure compatibility across various clients (web, legacy, modern CLI/mobile). _________________________________________________________________________________________________ ### 1. Classic Authentication (session via cookies, current workflow) Usage: Piwigo web interface or API calls with login/password - POST /ws.php?method=pwg.session.login - Data: username, password - Creates a PHP session - Returns a PHPSESSID cookie - Following requests must include this cookie Limitations: - Depends on a browser or client that handles cookies - Doesn’t work if 2FA is enabled and not supported by the client _________________________________________________________________________________________________ ### 2. Alternative Authentication via API Key (keyID + keySecret as login/pass) Usage: For compatibility with legacy clients (e.g. Piwigo Lightroom plugin, etc.) The client uses: - username = key_id (e.g., `pkid-20250414-qGNVUrtbHIHIVUrttbBoN`) - password = key_secret (e.g., `dH8HQlo8oQsZcfaKeKEYELRx7EFY01J04RMyb`) Advantage: Zero client modification, bypasses 2FA But: Not secure if poorly handled on the server side — the server must differentiate between a real login/password and a key_id/key_secret pair. Unlike a password, the key_secret is randomly and uniquely generated by Piwigo. Therefore, it is much more secure than a traditional password and can safely bypass 2FA. _________________________________________________________________________________________________ ### **3. Modern Authentication via Authorization: <key_id:key_secret>** Usage: Modern clients, mobile apps, CLI tools The app calls: ``` GET /ws.php?method=some.method Authorization: <key_id:key_secret> ``` - A hook or middleware detects this header and checks the key in the database - A pwg_token is automatically added to prevent CSRF If valid: - The key is associated with a user_id - A temporary session is created for the duration of the request, similar to uploadAsync when providing a username and password <!-- github-sync-id:2993567154 -->
adam closed this issue 2026-10-05 01:04:38 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
adam (Adam Wojcieszonek)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: adam/Piwigo#2045