view mod_auth_http/README.markdown @ 4877:adc6241e5d16

mod_measure_process: Report the enforced limit The soft limit is what the kernel actually enforces, while the hard limit is is how far you can change the soft limit without privileges. Unless the process dynamically adjusts the soft limit, knowing the hard limit is not as useful as knowing the soft limit. Reporting the soft limit and the number of in-use FDs allows placing alerts on expressions like 'process_open_fds / process_max_fds >= 0.95'
author Kim Alvefur <zash@zash.se>
date Tue, 18 Jan 2022 18:55:20 +0100
parents 1da63fe35ef3
children
line wrap: on
line source

---
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.

  Method          HTTP method Success codes   Error codes       Response
  --------        ----        ---             ----------------- -----------------------------------------------------------------
  register        POST        201             409 (user exists)
  check\_password GET         200                               A text string of `true` if the user exists, or `false` otherwise.
  user\_exists    GET         200                               A text string of `true` if the user exists, or `false` otherwise.
  set\_password   POST        200, 201 or 204
  remove\_user    POST        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.