Prosody auth WIP.

prosody-modules/mod_auth_http/README.markdown

@@ -0,0 +1,128 @@
+---
+labels:
+- Stage-Alpha
+summary: "Authenticate users against an external HTTP API"
+...
+
+# Overview
+
+This authentication module allows Prosody to authenticate users against
+an external HTTP service.
+
+# Configuration
+
+``` lua
+VirtualHost "example.com"
+  authentication = "http"
+  http_auth_url = "http://example.com/auth"
+```
+
+If the API requires Prosody to authenticate, you can provide static
+credentials using HTTP Basic authentication, like so:
+
+```
+http_auth_credentials = "prosody:secret-password"
+```
+
+# Developers
+
+This section contains information for developers who wish to implement a
+HTTP service that Prosody can use for authentication.
+
+## Protocol
+
+Prosody will make a HTTP request to the configured API URL with an
+appended `/METHOD` where `METHOD` is one of the methods described below.
+
+GET methods must expect a series of URL-encoded query parameters, while
+POST requests will receive an URL-encoded form (i.e.
+`application/x-www-form-urlencoded`).
+
+## Parameters
+
+user
+: The username, e.g. `stephanie` for the JID `stephanie@example.com`.
+
+server
+: The host part of the user's JID, e.g. `example.com` for the JID
+  `stephanie@example.com`.
+
+pass
+: For methods that verify or set a user's password, the password will
+  be supplied in this parameter, otherwise it is not set.
+
+## Methods
+
+The only mandatory methods that the service must implement are `check_password`
+and `user_exists`. Unsupported methods should return a HTTP status code
+of `501 Not Implemented`, but other error codes will also be handled by
+Prosody.
+
+### register
+
+**HTTP method:**
+: POST
+
+**Success codes:**
+: 201
+
+**Error codes:**
+: 409 (user exists)
+
+### check_password
+
+**HTTP method:**
+: GET
+
+**Success codes:**
+: 200
+
+**Response:**
+: A text string of `true` if the user exists, or `false` otherwise.
+
+### user_exists
+
+**HTTP method:**
+: GET
+
+**Success codes:**
+: 200
+
+**Response:**
+: A text string of `true` if the user exists, or `false` otherwise.
+
+### set_password
+
+**HTTP method:**
+: POST
+
+**Success codes:**
+: 200, 201, or 204
+
+### remove_user
+
+**HTTP method:**
+: POST
+
+**Success codes:**
+: 200, 201 or 204
+
+## Examples
+
+With the following configuration:
+
+```
+authentication = "http"
+http_auth_url = "https://auth.example.net/api"
+
+If a user connects and tries to log in to Prosody as "romeo@example.net"
+with the password "iheartjuliet", Prosody would make the following HTTP
+request:
+
+```
+https://auth.example.net/api/check_password?user=romeo&server=example.net&pass=iheartjuliet
+```
+
+# Compatibility
+
+Requires Prosody 0.11.0 or later.