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 <noreply@paperclip.ing>
This commit is contained in:
Paperclip CTO
parent
d8cd3638fa
commit
5e02c64dc4
1 changed files with 194 additions and 0 deletions
194
apps/opencloud/POCKET_ID_OIDC_SETUP.md
Normal file
194
apps/opencloud/POCKET_ID_OIDC_SETUP.md
Normal file
|
|
@ -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
|
||||
Loading…
Add table
Reference in a new issue