add detailed doc for authentication, authorization

docs/30_Usage.md

@@ -201,6 +201,55 @@ INSTRUCTION:
 
 ```
 
-### Try it
+## Try it
 
 Execute the script `./tests/example_01_simple_get.sh` to see a basic example.
+
+## Authentication
+
+If you access protected applications or APIs that require an authentication or authorization you can send credentials or tokens to login / authorize.
+
+See also the examples in the next page that show different authorization types.
+
+#### Basic authentication
+
+You should use the function `http.setAuth "<USER>:<PASSWORD>"`. This will add `-u "<USER>:<PASSWORD>"` in your curl requests.
+
+Parameters:
+
+* `"<USER>:<PASSWORD>"`: give a single string with Username + `:` + password in clear text.
+
+Remove basic auth:
+
+Use `http.setAuth` (without parameters) to remove the -u parameter for the next request(s).
+
+#### Authorization header
+
+A few authorization mechanisms use the variable `Authorization` in the request header.
+For those use `http.setAuthorization <TYPE> <TOKEN|HASH>`. It will insert the curl parameter -H `Authorization: <TYPE> <TOKEN|HASH>`.
+
+Parameters:
+
+* As TYPE you can use Basic|Bearer|Negotiate|...
+* The 2nd param is the token or hased "<USER>:<PASSWORD>". A token is added as is. If a password must be encoded/ crypted you need put the encoded string here.
+
+Remove authorization header:
+
+Use `http.setAuthorization` (without parameters) to remove the authorization header for the next request(s).
+
+#### Other Authorizatins
+
+If a backend needs another Variable in the request header for authorization then there is the function `http.addHeader <HEADER_LINE>`. With it you can put multiple request header variables for all your next resquests - not only for authorizations.
+
+Parameters:
+
+* `"<HEADER_LINE>"` a single string with the complete line to add.
+
+Example:
+
+`http.addHeader "PRIVATE-TOKEN: glpat-12345678"`
+
+Remove custom header:
+
+There is no way to remove a single header line that was added once.
+But you can use `http.init` to start over.