stack.basicstack.de/apps/opencloud/POCKET_ID_OIDC_SETUP.md

# 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