Qortal-Nextcloud-Integration/docs/external-auth-integration.md

Qortal External Auth Integration

This repo now includes a broker client for the Qortal External Auth API.

API docs

• Local docs URL: http://localhost:3191/docs/static/index.html
• OpenAPI JSON: http://localhost:3191/docs/json

Broker environment

Set these in .env (or .env.postgres / .env.devprod):

BROKER_INTERNAL_API_TOKEN=<random-secret>
BROKER_CORS_ALLOWED_ORIGINS=https://cloud.example.com
QORTAL_EXTERNAL_AUTH_BASE_URL=http://gateway.docker.internal:3191
QORTAL_EXTERNAL_AUTH_APP_ID=<your-app-id>
QORTAL_EXTERNAL_AUTH_APP_SECRET=<your-app-secret>

Notes:

• gateway.docker.internal works from Docker containers to host services in this setup.
• If you run the bundled External Auth container (profile external-auth), set:
  • QORTAL_EXTERNAL_AUTH_BASE_URL=http://external_auth:3191
• You can also register the External Auth app from the Nextcloud admin UI (Qortal Integration → External Auth Configuration). After updating env files, restart the broker container so it picks up the new credentials.
• Broker internal APIs (/api/qortal/*, /api/provision/*, /api/oidc/*) require X-Broker-Internal-Token: <BROKER_INTERNAL_API_TOKEN> when called directly.

Register app credentials

curl -sS -X POST http://localhost:3191/apps/register \
  -H "Content-Type: application/json" \
  -d '{"name":"qortal-nextcloud-integration"}'

Response shape:

{
  "appId": "...",
  "appSecret": "..."
}

Broker endpoints that use External Auth

• GET /api/qortal/health
  • Checks connectivity to External Auth /health.
• GET /api/qortal/wallets
  • Uses app credentials -> session token -> /wallets.
• POST /api/qortal/wallets
  • Uses app credentials -> session token -> /wallet/create.
  • Request body:
    • password (required)
    • kdfThreads (optional)
• POST /api/qortal/wallets/backup
  • Uses app credentials -> session token -> /wallet/backup.
  • Request body:
    • walletId (required)
    • password (required)
  • Returns backup JSON for download or storage in Nextcloud Files.
• POST /api/provision/upsert-from-wallet
  • Body requires walletId.
  • Broker resolves wallet metadata via /wallet/{id}, then provisions/links by address0.
• POST /api/provision/import-seed-link
  • Body requires:
    • seedPhrase
    • password
    • nextcloudUserId
  • Imports wallet through External Auth /wallet/import-seed, then links imported address0 to the requested Nextcloud user.
• POST /api/provision/import-backup-link
  • Body requires:
    • backup (or backupJson)
    • password
    • nextcloudUserId
  • Imports wallet through External Auth /wallet/import-backup, then links imported address0 to the requested Nextcloud user.
• GET /api/provision/mappings/by-nextcloud/:nextcloudUserId
  • Lists mapping records for a specific Nextcloud user.
• POST /api/provision/unlink
  • Removes mapping by qortalAddress (optionally constrained by nextcloudUserId).
• GET /authorize + POST /authorize
  • OIDC login flow now requires wallet import to prove ownership:
    • seed phrase + password, or
    • backup JSON + password
  • Optional qortal_address must match the imported wallet address.

Example wallet-based provisioning call:

curl -sS http://localhost:3000/api/provision/upsert-from-wallet \
  -H "X-Broker-Internal-Token: ${BROKER_INTERNAL_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"walletId":"<WALLET_ID>","displayName":"Qortal User"}'