135 lines
4.6 KiB
Markdown
135 lines
4.6 KiB
Markdown
# Qortal Integration Testing Guide
|
|
|
|
This guide covers the three main onboarding/login paths to test.
|
|
|
|
Keep this simple rule in mind:
|
|
|
|
- `link_only`: user mapping must already exist before Qortal login.
|
|
- `auto_provision`: mapping/user can be created during Qortal login.
|
|
- `auto_provision` + guard `invite_or_allowlist`: new-user Qortal login requires either an invite token or allowlisted Qortal address.
|
|
|
|
## Prerequisites (for all tests)
|
|
|
|
1. Nextcloud mail is configured (required for password reset / invite email tests).
|
|
2. Broker + External Auth are healthy.
|
|
3. In Nextcloud Admin > Qortal Integration, confirm:
|
|
- Broker URL works.
|
|
- Node URL works.
|
|
- OIDC policy mode and guard are set to the mode you want to test.
|
|
4. If your Qortal node requires API key, set it in external-auth runtime/env and recreate `external_auth` if needed.
|
|
|
|
---
|
|
|
|
## 1) Nextcloud-Admin-Created User + Invite + Password Reset
|
|
|
|
Use this to validate classic cloud-user onboarding flow. Where the nextcloud account is created first, and the user from there creates and links their (new) Qortal account.
|
|
|
|
### Setup - Starting as Nextcloud User
|
|
|
|
1. In Nextcloud Admin, create a normal Nextcloud user (or send invite using your normal admin flow).
|
|
2. Send onboarding instructions by email.
|
|
|
|
### User flow - Starting as Nextcloud User
|
|
|
|
1. User opens Nextcloud login page.
|
|
2. User clicks `Forgot password`.
|
|
3. User receives reset email.
|
|
4. User sets a new password.
|
|
5. User logs in with new password.
|
|
|
|
### Expected result - Starting as Nextcloud User
|
|
|
|
1. Password reset email arrives.
|
|
2. New password works.
|
|
3. User can access account.
|
|
4. Qortal pages show view-only mode until wallet is linked/imported.
|
|
|
|
---
|
|
|
|
## 2) Existing Qortal Account + Invite Token (new cloud user)
|
|
|
|
Use this when policy requires invite/allowlist and user is not pre-allowlisted. This method is for an existing Qortal user, who obtains an 'invite token' from the Nextcloud Admin, and the server policy allows new account creation via Qortal accounts.
|
|
|
|
### Required policy - Starting with Qortal account (invite token)
|
|
|
|
1. `OIDC_POLICY_MODE=auto_provision`
|
|
2. Guard set to `invite_or_allowlist`
|
|
|
|
### Setup - Starting with Qortal account (invite token)
|
|
|
|
1. Admin creates an invite token in Qortal Integration admin panel.
|
|
2. Admin sends invite token to user.
|
|
|
|
### User flow - Starting with Qortal account (invite token)
|
|
|
|
1. User clicks `Login with Qortal`.
|
|
2. Select `NEW cloud user`.
|
|
3. Select `Invite Token`.
|
|
4. Choose wallet method:
|
|
- `Backup file` (default), or
|
|
- `Seed phrase`.
|
|
5. Enter wallet password + invite token.
|
|
6. Enter Nextcloud user fields (user ID/display name/email) if shown.
|
|
7. Continue.
|
|
|
|
### Expected result - Starting with Qortal account (invite token)
|
|
|
|
1. Login succeeds.
|
|
2. New Nextcloud user is created.
|
|
3. Mapping is created between Qortal address and Nextcloud user.
|
|
4. Re-login with same Qortal account goes directly to that Nextcloud user.
|
|
|
|
---
|
|
|
|
## 3) Existing Qortal Account + Admin Allowlist (new cloud user)
|
|
|
|
Use this when guard is enabled but you want no invite token for this user. In this option the new user gives their Qortal address to the Nextcloud admin, who adds it to a whitelist then tells the user.
|
|
|
|
### Required policy - Starting with Qortal Account (whitelisted)
|
|
|
|
1. `OIDC_POLICY_MODE=auto_provision`
|
|
2. Guard set to `invite_or_allowlist`
|
|
|
|
### Setup - Starting with Qortal Account (whitelisted)
|
|
|
|
1. User shares Qortal address with admin.
|
|
2. Admin adds that address to allowlist in Qortal Integration admin panel.
|
|
|
|
### User flow - Starting with Qortal Account (whitelisted)
|
|
|
|
1. User clicks `Login with Qortal`.
|
|
2. Select `NEW cloud user`.
|
|
3. Select `Pre-Authorized Qortal Account`.
|
|
4. Choose wallet method:
|
|
- `Backup file` (default), or
|
|
- `Seed phrase`.
|
|
5. Enter wallet password.
|
|
6. Enter Nextcloud user fields (user ID/display name/email) if shown.
|
|
7. Continue.
|
|
|
|
### Expected result - Starting with Qortal Account (whitelisted)
|
|
|
|
1. Login succeeds without invite token.
|
|
2. New Nextcloud user is created.
|
|
3. Mapping is created between allowlisted Qortal address and new Nextcloud user.
|
|
|
|
---
|
|
|
|
## Quick failure checks
|
|
|
|
If you get `invite_or_allowlist_required`:
|
|
|
|
1. Confirm policy is `auto_provision`.
|
|
2. Confirm guard is `invite_or_allowlist`.
|
|
3. Confirm invite token is valid OR address is actually in allowlist.
|
|
|
|
If you get OIDC `No matching key found in JWKS`:
|
|
|
|
1. Ensure broker JWKS contains the same `kid` used in ID token header.
|
|
2. Restart broker after key/kid changes.
|
|
|
|
If you get `identity provider failed to authenticate`:
|
|
|
|
1. Verify `trusted_domains`, `trusted_proxies`, and `overwrite.cli.url`.
|
|
2. Confirm OIDC issuer/redirect URLs match public URL exactly.
|