# 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

```bash
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

```bash
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`:

```bash
127.0.0.1 broker
```

This prevents token endpoint failures after the login redirect.

## 3) Add OIDC provider config via `occ`

```bash
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:

```bash
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`:

```bash
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`:

```bash
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:

```bash
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.