100 lines
3.4 KiB
Markdown
100 lines
3.4 KiB
Markdown
# 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`):
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
curl -sS -X POST http://localhost:3191/apps/register \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"name":"qortal-nextcloud-integration"}'
|
|
```
|
|
|
|
Response shape:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```bash
|
|
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"}'
|
|
```
|