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
• OpenCloud Troubleshooting
• Deployment Status
• OpenCloud Official Docs

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