Add custom HTTP header for API authentication

5 files changed, 37 insertions, 5 deletions

diff --git a/app/constants.php b/app/constants.php
index 08759cbd..df57fe30 100644
--- a/app/constants.php
+++ b/app/constants.php
@@ -76,3 +76,6 @@ defined('FILES_DIR') or define('FILES_DIR', 'data/files/');
 
 // Escape html inside markdown text
 defined('MARKDOWN_ESCAPE_HTML') or define('MARKDOWN_ESCAPE_HTML', true);
+
+// API alternative authentication header, the default is HTTP Basic Authentication defined in RFC2617
+defined('API_AUTHENTICATION_HEADER') or define('API_AUTHENTICATION_HEADER', '');
diff --git a/config.default.php b/config.default.php
index 92b61bde..7f379f5c 100644
--- a/config.default.php
+++ b/config.default.php
@@ -132,3 +132,6 @@ define('ENABLE_XFRAME', true);
 
 // Escape html inside markdown text
 define('MARKDOWN_ESCAPE_HTML', true);
+
+// API alternative authentication header, the default is HTTP Basic Authentication defined in RFC2617
+define('API_AUTHENTICATION_HEADER', '');
diff --git a/docs/api-json-rpc.markdown b/docs/api-json-rpc.markdown
index 98ce48d7..a126b8b5 100644
--- a/docs/api-json-rpc.markdown
+++ b/docs/api-json-rpc.markdown
@@ -12,17 +12,39 @@ Almost the same thing as XML-RPC but with the JSON format.
 We use the [version 2 of the protocol](http://www.jsonrpc.org/specification).
 You must call the API with a `POST` HTTP request.
 
-Credentials
------------
+Authentication
+--------------
+
+### Default method (HTTP Basic)
 
 The API credentials are available on the settings page.
 
-- API end-point: `http://YOUR_SERVER/jsonrpc.php`
+- API end-point: `https://YOUR_SERVER/jsonrpc.php`
 - Username: `jsonrpc`
-- Password: Random token (API token on the settings page)
+- Password: API token on the settings page
 
 The API use the [HTTP Basic Authentication Scheme described in the RFC2617](http://www.ietf.org/rfc/rfc2617.txt).
-If there is an authentication error, you got an HTTP status code `401 Not Authorized`.
+If there is an authentication error, you will receive the HTTP status code `401 Not Authorized`.
+
+### Custom HTTP header
+
+You can use an alternative HTTP header for the authentication if your server have a very specific configuration.
+
+- The header name can be anything you want, by example `X-API-Auth`.
+- The header value is the `username:password` encoded in Base64.
+
+Configuration:
+
+1. Define your custom header in your `config.php`: `define('API_AUTHENTICATION_HEADER', 'X-API-Auth');`
+2. Encode the credentials in Base64, example with PHP `base64_encode('jsonrpc:19ffd9709d03ce50675c3a43d1c49c1ac207f4bc45f06c5b2701fbdf8929);`
+3. Test with curl:
+
+```bash
+curl \
+-H 'X-API-Auth: anNvbnJwYzoxOWZmZDk3MDlkMDNjZTUwNjc1YzNhNDNkMWM0OWMxYWMyMDdmNGJjNDVmMDZjNWIyNzAxZmJkZjg5Mjk=' \
+-d '{"jsonrpc": "2.0", "method": "getAllProjects", "id": 1}' \
+http://localhost/kanboard/jsonrpc.php
+```
 
 Examples
 --------
diff --git a/docs/config.markdown b/docs/config.markdown
index b11e005e..34c423c4 100644
--- a/docs/config.markdown
+++ b/docs/config.markdown
@@ -191,4 +191,7 @@ Various settings
 ```php
 // Escape html inside markdown text
 define('MARKDOWN_ESCAPE_HTML', true);
+
+// API alternative authentication header, the default is HTTP Basic Authentication defined in RFC2617
+define('API_AUTHENTICATION_HEADER', '');
 ```
diff --git a/jsonrpc.php b/jsonrpc.php
index c3de1fc5..6c4b9d3d 100644
--- a/jsonrpc.php
+++ b/jsonrpc.php
@@ -3,6 +3,7 @@
 require __DIR__.'/app/common.php';
 
 $server = new JsonRPC\Server;
+$server->setAuthenticationHeader(API_AUTHENTICATION_HEADER);
 $server->before('authentication');
 $server->attach(new Api\Action($container));
 $server->attach(new Api\App($container));