#9 Added user dashboard and API info
parent
95ed1d02a9
commit
7e76bffa3e
GPG Key ID:
DF773B3F4A88DA86
105
USAGE.md
105
USAGE.md
|
|
@ -1,8 +1,8 @@
|
||||||
# Wagon usage
|
# Wagon usage
|
||||||
|
|
||||||
This hasn't been written yet, but it will contain good information on all the dashboards and API endpoints.
|
## 1. User service
|
||||||
|
|
||||||
## User dashboard
|
### 1.1. Frontend
|
||||||
|
|
||||||
The sample frontend shows a user's devices in a table like this:
|
The sample frontend shows a user's devices in a table like this:
|
||||||
|
|
||||||
|
|
@ -15,18 +15,111 @@ The sample frontend shows a user's devices in a table like this:
|
||||||
|
|
||||||
The first column is each host's domain name. The next column has links for users to download an SSL cert/key for that device. Finally there is a button to delete that host. (Every host has a DELETE button, but the backend will not let you delete the device you are connecting from)
|
The first column is each host's domain name. The next column has links for users to download an SSL cert/key for that device. Finally there is a button to delete that host. (Every host has a DELETE button, but the backend will not let you delete the device you are connecting from)
|
||||||
|
|
||||||
Below the devices list is a place to add a device:
|
Below the devices list is a self-explanitory place to add a device:
|
||||||
|
|
||||||
|
> ### Add a peer
|
||||||
|
>
|
||||||
|
> To add a new peer, type in a hostname and click add. The hostname must be 3-10 lowercase letters and numbers `/[a-z0-9]{3,10}/`. Keep it short for your own sake!
|
||||||
|
>
|
||||||
|
> _______________ [ADD]
|
||||||
|
>
|
||||||
|
> After clicking "Add", the new peer's config will appear below. Copy and paste it into your wireguard client and start the service. **This configuration will not be shown again!** If you lose the config, you will need to delete the peer and recreate it.
|
||||||
|
|
||||||
|
As it says, there is no renaming of peers (yet), only deleting and re-adding.
|
||||||
|
|
||||||
|
### 1.2. API
|
||||||
|
|
||||||
|
There are four endpoints that power the user dashboard. Since the IP source address is used for authentication, a token must be provided when making changes (adding/deleting peers) to prevent IP spoofing. That is, a hacker at `10.99.6.1` should not be able to change our user's `10.99.1.0/24` network. However, this hacker could spoof their source IP to send a "delete" request and not care about receiving a response.
|
||||||
|
|
||||||
|
To prevent this, a token is generated on the server and sent to the user when requesting the `list`. This token can only be recieved by the actual source address, so a user can make a `list` request, get the token, and use it to authenticate `add` and `delete` requests. A spoofer would never recieve the token and not be able to send such changes. Thus, to `add` or `delete` a peer, two requests must be made; one for the token, and one for the actual command.
|
||||||
|
|
||||||
|
#### 1.2.1. List devices
|
||||||
|
|
||||||
|
- **REQUEST:** `GET /`
|
||||||
|
- **FILE:** `back/lib/dashboard/peer/list`
|
||||||
|
- **QUERYSTRING:** None
|
||||||
|
- **RESPONSE:** JSON with a token and array of user peers:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
|
||||||
|
"peers": [
|
||||||
|
{
|
||||||
|
"domain": "myhost1.myuser.mynet",
|
||||||
|
"ipv4": "10.99.1.1",
|
||||||
|
"ipv6": "fd69:1337:0:420:f4:99:1:1",
|
||||||
|
"pubkey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX="
|
||||||
|
},{
|
||||||
|
"domain": "myhost2.myuser.mynet",
|
||||||
|
"ipv4": "10.99.1.2",
|
||||||
|
"ipv6": "fd69:1337:0:420:f4:99:1:2",
|
||||||
|
"pubkey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX="
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 1.2.2. Add device
|
||||||
|
|
||||||
|
- **REQUEST:** `POST /`
|
||||||
|
- **FILE:** `back/lib/dashboard/peer/add`
|
||||||
|
- **QUERYSTRING:** `?token=XXXX&name=mynewhostname`
|
||||||
|
- `token`: The token provided in a `list devices` response
|
||||||
|
- `name`: The new hostname for the peer
|
||||||
|
- **RESPONSE:**
|
||||||
|
- **202:** Success
|
||||||
|
- **403:** Wrong token provided
|
||||||
|
- **409:** Hostname already exists
|
||||||
|
- **500:** Other server-side error
|
||||||
|
|
||||||
|
#### 1.2.3. Delete device
|
||||||
|
|
||||||
|
- **REQUEST:** `DELETE /`
|
||||||
|
- **FILE:** `back/lib/dashboard/peer/del`
|
||||||
|
- **QUERYSTRING:** `?token=XXXX&pubkey=XXXX`
|
||||||
|
- `token`: The token provided in a `list devices` response
|
||||||
|
- `pubkey`: The peer's wireguard public key
|
||||||
|
- **RESPONSE:**
|
||||||
|
- **202:** Success
|
||||||
|
- **403:** Wrong token provided
|
||||||
|
- **500:** Other server-side error
|
||||||
|
|
||||||
|
### 1.2.4. Get SSL certs
|
||||||
|
|
||||||
|
- **REQUEST:** `GET /ssl`
|
||||||
|
- **FILE:** `back/lib/dashboard/ssl`
|
||||||
|
- **QUERYSTRING:** `?host=myhostname&ext=crt`
|
||||||
|
- `host`: get file for which host?
|
||||||
|
- `ext`: `crt` for certs or `key` for keys
|
||||||
|
- **RESPONSE:** The requested SSL certificate or key file
|
||||||
|
|
||||||
|
## 2. Admin service
|
||||||
|
|
||||||
|
### 2.1. Dashboard
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## User API
|
### 2.2 API
|
||||||
|
|
||||||
|
#### 2.2.1. List devices
|
||||||
|
|
||||||
TODO
|
TODO
|
||||||
|
|
||||||
## Admin dashboard
|
#### 2.2.2. Add device
|
||||||
|
|
||||||
TODO
|
TODO
|
||||||
|
|
||||||
## Admin API
|
#### 2.2.3. Delete device
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
||||||
|
#### 2.2.4. List users
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
||||||
|
#### 2.2.5. Add user
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
||||||
|
#### 2.2.6. Delete user
|
||||||
|
|
||||||
TODO
|
TODO
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue