Qortal-Nextcloud-Integration/docs/nextcloud-oidc-setup.md

Nextcloud OIDC Setup

For the full NuQloud-as-Identity-Provider operator guide, client templates, security checklist, and recovery notes, see docs/nuqloud-identity-provider-guide.md.

OIDC auth-code flow is now implemented in the broker (/authorize, /token, /userinfo, /jwks). This doc covers the current dev setup for user_oidc.

1) Confirm app is enabled

make occ cmd="app:list --enabled"

You should see user_oidc in the enabled app list. If you are running the PostgreSQL stack, replace make occ with make occ-pg in all commands below.

2) Required local dev flags

make occ cmd="config:system:set allow_local_remote_servers --type=boolean --value=true"
make occ cmd="config:system:set debug --type=boolean --value=true"

Notes:

• allow_local_remote_servers=true lets Nextcloud call the local broker host.
• debug=true is needed for HTTP-only local login with user_oidc (it otherwise requires HTTPS).

2.1) Broker issuer hostname (important)

The issuer must be reachable by:

• the Nextcloud container (server-side token exchange), and
• your browser (authorization redirect).

Recommended dev setup:

• OIDC_ISSUER=http://broker:3000
• Add a host entry so your browser can resolve broker:

127.0.0.1 broker

This prevents token endpoint failures after the login redirect.

3) Add OIDC provider config via occ

make occ cmd="user_oidc:provider qortal -c nextcloud-local -s dev-secret -d http://broker:3000/.well-known/openid-configuration --scope='openid profile email' --mapping-uid=sub --mapping-display-name=name --mapping-email=email"

Verify provider is present:

make occ cmd="user_oidc:providers --output=json_pretty"

4) Login page check

Log out and open:

• http://localhost:8080/login

You should see a button similar to Create Account / Login in NuQloud mode, or the Qortal login button in full Qortal mode.

5) Broker OIDC policy mode

Configure in .env:

BROKER_INTERNAL_API_TOKEN=<random-secret>
OIDC_POLICY_MODE=auto_provision

Modes:

• auto_provision (default): missing mappings are created at authorize time (creates Nextcloud user if needed).
• link_only: mapped identities only (qortal_address -> nextcloud_user_id must already exist).

Security note:

• Any password used for internal Nextcloud user creation is generated server-side and is never returned in broker API responses.

When OIDC_POLICY_MODE=auto_provision, the broker guard defaults to invite_or_allowlist. That means new accounts are only created if the Qortal address is allowlisted or the user supplies a valid invite token on the broker authorize form.

Configure in .env:

OIDC_AUTO_PROVISION_GUARD=invite_or_allowlist
OIDC_INVITE_TTL_SECONDS=604800

6) Ownership check behavior

Ownership is now verified by importing the wallet at login time:

• Provide seed phrase + password, or
• Provide backup JSON + password.

The broker imports the wallet via External Auth, signs a nonce with the wallet, and verifies the resolved address0 + signature pair before issuing the OIDC code. If you also supply a Qortal address, it must match the imported wallet address.

This prevents login using only a public address. A future signed‑nonce flow can provide auth‑only login without import.

If auto-provision is guarded, the broker login form will include an Invite Token field. Invite links can prefill that token and open the new-user invite path automatically, but users can still paste the token manually if needed. The Qortal Integration dashboard can create the invite token/link for admins or MSP admins, and it stores the recipient email as the invite comment for tracking.

7) Pre-provision mapping (for link_only)

If OIDC_POLICY_MODE=link_only, create the mapping first:

curl -sS http://localhost:3000/api/provision/link \
  -H "X-Broker-Internal-Token: ${BROKER_INTERNAL_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "qortalAddress":"QORTAL_ADDRESS",
    "nextcloudUserId":"existing_nextcloud_user",
    "walletId":"OPTIONAL_WALLET_ID"
  }'

8) User self-service import + link

For beta flow that requires wallet import into broker-visible External Auth context:

1. User opens Personal Settings -> Qortal Integration.
2. User imports either:
   • seed phrase + wallet password (POST /apps/qortal_integration/api/user/import-seed-link)
   • backup JSON + backup password (POST /apps/qortal_integration/api/user/import-backup-link)
3. Imported wallet is linked to the current Nextcloud user and becomes OIDC-login eligible.
4. User can remove accidental links via POST /apps/qortal_integration/api/user/mappings/unlink.

9) Validate auth in UI

Open the Qortal Account dashboard:

• /apps/qortal_integration/account

It shows wallet ID, address, public key, names, and QORT balance, with a Test Auth button and live refresh to confirm that broker → External Auth signing is working.