[drill] 01/02: Update 010-rest-api-introduction.md

[vo...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

volodymyr pushed a commit to branch gh-pages
in repository https://gitbox.apache.org/repos/asf/drill.git

commit 4833419235acf499f2aa574f18b453de333e8e4d
Author: Dobes Vandermeer <do...@gmail.com>
AuthorDate: Wed Feb 12 14:36:31 2020 -0800

    Update 010-rest-api-introduction.md
---
 .../rest-api/010-rest-api-introduction.md          | 67 ++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/_docs/developer-information/rest-api/010-rest-api-introduction.md b/_docs/developer-information/rest-api/010-rest-api-introduction.md
index a57a5f7..eb9aa06 100644
--- a/_docs/developer-information/rest-api/010-rest-api-introduction.md
+++ b/_docs/developer-information/rest-api/010-rest-api-introduction.md
@@ -481,4 +481,71 @@ Enclose option values of kind STRING in double quotation marks.
 
  -->
 
+## Authenticating REST API requests
+
+If drill has authentication enabled, you will have to supply credentials when you use the REST API.
+
+### Basic authentication
+
+Apache Drill versions 1.18 and higher support HTTP's "Basic" authentication system, sendind the username & password in the `Authorization` header, encoded to base64 and joined using `:`.
+
+Basic authentication support is controlled using `drill-override.conf`.  Add the string `"BASIC"` to `http.auth.mechanisms`.  Note that if the field is not currently set, it defaults to having `"FORM"` in it, so you probably want to include `"FORM"` if you set this field, so that Web UI users can still use the login form.
+
+Example:
+
+```
+http: {
+    enabled: true,
+    auth: {
+        # Http Auth mechanisms to configure. If not provided but user.auth is enabled
+        # then default value is ["FORM"].
+        mechanisms: ["BASIC", "FORM"]
+    }
+}
+```
+
+To authenticate requests using Basic authentication, send the appropriate `Authorization` header with each request using your HTTP client's options:
+
+    curl -kv \
+           -u drilluser:drillpassword  \
+           -X POST \
+           -H "Content-Type: application/json" \
+           -d '{"queryType":"SQL", "query": "select * from sys.version"}' \
+           http://localhost:8047/query.json
+
+### Form based authentication
+
+Form based authentication is enabled or disabled using `drill-override.conf`.  Add the string `"FORM"` to `http.auth.mechanisms` if it is set.  If `http.auth.mechanisms` is not set, `"FORM"` is enabled by default.
+
+Example:
+
+```
+http: {
+    enabled: true,
+    auth: {
+        # Http Auth mechanisms to configure. If not provided but user.auth is enabled
+        # then default value is ["FORM"].
+        mechanisms: ["BASIC", "FORM"]
+    }
+}
+```
+
+To authenticate requests using form-based authentication, you must use an HTTP client that saves cookies between requests.  Simulate a form submission to the same URL used in the Web UI / Console (`/j_security_check`)
+
+    curl -X POST \
+        -H "Content-Type: application/x-www-form-urlencoded" \
+        -k -c cookies.txt -s \
+        -d "j_username=drilluser" \
+        -d "j_password=drillpassword" \
+        http://localhost:8047/j_security_check
+
+
+In subsequent requests, use the cookie returned from that request:
+
+    curl -kv \
+           -b cookies.txt  \
+           -X POST \
+           -H "Content-Type: application/json" \
+           -d '{"queryType":"SQL", "query": "select * from sys.version"}' \
+           http://localhost:8047/query.json