67 lines
2.0 KiB
Markdown
67 lines
2.0 KiB
Markdown
# zonegift - all zones are created equal
|
|
|
|
zonegift is a web API to manage your zone. It aims to Keep It Simple Stupid (KISS).
|
|
|
|
ATTENTION: This is very early work! There is no DNS software integration at the moment, just a JSON API skeleton. So basically it does really nothing.
|
|
|
|
# Authentication
|
|
|
|
Authentication is managed by the HTTP reverse proxy securing access to zonegift. If a `REMOTE_USER` HTTP header is found, it will be used as a reference for the currently logged in username. The API can only be used when the client is authenticated.
|
|
|
|
The examples in the next subsections are based on the [nginx](https://nginx.org) web server. However, this kind of setup would work with any HTTP reverse proxy.
|
|
|
|
## Basic auth
|
|
|
|
HTTP Basic Auth is a very simple and standard authentication mechanism. It matches user-supplied username/password with a file in which the password is hashed.
|
|
|
|
Example /etc/nginx/users.db (user/password):
|
|
|
|
```
|
|
user:is1LYO/kerx8I
|
|
```
|
|
|
|
Example nginx configuration block for zonegift:
|
|
|
|
```
|
|
location /api {
|
|
auth_basic "NEED TO LOGIN";
|
|
auth_basic_user_file "users.test";
|
|
proxy_set_header REMOTE_USER $remote_user;
|
|
proxy_pass http://localhost:3030;
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Forwarded-For $remote_addr;
|
|
proxy_intercept_errors on;
|
|
recursive_error_pages on;
|
|
}
|
|
```
|
|
|
|
## Authentication by subrequest
|
|
|
|
TODO: How to let nginx decide on authentication by performing an HTTP auth request
|
|
This allows to plug in a 3rd party authentication mechanism that speaks HTTP.
|
|
|
|
# API
|
|
|
|
There is an API endpoint exposed under the route "/api". You can try it out with the JSON payloads located in the tests/ folder. There is a convenient wrapper script to use those, called `curl.sh`:
|
|
|
|
```
|
|
$ ./curl.sh
|
|
Available test payloads:
|
|
bogus_command
|
|
bogus_method
|
|
stats
|
|
version
|
|
zone_list
|
|
zone_read
|
|
$ ./curl.sh version
|
|
0.0.1
|
|
$ ./curl.sh bogus_method
|
|
curl: (22) The requested URL returned error: 400 Bad Request
|
|
HTTP ERROR
|
|
$ ./curl.sh bogus_command
|
|
curl: (22) The requested URL returned error: 400 Bad Request
|
|
HTTP ERROR
|
|
```
|
|
|
|
The API has no specification yet.
|