143 lines
4.4 KiB
Markdown
143 lines
4.4 KiB
Markdown
# Nextcloud OIDC Setup
|
||
|
||
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 `Login with qortal`.
|
||
|
||
## 5) Broker OIDC policy mode
|
||
|
||
Configure in `.env`:
|
||
|
||
```bash
|
||
BROKER_INTERNAL_API_TOKEN=<random-secret>
|
||
OIDC_POLICY_MODE=link_only
|
||
```
|
||
|
||
Modes:
|
||
|
||
- `link_only` (default): mapped identities only (`qortal_address -> nextcloud_user_id` must already exist).
|
||
- `auto_provision`: missing mappings are created at authorize time (creates Nextcloud user if needed).
|
||
|
||
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. Users paste their invite
|
||
token there to unlock account creation.
|
||
|
||
## 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.
|