From 5e02c64dc455543aada05d47d851110766ec20cb Mon Sep 17 00:00:00 2001 From: Paperclip CTO Date: Sat, 11 Jul 2026 12:03:44 +0000 Subject: [PATCH] docs: Add comprehensive Pocket ID OIDC client setup documentation Document all four OIDC clients for OpenCloud: - Web application (UUID-based client ID) - Desktop client (OpenCloudDesktop) - Android mobile (OpenCloudAndroid) - iOS mobile (OpenCloudIOS) Includes configuration details, security notes, and troubleshooting. Co-Authored-By: Paperclip --- apps/opencloud/POCKET_ID_OIDC_SETUP.md | 194 +++++++++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 apps/opencloud/POCKET_ID_OIDC_SETUP.md diff --git a/apps/opencloud/POCKET_ID_OIDC_SETUP.md b/apps/opencloud/POCKET_ID_OIDC_SETUP.md new file mode 100644 index 0000000..91e2411 --- /dev/null +++ b/apps/opencloud/POCKET_ID_OIDC_SETUP.md @@ -0,0 +1,194 @@ +# Pocket ID OIDC Client Setup for OpenCloud + +This document describes the correct OIDC client configuration in Pocket ID for OpenCloud web, desktop, and mobile applications. + +## Overview + +OpenCloud requires separate OIDC clients for each platform: +- **Web Application** - Browser-based access +- **Desktop Client** - Native Windows/macOS/Linux applications +- **Mobile Apps** - iOS and Android applications + +All clients authenticate against Pocket ID at `https://auth.basicstack.de`. + +## OIDC Clients Configuration + +### 1. Web Application + +**Client ID:** `2f3c0cea-697f-4dbc-9573-6f6e8adfd4b0` +**Client Name:** `OpenCloud` +**Client Type:** Public Client +**PKCE:** Enabled + +**Redirect URIs:** +- `https://opencloud.basicstack.de/` +- `https://opencloud.basicstack.de/oidc-callback.html` +- `https://opencloud.basicstack.de/oidc-silent-redirect.html` + +**Logout Redirect URIs:** +- `https://opencloud.basicstack.de` + +**Allowed User Groups:** +- OpenCloud Users +- OpenCloud Administrators +- OpenCloud Guests +- OpenCloud Space Administrators + +### 2. Desktop Client + +**Client ID:** `OpenCloudDesktop` +**Client Name:** `OpenCloud Desktop` +**Client Type:** Public Client +**PKCE:** Enabled (Required for native apps) + +**Redirect URIs:** +- `http://127.0.0.1` +- `http://localhost` + +**Logout Redirect URIs:** +- `http://127.0.0.1` +- `http://localhost` + +**Allowed User Groups:** +- OpenCloud Users +- OpenCloud Administrators +- OpenCloud Guests +- OpenCloud Space Administrators + +**Notes:** +- Desktop clients use dynamic ports (e.g., `http://127.0.0.1:60938`) +- The redirect URI base (`http://127.0.0.1`) matches all ports +- PKCE is required for security as desktop apps cannot securely store client secrets + +### 3. Android Mobile App + +**Client ID:** `OpenCloudAndroid` +**Client Name:** `OpenCloud Android` +**Client Type:** Public Client +**PKCE:** Enabled (Required for native apps) + +**Redirect URIs:** +- `oc://android.opencloud.app` + +**Logout Redirect URIs:** +- `oc://android.opencloud.app` + +**Allowed User Groups:** +- OpenCloud Users +- OpenCloud Administrators +- OpenCloud Guests +- OpenCloud Space Administrators + +### 4. iOS Mobile App + +**Client ID:** `OpenCloudIOS` +**Client Name:** `OpenCloud iOS` +**Client Type:** Public Client +**PKCE:** Enabled (Required for native apps) + +**Redirect URIs:** +- `oc://ios.opencloud.app` + +**Logout Redirect URIs:** +- `oc://ios.opencloud.app` + +**Allowed User Groups:** +- OpenCloud Users +- OpenCloud Administrators +- OpenCloud Guests +- OpenCloud Space Administrators + +## Common Configuration + +All clients share the following settings: + +**OIDC Issuer:** `https://auth.basicstack.de` +**Discovery Endpoint:** `https://auth.basicstack.de/.well-known/openid-configuration` +**JWKS Endpoint:** `https://auth.basicstack.de/.well-known/jwks.json` + +**Scopes:** +- `openid` - Required for OIDC +- `profile` - User profile information +- `email` - User email address +- `groups` - User group memberships +- `offline_access` - Refresh token support + +**Response Type:** `code` (Authorization Code Flow) +**PKCE Method:** `S256` (SHA-256) + +## User Group Permissions + +The following user groups have access to OpenCloud: + +1. **OpenCloud Users** - Standard users with file access +2. **OpenCloud Administrators** - Full administrative access +3. **OpenCloud Guests** - Limited guest access +4. **OpenCloud Space Administrators** - Space-level administrative permissions + +## Security Notes + +### Why Public Clients? + +Desktop and mobile applications are classified as "public clients" because: +- They cannot securely store client secrets +- The application code can be reverse-engineered +- PKCE provides security without requiring a client secret + +### PKCE (Proof Key for Code Exchange) + +All clients use PKCE to prevent authorization code interception attacks: +1. Client generates a random `code_verifier` +2. Client sends `code_challenge = SHA256(code_verifier)` to authorization endpoint +3. Client sends original `code_verifier` to token endpoint +4. Authorization server verifies the challenge matches + +### Client ID Naming + +The desktop and mobile client IDs use specific string identifiers (not UUIDs) because: +- OpenCloud applications expect these exact client IDs in their configuration +- The client_id parameter in OAuth flows must match exactly +- Example: Desktop app uses `client_id=OpenCloudDesktop` in authorization requests + +## Troubleshooting + +### Desktop Client Error: "Record not found" + +**Symptom:** When authenticating, Pocket ID returns "Record not found" + +**Cause:** The `client_id` parameter doesn't match any configured client in Pocket ID + +**Solution:** Verify the client ID is exactly `OpenCloudDesktop` (case-sensitive, no spaces) + +### Mobile App Authentication Fails + +**Symptom:** Mobile app cannot complete OIDC flow + +**Cause:** Custom URI scheme not registered or incorrect client_id + +**Solution:** +- Verify the app uses `OpenCloudAndroid` or `OpenCloudIOS` as client_id +- Ensure the custom URI scheme (`oc://`) is registered in the app manifest + +### Authorization Denied for User + +**Symptom:** User successfully logs into Pocket ID but is denied access to OpenCloud + +**Cause:** User is not a member of any allowed user groups + +**Solution:** Add the user to one of the four OpenCloud user groups in Pocket ID + +## Related Documentation + +- [OpenCloud OIDC Configuration](OIDC_FIX_SUMMARY.md) +- [OpenCloud Troubleshooting](OIDC_TROUBLESHOOTING.md) +- [Deployment Status](DEPLOYMENT_STATUS.md) +- [OpenCloud Official Docs](https://docs.opencloud.eu/docs/admin/configuration/authentication-and-user-management/external-idp/) + +## Pocket ID Administration + +Access Pocket ID admin interface at: `https://auth.basicstack.de` + +To manage OIDC clients: +1. Log in with admin credentials +2. Navigate to "OIDC Clients" +3. View/edit client configurations and user group assignments