mod_auth_http

Overview

This authentication module allows Prosody to authenticate users against an external HTTP service.

Configuration

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.