129 lines
2.5 KiB
Markdown
129 lines
2.5 KiB
Markdown
---
|
|
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.
|