Token documentation and configuration examples

README.md

@@ -70,6 +70,57 @@ vmpooler provides an API and web front-end (dashboard) on port `:4567`.  See the
 
 vmpooler provides a REST API for VM management.  The following examples use `curl` for communication.
 
+#### Token operations
+
+Token-based authentication can be used when requesting or modifying VMs.  The `/token` route can be used to create, query, or delete tokens.  See the provided YAML configuration example, [vmpooler.yaml.example](vmpooler.yaml.example), for information on configuring an authentication store to use when performing token operations.
+
+##### GET /token/<token>
+
+Get information about an existing token.
+
+```
+$ curl -u sschneid --url vmpooler.company.com/token/utpg2i2xswor6h8ttjhu3d47z53yy47y
+Enter host password for user 'sschneid':
+```
+```json
+{
+  "ok": true,
+  "utpg2i2xswor6h8ttjhu3d47z53yy47y": {
+    "user": "sschneid",
+    "timestamp": "2015-04-28 19:17:47 -0700"
+  }
+}
+```
+
+##### POST /token
+
+Generate a new authentication token.
+
+```
+$ curl -X POST -u sschneid --url vmpooler.company.com/token
+Enter host password for user 'sschneid':
+```
+```json
+{
+    "ok": true,
+    "token": "utpg2i2xswor6h8ttjhu3d47z53yy47y"
+}
+```
+
+##### DELETE /token/<token>
+
+Delete an authentication token.
+
+```
+$ curl -X DELETE -u sschneid --url vmpooler.company.com/token/utpg2i2xswor6h8ttjhu3d47z53yy47y
+Enter host password for user 'sschneid':
+```
+```json
+{
+  "ok": true
+}
+```
+
 #### VM operations
 
 ##### GET /vm
@@ -90,6 +141,8 @@ $ curl --url vmpooler.company.com/vm
 
 Useful for batch operations; post JSON (see format below), get back VMs.
 
+If an authentication store is configured, an authentication token supplied via the `X-AUTH-TOKEN` HTTP header will modify a VM's default lifetime.  See the provided YAML configuration example, [vmpooler.yaml.example](vmpooler.yaml.example), and the 'token operations' section above for more information.
+
 ```
 $ curl -d '{"debian-7-i386":"2","debian-7-x86_64":"1"}' --url vmpooler.company.com/vm
 ```
@@ -177,6 +230,8 @@ parameter | description | required structure
 
 Any modifications can be verified using the [GET /vm/<hostname>](#get-vmhostname) endpoint.
 
+If an authentication store is configured, an authentication token is required (via the `X-AUTH-TOKEN` HTTP header) to access this route.  See the provided YAML configuration example, [vmpooler.yaml.example](vmpooler.yaml.example), and the 'token operations' section above for more information.
+
 ```
 $ curl -X PUT -d '{"lifetime":"2"}' --url vmpooler.company.com/vm/fq6qlpjlsskycq6
 ```

vmpooler.yaml.example

@@ -73,6 +73,39 @@
 :graphite:
   server: 'graphite.company.com'
 
+# :auth:
+#
+# This section contains information related to authenticating users
+# for token operations.
+#
+# Currently the only supported provider is LDAP; the following parameters
+# will all be under an ':ldap:' subsection (see example below).
+#
+# Available configuration parameters:
+#
+#   - host
+#     The FQDN hostname of the LDAP server.
+#
+#   - port
+#     The port used to connect to the LDAP service.
+#     (optional; default: '389')
+#
+#   - base
+#     The base DN used for LDAP searches.
+#
+#   - user_object
+#     The LDAP object-type used to designate a user object.
+
+# Example:
+
+:auth:
+  provider: 'ldap'
+  :ldap:
+    host: 'ldap.company.com'
+    port: 389
+    base: 'ou=users,dc=company,dc=com'
+    user_object: 'uid'
+
 # :config:
 #
 # This section contains global configuration information.
@@ -107,6 +140,10 @@
 #     How long (in hours) to keep VMs in 'running' queues before destroying.
 #     (optional; default: '24')
 #
+#   - vm_lifetime_auth
+#     Same as vm_lifetime, but applied if a valid authentication token is
+#     included during the request.
+#
 #   - domain
 #     If set, returns a top-level 'domain' JSON key in POST requests
 
@@ -119,6 +156,7 @@
   timeout: 15
   vm_checktime: 15
   vm_lifetime: 12
+  vm_lifetime_auth: 24
   domain: 'company.com'
 
 # :pools: