118 lines
3.5 KiB
Markdown
118 lines
3.5 KiB
Markdown
# Concept Plan
|
|
|
|
## Objectives
|
|
|
|
- Provision Nextcloud users from Qortal identities.
|
|
- Support both existing and newly-created Nextcloud users.
|
|
- Add Qortal-backed login through OIDC without deep Nextcloud core coupling.
|
|
|
|
## Program goals
|
|
|
|
1. Admins can enable Qortal onboarding for existing Nextcloud users.
|
|
2. Users can authenticate to Nextcloud with Qortal ownership proof.
|
|
3. Users receive guided prompts (in-app/email) to create or link Qortal identity.
|
|
4. Approved Q-Apps can be launched from Nextcloud with policy controls.
|
|
|
|
See `docs/master-goals.md` for the full delivery plan and architecture boundaries.
|
|
|
|
## Architecture
|
|
|
|
### Components
|
|
|
|
1. Qortal External Auth API (existing)
|
|
- Source of truth for Qortal identity ownership proofs.
|
|
2. Qortal OIDC Broker (this repo, TypeScript)
|
|
- OIDC provider endpoints for Nextcloud `user_oidc`.
|
|
- Calls Qortal External Auth for challenge verification.
|
|
- Uses Nextcloud Provisioning API for account create/update/link.
|
|
3. Nextcloud + `user_oidc`
|
|
- Handles login UI/session.
|
|
- Uses broker as external OpenID Connect provider.
|
|
4. Mapping store
|
|
- `qortal_address -> nextcloud_userid`.
|
|
- Persisted in broker PostgreSQL for deterministic identity mapping.
|
|
5. Q-Apps gateway proxy (Nextcloud app)
|
|
- Embeds Q-Apps through a gateway URL.
|
|
- Rewrites gateway assets and API calls for same-origin rendering.
|
|
|
|
## Phase plan
|
|
|
|
### Phase 1: Provisioning Bridge (now)
|
|
|
|
- Implement service account access to Nextcloud OCS API.
|
|
- Add endpoints:
|
|
- `POST /api/provision/upsert`
|
|
- `POST /api/provision/upsert-from-wallet`
|
|
- `POST /api/provision/link`
|
|
- `GET /api/provision/mapping/:qortalAddress`
|
|
- `GET /api/provision/mappings`
|
|
- Create users when absent; map identities and return linkage metadata.
|
|
|
|
Definition of done:
|
|
- Calling broker endpoint creates a Nextcloud user and stores mapping.
|
|
- Repeated calls for same Qortal address are idempotent.
|
|
|
|
### Phase 2: OIDC Login
|
|
|
|
- Implement broker endpoints:
|
|
- `/.well-known/openid-configuration`
|
|
- `/authorize`
|
|
- `/token`
|
|
- `/userinfo`
|
|
- `/jwks`
|
|
- In `/authorize`, validate Qortal ownership by signed nonce challenge.
|
|
- Issue OIDC code/token set for Nextcloud.
|
|
|
|
Definition of done:
|
|
- Nextcloud `user_oidc` can redirect to broker and complete login.
|
|
- `sub` claim maps consistently to linked Nextcloud user.
|
|
|
|
### Phase 3: Existing + New User Policies
|
|
|
|
- Configure `user_oidc` auto-provision mode for desired behavior.
|
|
- Support strict/pre-provision modes where required.
|
|
- Add admin endpoints/UI for manual linking and conflict handling.
|
|
|
|
Definition of done:
|
|
- Existing users can link/login without duplicate account creation.
|
|
- New users can be auto-provisioned based on policy.
|
|
|
|
## Data contracts (starter)
|
|
|
|
### Provision upsert request
|
|
|
|
```json
|
|
{
|
|
"qortalAddress": "Q...",
|
|
"nextcloudUserId": "optional-existing-user",
|
|
"displayName": "Optional Name",
|
|
"email": "optional@example.com"
|
|
}
|
|
```
|
|
|
|
### Provision upsert response
|
|
|
|
```json
|
|
{
|
|
"linked": true,
|
|
"qortalAddress": "Q...",
|
|
"nextcloudUserId": "nc_user_123",
|
|
"created": true
|
|
}
|
|
```
|
|
|
|
Notes:
|
|
- Provisioning responses never return plaintext passwords.
|
|
- If user auto-creation is needed, password generation is internal-only.
|
|
|
|
## Risks and mitigations
|
|
|
|
- OIDC complexity
|
|
- Start with minimal standards-compliant broker and add claims incrementally.
|
|
- Account duplication
|
|
- Enforce deterministic mapping and explicit conflict responses.
|
|
- Secret handling
|
|
- Keep service credentials in env vars; rotate in deployment pipeline.
|
|
- Desktop/WebDAV compatibility
|
|
- Document app-password strategy early for non-browser clients.
|